androidx.ui.graphics

Classes

Color

The Color class contains color information to be used while painting in Canvas.

ColorFilter

Creates a color filter that applies the blend mode given as the second argument.

FixedScale

ScaleFit implementation that always scales the dimension by the provided fixed floating point value

LinearGradient

Brush implementation used to apply a linear gradient on a given Paint

MaskFilter

Paint

Path

Picture

An object representing a sequence of recorded graphical operations.

PictureRecorder

Creates a new idle PictureRecorder.

RadialGradient

Brush implementation used to apply a radial gradient on a given Paint

Shader

Inline class used to represent primitives used to render gradients or to tile an Image

ShaderBrush

Brush implementation that wraps and applies a the provided shader to a Paint

Shadow

A single shadow.

SolidColor

Type-aliases

ColorStop

NativeCanvas

An interface for recording graphical operations.

NativeImage

This class is created by the engine, and should not be instantiated or extended directly.

NativeShader

Class that represents the corresponding Shader implementation on a platform.

NativeTileMode

Enums

BlendMode

Algorithms to use when painting on the canvas.

BlurStyle

ClipOp

Defines how a new clip region should be merged with the existing clip region.

FilterQuality

ImageByteFormat

The format in which image bytes should be returned when using Image.toByteData.

ImageConfig

Possible Image configurations.

ImageRepeat

How to paint any portions of a box not covered by an image.

PaintingStyle

Strategies for painting shapes and paths on a canvas.

PathFillType

Determines the winding rule that decides how the interior of a Path is calculated.

PathOperation

Strategies for combining paths.

PointMode

Used by Canvas.drawPoints.

StrokeCap

StrokeJoin

TileMode

Top-level functions summary

Canvas
Canvas(image: Image)

Create a new Canvas instance that targets its drawing commands to the provided Image

Canvas
Canvas(recorder: PictureRecorder, cullRect: Rect = Rect.largest)

Create a new Canvas instance that targets its drawing commands to the provided PictureRecorder in order to be replayed later

Canvas

Color
Color(red: Float, green: Float, blue: Float, alpha: Float = 1f, colorSpace: ColorSpace = ColorSpaces.Srgb)

Create a Color by passing individual red, green, blue, alpha, and colorSpace components.

Color
Color(color: Int)

Creates a new Color instance from an ARGB color int.

Color
Color(color: Long)

Creates a new Color instance from an ARGB color int.

Color
Color(red: Int, green: Int, blue: Int, alpha: Int = 0xFF)

Creates a new Color instance from an ARGB color components.

LinearGradient
HorizontalGradient(colors: List<Color>, startX: Px, endX: Px, tileMode: TileMode = TileMode.Clamp)

Creates a horizontal gradient with the given colors evenly dispersed within the gradient

Brush
HorizontalGradient(vararg colorStops: ColorStop, startX: Px, endX: Px, tileMode: TileMode = TileMode.Clamp)

Creates a horizontal gradient with the given colors dispersed at the provided offset defined in the ColorStop

Image
Image(width: Int, height: Int, config: ImageConfig = ImageConfig.Argb8888, hasAlpha: Boolean = true, colorSpace: ColorSpace = ColorSpaces.Srgb)

Shader
ImageShader(image: Image, tileModeX: TileMode = TileMode.Clamp, tileModeY: TileMode = TileMode.Clamp)

LinearGradient
LinearGradient(colors: List<Color>, startX: Px, startY: Px, endX: Px, endY: Px, tileMode: TileMode = TileMode.Clamp)

Creates a linear gradient with the provided colors along the given start and end coordinates.

LinearGradient
LinearGradient(vararg colorStops: ColorStop, startX: Px, startY: Px, endX: Px, endY: Px, tileMode: TileMode = TileMode.Clamp)

Creates a linear gradient with the provided colors along the given start and end coordinates.

Shader
LinearGradientShader(from: Offset, to: Offset, colors: List<Color>, colorStops: List<Float>? = null, tileMode: TileMode = TileMode.Clamp)

Creates a linear gradient from from to to.

NativeTileMode

NativeTileMode

NativeTileMode

RadialGradient
RadialGradient(vararg colorStops: ColorStop, centerX: Float, centerY: Float, radius: Float, tileMode: TileMode = TileMode.Clamp)

Creates a radial gradient with the given colors at the provided offset defined in the ColorStop

RadialGradient
RadialGradient(colors: List<Color>, centerX: Float, centerY: Float, radius: Float, tileMode: TileMode = TileMode.Clamp)

Creates a radial gradient with the given colors evenly dispersed within the gradient

Shader
RadialGradientShader(center: Offset, radius: Float, colors: List<Color>, colorStops: List<Float>? = null, tileMode: TileMode = TileMode.Clamp)

Creates a radial gradient centered at center that ends at radius distance from the center.

LinearGradient
VerticalGradient(colors: List<Color>, startY: Px, endY: Px, tileMode: TileMode = TileMode.Clamp)

Creates a vertical gradient with the given colors at the provided offset defined in the ColorStop Ex:

LinearGradient
VerticalGradient(vararg colorStops: ColorStop, startY: Px, endY: Px, tileMode: TileMode = TileMode.Clamp)

Creates a vertical gradient with the given colors evenly dispersed within the gradient Ex:

Image

Color
lerp(start: Color, stop: Color, fraction: Float)

Linear interpolate between two Colors, start and stop with fraction fraction between the two.

Shadow
lerp(start: Shadow, stop: Shadow, fraction: Float)

Linearly interpolate two Shadows.

Extension functions summary

For Color
Float

Returns the relative luminance of this color.

Int

Converts this color to an ARGB color int.

For Canvas
Unit
Canvas.withSave(block: () -> Unit)

Saves a copy of the current transform and clip on the save stack and executes the provided lambda with the current transform applied.

Unit
Canvas.withSaveLayer(bounds: Rect, paint: Paint, block: () -> Unit)

Saves a copy of the current transform and clip on the save stack, and then creates a new group which subsequent calls will become a part of.

Top-level functions

Canvas

fun Canvas(image: Image): Canvas

Create a new Canvas instance that targets its drawing commands to the provided Image

Canvas

fun Canvas(
    recorder: PictureRecorder,
    cullRect: Rect = Rect.largest
): Canvas

Create a new Canvas instance that targets its drawing commands to the provided PictureRecorder in order to be replayed later

Canvas

fun Canvas(c: Canvas): Canvas

Color

fun Color(
    red: Float,
    green: Float,
    blue: Float,
    alpha: Float = 1f,
    colorSpace: ColorSpace = ColorSpaces.Srgb
): Color

Create a Color by passing individual red, green, blue, alpha, and colorSpace components. The default color space is SRGB and the default alpha is 1.0 (opaque). colorSpace must have a ColorSpace.componentCount of

Color

fun Color(color: Int): Color

Creates a new Color instance from an ARGB color int. The resulting color is in the sRGB color space.

Parameters
color: Int The ARGB color int to create a Color from.
Return
A non-null instance of {@link Color}

Color

fun Color(color: Long): Color

Creates a new Color instance from an ARGB color int. The resulting color is in the sRGB color space. This is useful for specifying colors with alpha greater than 0x80 in numeric form without using Long.toInt:

    val color = Color(0xFF000080)
Parameters
color: Long The 32-bit ARGB color int to create a Color from
Return
A non-null instance of {@link Color}

Color

fun Color(
    red: Int,
    green: Int,
    blue: Int,
    alpha: Int = 0xFF
): Color

Creates a new Color instance from an ARGB color components. The resulting color is in the sRGB color space. The default alpha value is 0xFF (opaque).

Return
A non-null instance of {@link Color}

HorizontalGradient

fun HorizontalGradient(
    colors: List<Color>,
    startX: Px,
    endX: Px,
    tileMode: TileMode = TileMode.Clamp
): LinearGradient

Creates a horizontal gradient with the given colors evenly dispersed within the gradient

Ex:

 HorizontalGradient(
     Color.Red,
     Color.Green,
     Color.Blue,
     startX = Px(10.0f),
     endX = Px(20.0f)
)

HorizontalGradient

fun HorizontalGradient(
    vararg colorStops: ColorStop,
    startX: Px,
    endX: Px,
    tileMode: TileMode = TileMode.Clamp
): Brush

Creates a horizontal gradient with the given colors dispersed at the provided offset defined in the ColorStop

Ex:

 HorizontalGradient(
     0.0f to Color.Red,
     0.3f to Color.Green,
     1.0f to Color.Blue,
     startX = Px.Zero,
     endX = Px(100.0f)
)

Image

fun Image(
    width: Int,
    height: Int,
    config: ImageConfig = ImageConfig.Argb8888,
    hasAlpha: Boolean = true,
    colorSpace: ColorSpace = ColorSpaces.Srgb
): Image

ImageShader

fun ImageShader(
    image: Image,
    tileModeX: TileMode = TileMode.Clamp,
    tileModeY: TileMode = TileMode.Clamp
): Shader

LinearGradient

fun LinearGradient(
    colors: List<Color>,
    startX: Px,
    startY: Px,
    endX: Px,
    endY: Px,
    tileMode: TileMode = TileMode.Clamp
): LinearGradient

Creates a linear gradient with the provided colors along the given start and end coordinates. The colors are

 LinearGradient(
     0.0f to Color.Red,
     0.3f to Color.Green,
     1.0f to Color.Blue,
     startX = Px.Zero,
     startY = Px(50.0f),
     endY = Px.Zero,
     endY = Px(100.0f)
)

LinearGradient

fun LinearGradient(
    vararg colorStops: ColorStop,
    startX: Px,
    startY: Px,
    endX: Px,
    endY: Px,
    tileMode: TileMode = TileMode.Clamp
): LinearGradient

Creates a linear gradient with the provided colors along the given start and end coordinates. The colors are dispersed at the provided offset defined in the ColorStop

 LinearGradient(
     0.0f to Color.Red,
     0.3f to Color.Green,
     1.0f to Color.Blue,
     startX = Px.Zero,
     startY = Px(50.0f),
     endY = Px.Zero,
     endY = Px(100.0f)
)

LinearGradientShader

fun LinearGradientShader(
    from: Offset,
    to: Offset,
    colors: List<Color>,
    colorStops: List<Float>? = null,
    tileMode: TileMode = TileMode.Clamp
): Shader

Creates a linear gradient from from to to.

If colorStops is provided, each value is a number from 0.0 to 1.0 that specifies where the color at the corresponding index in colors begins in the gradient. If colorStops is not provided, then the colors are dispersed evenly

The behavior before from and after to is described by the tileMode argument. For details, see the TileMode enum. If no TileMode is provided the default value of TileMode.Clamp is used

NativeClampTileMode

fun NativeClampTileMode(): NativeTileMode

NativeMirrorTileMode

fun NativeMirrorTileMode(): NativeTileMode

NativeRepeatedTileMode

fun NativeRepeatedTileMode(): NativeTileMode

RadialGradient

fun RadialGradient(
    vararg colorStops: ColorStop,
    centerX: Float,
    centerY: Float,
    radius: Float,
    tileMode: TileMode = TileMode.Clamp
): RadialGradient

Creates a radial gradient with the given colors at the provided offset defined in the ColorStop

RadialGradient(
     0.0f to Color.Red,
     0.3f to Color.Green,
     1.0f to Color.Blue,
     centerX = side1 / 2.0f,
     centerY = side2 / 2.0f,
     radius = side1 / 2.0f,
     tileMode = TileMode.Repeated
)

RadialGradient

fun RadialGradient(
    colors: List<Color>,
    centerX: Float,
    centerY: Float,
    radius: Float,
    tileMode: TileMode = TileMode.Clamp
): RadialGradient

Creates a radial gradient with the given colors evenly dispersed within the gradient

RadialGradient(
     Color.Red,
     Color.Green,
     Color.Blue,
     centerX = side1 / 2.0f,
     centerY = side2 / 2.0f,
     radius = side1 / 2.0f,
     tileMode = TileMode.Repeated
)

RadialGradientShader

fun RadialGradientShader(
    center: Offset,
    radius: Float,
    colors: List<Color>,
    colorStops: List<Float>? = null,
    tileMode: TileMode = TileMode.Clamp
): Shader

Creates a radial gradient centered at center that ends at radius distance from the center.

If colorStops is provided, each value is a number from 0.0 to 1.0 that specifies where the color at the corresponding index in colors begins in the gradient. If colorStops is not provided, then the colors are dispersed evenly

The behavior before and after the radius is described by the tileMode argument. For details, see the TileMode enum.

The behavior outside of the bounds of center +/- radius is described by the tileMode argument. For details, see the TileMode enum. If no TileMode is provided the default value of TileMode.Clamp is used

VerticalGradient

fun VerticalGradient(
    colors: List<Color>,
    startY: Px,
    endY: Px,
    tileMode: TileMode = TileMode.Clamp
): LinearGradient

Creates a vertical gradient with the given colors at the provided offset defined in the ColorStop Ex:

 VerticalGradient(
     Color.Red,
     Color.Green,
     Color.Blue,
     startY = Px.Zero,
     endY = Px(100.0f)
)

VerticalGradient

fun VerticalGradient(
    vararg colorStops: ColorStop,
    startY: Px,
    endY: Px,
    tileMode: TileMode = TileMode.Clamp
): LinearGradient

Creates a vertical gradient with the given colors evenly dispersed within the gradient Ex:

 VerticalGradient(
     Color.Red,
     Color.Green,
     Color.Blue,
     startY = Px.Zero,
     endY = Px(100.0f)
)

imageFromResource

fun imageFromResource(
    res: Resources,
    resId: Int
): Image

lerp

fun lerp(
    start: Color,
    stop: Color,
    fraction: Float
): Color

Linear interpolate between two Colors, start and stop with fraction fraction between the two. The ColorSpace of the result is always the ColorSpace of stop.

lerp

fun lerp(
    start: Shadow,
    stop: Shadow,
    fraction: Float
): Shadow

Linearly interpolate two Shadows.

Extension functions

luminance

fun Color.luminance(): Float

Returns the relative luminance of this color.

Based on the formula for relative luminance defined in WCAG 2.0, W3C Recommendation 11 December 2008.

Return
A value between 0 (darkest black) and 1 (lightest white)
Exceptions
IllegalArgumentException If the this color's color space does not use the RGB color model

toArgb

fun Color.toArgb(): Int

Converts this color to an ARGB color int. A color int is always in the sRGB color space. This implies a color space conversion is applied if needed.

Return
An ARGB color in the sRGB color space

withSave

inline fun Canvas.withSave(block: () -> Unit): Unit

Saves a copy of the current transform and clip on the save stack and executes the provided lambda with the current transform applied. Once the lambda has been executed, the transformation is popped from the stack, undoing the transformation.

See also:

Canvas.saveLayer, which does the same thing but additionally also groups the commands

withSaveLayer

inline fun Canvas.withSaveLayer(
    bounds: Rect,
    paint: Paint,
    block: () -> Unit
): Unit

Saves a copy of the current transform and clip on the save stack, and then creates a new group which subsequent calls will become a part of. When the lambda is executed and the save stack is popped, the group will be flattened into a layer and have the given paint's Paint.colorFilter and Paint.blendMode applied.

This lets you create composite effects, for example making a group of drawing commands semi-transparent. Without using Canvas.saveLayer, each part of the group would be painted individually, so where they overlap would be darker than where they do not. By using Canvas.saveLayer to group them together, they can be drawn with an opaque color at first, and then the entire group can be made transparent using the Canvas.saveLayer's paint.

Using saveLayer with clips

When a rectangular clip operation (from Canvas.clipRect) is not axis-aligned with the raster buffer, or when the clip operation is not rectalinear (e.g. because it is a rounded rectangle clip created by Canvas.clipRRect or an arbitrarily complicated path clip created by Canvas.clipPath), the edge of the clip needs to be anti-aliased.

If two draw calls overlap at the edge of such a clipped region, without using Canvas.saveLayer, the first drawing will be anti-aliased with the background first, and then the second will be anti-aliased with the result of blending the first drawing and the background. On the other hand, if Canvas.saveLayer is used immediately after establishing the clip, the second drawing will cover the first in the layer, and thus the second alone will be anti-aliased with the background when the layer is clipped and composited (when lambda is finished executing).

Performance considerations

Generally speaking, Canvas.saveLayer is relatively expensive.

There are a several different hardware architectures for GPUs (graphics processing units, the hardware that handles graphics), but most of them involve batching commands and reordering them for performance. When layers are used, they cause the rendering pipeline to have to switch render target (from one layer to another). Render target switches can flush the GPU's command buffer, which typically means that optimizations that one could get with larger batching are lost. Render target switches also generate a lot of memory churn because the GPU needs to copy out the current frame buffer contents from the part of memory that's optimized for writing, and then needs to copy it back in once the previous render target (layer) is restored.

See also: