The second Android 11 Developer Preview is now available, test it out and share your feedback.

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

Outline

Defines a simple shape, used for bounding graphical regions.

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 ImageAsset

ShaderBrush

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

Shadow

A single shadow.

SolidColor

Vertices

A set of vertex data used by Canvas.drawVertices.

Type-aliases

ColorStop

NativeCanvas

An interface for recording graphical operations.

NativeImageAsset

Handle for the underlying platform primitive for the ImageAsset implementation

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

ImageAssetConfig

Possible ImageAsset configurations.

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

VertexMode

Defines how a list of points is interpreted when drawing a set of triangles.

Top-level constants summary

const Float

Default alpha value used on Paint.

Top-level functions summary

Canvas

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

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

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

Shader
ImageShader(image: ImageAsset, 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:

ImageAsset

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 android.graphics.Bitmap
ImageAsset

Create an ImageAsset from the given Bitmap.

For Path
Unit

Adds the outline to the Path.

For Color
Color
Color.compositeOver(background: Color)

Composites this color on top of background using the Porter-Duff 'source over' mode.

Float

Returns the relative luminance of this color.

Int

Converts this color to an ARGB color int.

For Canvas
Unit
Canvas.drawOutline(outline: Outline, paint: Paint)

Draws the Outline on a 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 constants

DefaultAlpha

const val DefaultAlpha: Float

Default alpha value used on Paint. This value will draw source content fully opaque.

Value: 1.0f

Top-level functions

Canvas

fun Canvas(image: ImageAsset): Canvas

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

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)
)

ImageAsset

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

ImageShader

fun ImageShader(
    image: ImageAsset,
    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
): ImageAsset

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

addOutline

fun Path.addOutline(outline: Outline): Unit

Adds the outline to the Path.

asImageAsset

fun Bitmap.asImageAsset(): ImageAsset

Create an ImageAsset from the given Bitmap. Note this does not create a copy of the original Bitmap and changes to it will modify the returned ImageAsset

compositeOver

fun Color.compositeOver(background: Color): Color

Composites this color on top of background using the Porter-Duff 'source over' mode.

Both this and background must not be pre-multiplied, and the resulting color will also not be pre-multiplied.

The ColorSpace of the result is always the ColorSpace of background.

Return
the Color representing this composited on top of background, converted to the color space of background.

drawOutline

fun Canvas.drawOutline(
    outline: Outline,
    paint: Paint
): Unit

Draws the Outline on a Canvas.

Parameters
outline: Outline the outline to draw.
paint: Paint the paint used for the drawing.

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: