---
title: "GraphicsLayer"
description: "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]"
type: "class"
---
Class
Common
```kotlin
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
Common
```kotlin
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`.
Common
```kotlin
var topLeft: IntOffset
```
Offset in pixels where this `GraphicsLayer` will render within a provided canvas when
`drawLayer` is called.
Common
```kotlin
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`
Common
```kotlin
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`
Common
```kotlin
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.
Common
```kotlin
var scaleX: Float
```
The horizontal scale of the drawn area. Default value is `1`.
Common
```kotlin
var scaleY: Float
```
The vertical scale of the drawn area. Default value is `1`.
Common
```kotlin
var translationX: Float
```
Horizontal pixel offset of the layer relative to `topLeft`.x. Default value is `0`.
Common
```kotlin
var translationY: Float
```
Vertical pixel offset of the layer relative to `topLeft`.y. Default value is `0`
Common
```kotlin
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.
Common
```kotlin
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.
Common
```kotlin
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.
Common
```kotlin
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`.
Common
```kotlin
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`
Common
```kotlin
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.
Common
```kotlin
var rotationX: Float
```
The rotation, in degrees, of the contents around the horizontal axis in degrees. Default
value is `0`.
Common
```kotlin
var rotationY: Float
```
The rotation, in degrees, of the contents around the vertical axis in degrees. Default value
is `0`.
Common
```kotlin
var rotationZ: Float
```
The rotation, in degrees, of the contents around the Z axis in degrees. Default value is `0`.
Common
```kotlin
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`
Common
```kotlin
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
Common
```kotlin
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.
Common
```kotlin
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
```kotlin
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
| | |
| --- | --- |
| path | Path to be used as the Outline for the `GraphicsLayer` |
```kotlin
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
| | |
| --- | --- |
| topLeft | The top left of the rounded rect outline |
| size | The size of the rounded rect outline |
| cornerRadius | The corner radius of the rounded rect outline |
```kotlin
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
| | |
| --- | --- |
| topLeft | The top left of the rounded rect outline |
| size | The size of the rounded rect outline |
```kotlin
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
| | |
| --- | --- |
| density | `Density` used to assist in conversions of density independent pixels to raw pixels to draw. |
| layoutDirection | `LayoutDirection` of the layout being drawn in. |
| size | `Size` of the `GraphicsLayer` |
| block | lambda that is called to issue drawing commands on this `DrawScope` |
```kotlin
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.
Android
```kotlin
actual class GraphicsLayer internal constructor(internal val impl: GraphicsLayerImpl)
```
## Properties
Android
```kotlin
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.
Android
```kotlin
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.
Android
```kotlin
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`
Android
```kotlin
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`
Android
```kotlin
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.
Android
```kotlin
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`.
Android
```kotlin
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`
Android
```kotlin
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`
Android
```kotlin
actual var scaleX: Float
```
The horizontal scale of the drawn area. Default value is `1`.
Android
```kotlin
actual var scaleY: Float
```
The vertical scale of the drawn area. Default value is `1`.
Android
```kotlin
actual var translationX: Float
```
Horizontal pixel offset of the layer relative to its left bound. Default value is `0`.
Android
```kotlin
actual var translationY: Float
```
Vertical pixel offset of the layer relative to its top bound. Default value is `0`
Android
```kotlin
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.
Android
```kotlin
actual var rotationX: Float
```
The rotation, in degrees, of the contents around the horizontal axis in degrees. Default
value is `0`.
Android
```kotlin
actual var rotationY: Float
```
The rotation, in degrees, of the contents around the vertical axis in degrees. Default value
is `0`.
Android
```kotlin
actual var rotationZ: Float
```
The rotation, in degrees, of the contents around the Z axis in degrees. Default value is `0`.
Android
```kotlin
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`
Android
```kotlin
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.
Android
```kotlin
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.
Android
```kotlin
val layerId: Long
```
The ID of the layer. This is used by tooling to match a layer to the associated LayoutNode.
Android
```kotlin
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.
Android
```kotlin
actual val outline: Outline
```
Android
```kotlin
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.
Android
```kotlin
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
```kotlin
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
| | |
| --- | --- |
| density | `Density` used to assist in conversions of density independent pixels to raw pixels to draw. |
| layoutDirection | `LayoutDirection` of the layout being drawn in. |
| size | `Size` of the `GraphicsLayer` |
| block | lambda that is called to issue drawing commands on this `DrawScope` |
```kotlin
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
| | |
| --- | --- |
| path | Path to be used as the Outline for the `GraphicsLayer` |
```kotlin
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
| | |
| --- | --- |
| topLeft | The top left of the rounded rect outline |
| size | The size of the rounded rect outline |
| cornerRadius | The corner radius of the rounded rect outline |
```kotlin
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
| | |
| --- | --- |
| topLeft | The top left of the rounded rect outline |
| size | The size of the rounded rect outline |
```kotlin
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