GraphicsLayer

expect class GraphicsLayer

Drawing layer used to record drawing commands in a displaylist as well as additional properties that affect the rendering of the display list. This provides an isolation boundary to divide a complex scene into smaller pieces that can be updated individually of one another without recreating the entire scene. Transformations made to a GraphicsLayer can be done without re-recording the display list.

Usage of a GraphicsLayer requires a minimum of 2 steps.

1. The GraphicsLayer must be built, which involves specifying the position alongside a list of drawing commands using GraphicsLayer.record
2. The GraphicsLayer is then drawn into another destination Canvas using GraphicsLayer.draw.

Additionally the contents of the displaylist can be transformed when it is drawn into a desintation Canvas by specifying either scaleX, scaleY, translationX, translationY, rotationX, rotationY, or rotationZ.

The rendered result of the displaylist can also be modified by configuring the GraphicsLayer.blendMode, GraphicsLayer.colorFilter, GraphicsLayer.alpha or GraphicsLayer.renderEffect

Properties

var compositingStrategy: CompositingStrategy

CompositingStrategy determines whether or not the contents of this layer are rendered into an offscreen buffer. This is useful in order to optimize alpha usages with CompositingStrategy.ModulateAlpha which will skip the overhead of an offscreen buffer but can generate different rendering results depending on whether or not the contents of the layer are overlapping. Similarly leveraging CompositingStrategy.Offscreen is useful in situations where creating an offscreen buffer is preferred usually in conjunction with BlendMode usage.

When blendMode is anything other than BlendMode.SrcOver or colorFilter is non-null, compositingStrategy's value will be overridden and is forced to CompositingStrategy.Offscreen.

var topLeft: IntOffset

Offset in pixels where this GraphicsLayer will render within a provided canvas when drawLayer is called.

var size: IntSize

Size in pixels of the GraphicsLayer. By default GraphicsLayer contents can draw outside of the bounds specified by topLeft and size, however, rasterization of this layer into an offscreen buffer will be sized according to the specified size. This is configured by calling record

var pivotOffset: Offset

Offset in pixels used as the center for any rotation or scale transformation. If this value is Offset.Unspecified, then the center of the GraphicsLayer is used relative to topLeft and size

var alpha: Float

Alpha of the content of the GraphicsLayer between 0f and 1f. Any value between 0f and 1f will be translucent, where 0f will cause the layer to be completely invisible and 1f will be entirely opaque.

var scaleX: Float

The horizontal scale of the drawn area. Default value is 1.

var scaleY: Float

The vertical scale of the drawn area. Default value is 1.

var translationX: Float

Horizontal pixel offset of the layer relative to topLeft.x. Default value is 0.

var translationY: Float

Vertical pixel offset of the layer relative to topLeft.y. Default value is 0

var shadowElevation: Float

Sets the elevation for the shadow in pixels. With the shadowElevation > 0f and Outline set, a shadow is produced. Default value is 0 and the value must not be negative. Configuring a non-zero shadowElevation enables clipping of GraphicsLayer content.

Note that if you provide a non-zero shadowElevation and if the passed Outline is concave the shadow will not be drawn on Android versions less than 10.

var ambientShadowColor: Color

Sets the color of the ambient shadow that is drawn when shadowElevation > 0f.

By default the shadow color is black. Generally, this color will be opaque so the intensity of the shadow is consistent between different graphics layers with different colors.

The opacity of the final ambient shadow is a function of the shadow caster height, the alpha channel of the ambientShadowColor (typically opaque), and the android.R.attr.ambientShadowAlpha theme attribute.

Note that this parameter is only supported on Android 9 (Pie) and above. On older versions, this property always returns Color.Black and setting new values is ignored.

var spotShadowColor: Color

Sets the color of the spot shadow that is drawn when shadowElevation > 0f.

By default the shadow color is black. Generally, this color will be opaque so the intensity of the shadow is consistent between different graphics layers with different colors.

The opacity of the final spot shadow is a function of the shadow caster height, the alpha channel of the spotShadowColor (typically opaque), and the android.R.attr.spotShadowAlpha theme attribute.

Note that this parameter is only supported on Android 9 (Pie) and above. On older versions, this property always returns Color.Black and setting new values is ignored.

var blendMode: BlendMode

BlendMode to use when drawing this layer to the destination in drawLayer. The default is BlendMode.SrcOver. Any value other than BlendMode.SrcOver will force this GraphicsLayer to use an offscreen compositing layer for rendering and is equivalent to using CompositingStrategy.Offscreen.

var colorFilter: ColorFilter?

ColorFilter applied when drawing this layer to the destination in drawLayer. Setting of this to any non-null will force this GraphicsLayer to use an offscreen compositing layer for rendering and is equivalent to using CompositingStrategy.Offscreen

val outline: Outline

Returns the outline specified by either setPathOutline or setRoundRectOutline. By default this will return Outline.Rectangle with the size of the GraphicsLayer specified by record or IntSize.Zero if record was not previously invoked.

var rotationX: Float

The rotation, in degrees, of the contents around the horizontal axis in degrees. Default value is 0.

var rotationY: Float

The rotation, in degrees, of the contents around the vertical axis in degrees. Default value is 0.

var rotationZ: Float

The rotation, in degrees, of the contents around the Z axis in degrees. Default value is 0.

var cameraDistance: Float

Sets the distance along the Z axis (orthogonal to the X/Y plane on which layers are drawn) from the camera to this layer. The camera's distance affects 3D transformations, for instance rotations around the X and Y axis. If the rotationX or rotationY properties are changed and this view is large (more than half the size of the screen), it is recommended to always use a camera distance that's greater than the height (X axis rotation) or the width (Y axis rotation) of this view.

The distance of the camera from the drawing plane can have an affect on the perspective distortion of the layer when it is rotated around the x or y axis. For example, a large distance will result in a large viewing angle, and there will not be much perspective distortion of the view as it rotates. A short distance may cause much more perspective distortion upon rotation, and can also result in some drawing artifacts if the rotated view ends up partially behind the camera (which is why the recommendation is to use a distance at least as far as the size of the view, if the view is to be rotated.)

The distance is expressed in pixels and must always be positive. Default value is DefaultCameraDistance

var clip: Boolean

Determines if the GraphicsLayer should be clipped to the rectangular bounds specified by topLeft and size. The default is false, however, contents will always be clipped to their bounds when the GraphicsLayer is promoted off an offscreen rendering buffer (i.e. CompositingStrategy.Offscreen is used, a non-null ColorFilter, RenderEffect is applied or if the BlendMode is not equivalent to BlendMode.SrcOver

var renderEffect: RenderEffect?

Configure the RenderEffect to apply to this GraphicsLayer. This will apply a visual effect to the results of the GraphicsLayer before it is drawn. For example if BlurEffect is provided, the contents will be drawn in a separate layer, then this layer will be blurred when this GraphicsLayer is drawn.

Note this parameter is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

var isReleased: Boolean

Determines if this GraphicsLayer has been released. Any attempts to use a GraphicsLayer after it has been released is an error.

Functions

fun setPathOutline(path: Path)

Specifies the given path to be configured as the outline for this GraphicsLayer. When shadowElevation is non-zero a shadow is produced with an Outline created from the provided path. Additionally if clip is true, the contents of this GraphicsLayer will be clipped to this geometry.

Parameters

fun setRoundRectOutline(
        topLeft: Offset = Offset.Zero,
        size: Size = Size.Unspecified,
        cornerRadius: Float = 0f,
    )

Configures a rounded rect outline for this GraphicsLayer. By default, topLeft is set to Size.Zero and size is set to Size.Unspecified indicating that the outline should match the size of the GraphicsLayer. When shadowElevation is non-zero a shadow is produced using an Outline created from the round rect parameters provided. Additionally if clip is true, the contents of this GraphicsLayer will be clipped to this geometry.

Parameters

fun setRectOutline(topLeft: Offset = Offset.Zero, size: Size = Size.Unspecified)

Configures a rectangular outline for this GraphicsLayer. By default, topLeft is set to Size.Zero and size is set to Size.Unspecified indicating that the outline should match the size of the GraphicsLayer. When shadowElevation is non-zero a shadow is produced using an Outline created from the round rect parameters provided. Additionally if clip is true, the contents of this GraphicsLayer will be clipped to this geometry.

Parameters

fun record(
        density: Density,
        layoutDirection: LayoutDirection,
        size: IntSize,
        block: DrawScope.() -> Unit,
    )

Constructs the display list of drawing commands into this layer that will be rendered when this GraphicsLayer is drawn elsewhere with drawLayer.

Parameters

suspend fun toImageBitmap(): ImageBitmap

Create an ImageBitmap with the contents of this GraphicsLayer instance. Note that GraphicsLayer.record must be invoked first to record drawing operations before invoking this method.

actual class GraphicsLayer internal constructor(internal val impl: GraphicsLayerImpl)

Properties

actual var isReleased: Boolean

Determines if this GraphicsLayer has been released. Any attempts to use a GraphicsLayer after it has been released is an error.

actual var compositingStrategy: CompositingStrategy

CompositingStrategy determines whether or not the contents of this layer are rendered into an offscreen buffer. This is useful in order to optimize alpha usages with CompositingStrategy.ModulateAlpha which will skip the overhead of an offscreen buffer but can generate different rendering results depending on whether or not the contents of the layer are overlapping. Similarly leveraging CompositingStrategy.Offscreen is useful in situations where creating an offscreen buffer is preferred usually in conjunction with BlendMode usage.

actual var topLeft: IntOffset

Offset in pixels where this GraphicsLayer will render within a provided canvas when drawLayer is called. This is configured by calling record

actual var size: IntSize

Size in pixels of the GraphicsLayer. By default GraphicsLayer contents can draw outside of the bounds specified by topLeft and size, however, rasterization of this layer into an offscreen buffer will be sized according to the specified size. This is configured by calling record

actual var alpha: Float

Alpha of the content of the GraphicsLayer between 0f and 1f. Any value between 0f and 1f will be translucent, where 0f will cause the layer to be completely invisible and 1f will be entirely opaque.

actual var blendMode: BlendMode

BlendMode to use when drawing this layer to the destination in drawLayer. The default is BlendMode.SrcOver. Any value other than BlendMode.SrcOver will force this GraphicsLayer to use an offscreen compositing layer for rendering and is equivalent to using CompositingStrategy.Offscreen.

actual var colorFilter: ColorFilter?

ColorFilter applied when drawing this layer to the destination in drawLayer. Setting of this to any non-null will force this GraphicsLayer to use an offscreen compositing layer for rendering and is equivalent to using CompositingStrategy.Offscreen

actual var pivotOffset: Offset

Offset in pixels used as the center for any rotation or scale transformation. If this value is Offset.Unspecified, then the center of the GraphicsLayer is used relative to topLeft and size

actual var scaleX: Float

The horizontal scale of the drawn area. Default value is 1.

actual var scaleY: Float

The vertical scale of the drawn area. Default value is 1.

actual var translationX: Float

Horizontal pixel offset of the layer relative to its left bound. Default value is 0.

actual var translationY: Float

Vertical pixel offset of the layer relative to its top bound. Default value is 0

actual var shadowElevation: Float

Sets the elevation for the shadow in pixels. With the shadowElevation > 0f and Outline set, a shadow is produced. Default value is 0 and the value must not be negative. Configuring a non-zero shadowElevation enables clipping of GraphicsLayer content.

Note that if you provide a non-zero shadowElevation and if the passed Outline is concave the shadow will not be drawn on Android versions less than 10.

actual var rotationX: Float

The rotation, in degrees, of the contents around the horizontal axis in degrees. Default value is 0.

actual var rotationY: Float

The rotation, in degrees, of the contents around the vertical axis in degrees. Default value is 0.

actual var rotationZ: Float

The rotation, in degrees, of the contents around the Z axis in degrees. Default value is 0.

actual var cameraDistance: Float

Sets the distance along the Z axis (orthogonal to the X/Y plane on which layers are drawn) from the camera to this layer. The camera's distance affects 3D transformations, for instance rotations around the X and Y axis. If the rotationX or rotationY properties are changed and this view is large (more than half the size of the screen), it is recommended to always use a camera distance that's greater than the height (X axis rotation) or the width (Y axis rotation) of this view.

The distance of the camera from the drawing plane can have an affect on the perspective distortion of the layer when it is rotated around the x or y axis. For example, a large distance will result in a large viewing angle, and there will not be much perspective distortion of the view as it rotates. A short distance may cause much more perspective distortion upon rotation, and can also result in some drawing artifacts if the rotated view ends up partially behind the camera (which is why the recommendation is to use a distance at least as far as the size of the view, if the view is to be rotated.)

The distance is expressed in pixels and must always be positive. Default value is DefaultCameraDistance

actual var clip: Boolean

Determines if the GraphicsLayer should be clipped to the rectangular bounds specified by topLeft and size or to the Outline if one is provided. The default is false. Note if elevation is provided then clipping will be enabled.

actual var renderEffect: RenderEffect?

Configure the RenderEffect to apply to this GraphicsLayer. This will apply a visual effect to the results of the GraphicsLayer before it is drawn. For example if BlurEffect is provided, the contents will be drawn in a separate layer, then this layer will be blurred when this GraphicsLayer is drawn.

Note this parameter is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

val layerId: Long

The ID of the layer. This is used by tooling to match a layer to the associated LayoutNode.

val ownerViewId: Long

The uniqueDrawingId of the owner view of this graphics layer. This is used by tooling to match a layer to the associated owner View.

actual val outline: Outline

actual var ambientShadowColor: Color

Sets the color of the ambient shadow that is drawn when shadowElevation > 0f.

By default the shadow color is black. Generally, this color will be opaque so the intensity of the shadow is consistent between different graphics layers with different colors.

The opacity of the final ambient shadow is a function of the shadow caster height, the alpha channel of the ambientShadowColor (typically opaque), and the android.R.attr.ambientShadowAlpha theme attribute.

Note that this parameter is only supported on Android 9 (Pie) and above. On older versions, this property always returns Color.Black and setting new values is ignored.

actual var spotShadowColor: Color

Sets the color of the spot shadow that is drawn when shadowElevation > 0f.

By default the shadow color is black. Generally, this color will be opaque so the intensity of the shadow is consistent between different graphics layers with different colors.

The opacity of the final spot shadow is a function of the shadow caster height, the alpha channel of the spotShadowColor (typically opaque), and the android.R.attr.spotShadowAlpha theme attribute.

Note that this parameter is only supported on Android 9 (Pie) and above. On older versions, this property always returns Color.Black and setting new values is ignored.

Functions

actual fun record(
        density: Density,
        layoutDirection: LayoutDirection,
        size: IntSize,
        block: DrawScope.() -> Unit,
    )

Constructs the display list of drawing commands into this layer that will be rendered when this GraphicsLayer is drawn elsewhere with drawLayer.

Parameters

actual fun setPathOutline(path: Path)

Specifies the given path to be configured as the outline for this GraphicsLayer. When shadowElevation is non-zero a shadow is produced using this Outline.

Parameters

actual fun setRoundRectOutline(topLeft: Offset, size: Size, cornerRadius: Float)

Configures a rounded rect outline for this GraphicsLayer. By default, topLeft is set to Size.Zero and size is set to Size.Unspecified indicating that the outline should match the size of the GraphicsLayer. When shadowElevation is non-zero a shadow is produced using an Outline created from the round rect parameters provided. Additionally if clip is true, the contents of this GraphicsLayer will be clipped to this geometry.

Parameters

actual fun setRectOutline(topLeft: Offset, size: Size)

Configures a rectangular outline for this GraphicsLayer. By default, both topLeft and size are set to Offset.Unspecified and Size.Unspecified indicating that the outline should match the bounds of the GraphicsLayer. When shadowElevation is non-zero a shadow is produced using with an Outline created from the rect parameters provided. Additionally if clip is true, the contents of this GraphicsLayer will be clipped to this geometry.

Parameters

actual suspend fun toImageBitmap(): ImageBitmap

Create an ImageBitmap with the contents of this GraphicsLayer instance. Note that GraphicsLayer.record must be invoked first to record drawing operations before invoking this method.

Companion Object