{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

GraphicsLayerScope

public interface GraphicsLayerScope extends Density


A scope which can be used to define the effects to apply for the content, such as scaling (scaleX, scaleY), rotation (rotationX, rotationY, rotationZ), opacity (alpha), shadow (shadowElevation, shape), and clipping (clip, shape).

Summary

Public methods

abstract float

The alpha of the drawn area.

default @NonNull Color

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

abstract 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.

abstract boolean

Set to true to clip the content to the shape.

default @NonNull CompositingStrategy

Determines the CompositingStrategy used to render the contents of this graphicsLayer into an offscreen buffer first before rendering to the destination

default RenderEffect

Configure the RenderEffect to apply to this GraphicsLayerScope.

abstract float

The rotation, in degrees, of the contents around the horizontal axis in degrees.

abstract float

The rotation, in degrees, of the contents around the vertical axis in degrees.

abstract float

The rotation, in degrees, of the contents around the Z axis in degrees.

abstract float

The horizontal scale of the drawn area.

abstract float

The vertical scale of the drawn area.

abstract float

Sets the elevation for the shadow in pixels.

abstract @NonNull Shape

The Shape of the layer.

default @NonNull Size

Size of the graphicsLayer represented in pixels.

default @NonNull Color

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

abstract @NonNull TransformOrigin

Offset percentage along the x and y axis for which contents are rotated and scaled.

abstract float

Horizontal pixel offset of the layer relative to its left bound.

abstract float

Vertical pixel offset of the layer relative to its top bound.

abstract void
setAlpha(float alpha)

The alpha of the drawn area.

default void
setAmbientShadowColor(@NonNull Color ambientShadowColor)

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

abstract void
setCameraDistance(float cameraDistance)

Sets the distance along the Z axis (orthogonal to the X/Y plane on which layers are drawn) from the camera to this layer.

abstract void
setClip(boolean clip)

Set to true to clip the content to the shape.

default void

Determines the CompositingStrategy used to render the contents of this graphicsLayer into an offscreen buffer first before rendering to the destination

default void

Configure the RenderEffect to apply to this GraphicsLayerScope.

abstract void
setRotationX(float rotationX)

The rotation, in degrees, of the contents around the horizontal axis in degrees.

abstract void
setRotationY(float rotationY)

The rotation, in degrees, of the contents around the vertical axis in degrees.

abstract void
setRotationZ(float rotationZ)

The rotation, in degrees, of the contents around the Z axis in degrees.

abstract void
setScaleX(float scaleX)

The horizontal scale of the drawn area.

abstract void
setScaleY(float scaleY)

The vertical scale of the drawn area.

abstract void
setShadowElevation(float shadowElevation)

Sets the elevation for the shadow in pixels.

abstract void

The Shape of the layer.

default void
setSpotShadowColor(@NonNull Color spotShadowColor)

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

abstract void

Offset percentage along the x and y axis for which contents are rotated and scaled.

abstract void
setTranslationX(float translationX)

Horizontal pixel offset of the layer relative to its left bound.

abstract void
setTranslationY(float translationY)

Vertical pixel offset of the layer relative to its top bound.

Inherited methods

From androidx.compose.ui.unit.Density
abstract float

The logical density of the display.

abstract float

Current user preference for the scaling factor for fonts.

default int

Convert Dp to Int by rounding

default int

Convert Sp to Int by rounding

default @NonNull Dp

Convert Sp to Dp.

default @NonNull Dp
orgKt.toDp(int receiver)

Convert an Int pixel value to Dp.

default @NonNull Dp
orgKt.toDp(float receiver)

Convert a Float pixel value to a Dp

default @NonNull DpSize

Convert a Size to a DpSize.

default float
orgKt.toPx(@NonNull Dp receiver)

Convert Dp to pixels.

default float

Convert Sp to pixels.

default @NonNull Rect

Convert a DpRect to a Rect.

default @NonNull Size

Convert a DpSize to a Size.

default @NonNull TextUnit
orgKt.toSp(@NonNull Dp receiver)

Convert Dp to Sp.

default @NonNull TextUnit
orgKt.toSp(int receiver)

Convert an Int pixel value to Sp.

default @NonNull TextUnit
orgKt.toSp(float receiver)

Convert a Float pixel value to a Sp

Public methods

getAlpha

abstract float getAlpha()

The alpha of the drawn area. Setting this to something other than 1 will cause the drawn contents to be translucent and setting it to 0 will cause it to be fully invisible. Default value is 1 and the range is between 0 and 1.

getAmbientShadowColor

default @NonNull Color getAmbientShadowColor()

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.

getCameraDistance

abstract float getCameraDistance()

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

getClip

abstract boolean getClip()

Set to true to clip the content to the shape. Default value is false

getCompositingStrategy

default @NonNull CompositingStrategy getCompositingStrategy()

Determines the CompositingStrategy used to render the contents of this graphicsLayer into an offscreen buffer first before rendering to the destination

getRenderEffect

default RenderEffect getRenderEffect()

Configure the RenderEffect to apply to this GraphicsLayerScope. This will apply a visual effect to the results of the GraphicsLayerScope 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 GraphicsLayerScope 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.

getRotationX

abstract float getRotationX()

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

getRotationY

abstract float getRotationY()

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

getRotationZ

abstract float getRotationZ()

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

getScaleX

abstract float getScaleX()

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

getScaleY

abstract float getScaleY()

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

getShadowElevation

abstract float getShadowElevation()

Sets the elevation for the shadow in pixels. With the shadowElevation 0f and shape set, a shadow is produced. Default value is 0 and the value must not be negative.

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

getShape

abstract @NonNull Shape getShape()

The Shape of the layer. When shadowElevation is non-zero a shadow is produced using this shape. When clip is true contents will be clipped to this shape. When clipping, the content will be redrawn when the shape changes. Default value is RectangleShape

getSize

default @NonNull Size getSize()

Size of the graphicsLayer represented in pixels. Drawing commands can extend beyond the size specified, however, if the graphicsLayer is promoted to an offscreen rasterization layer, any content rendered outside of the specified size will be clipped.

getSpotShadowColor

default @NonNull Color getSpotShadowColor()

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.

getTransformOrigin

abstract @NonNull TransformOrigin getTransformOrigin()

Offset percentage along the x and y axis for which contents are rotated and scaled. The default value of 0.5f, 0.5f indicates the pivot point will be at the midpoint of the left and right as well as the top and bottom bounds of the layer. Default value is TransformOrigin.Center

getTranslationX

abstract float getTranslationX()

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

getTranslationY

abstract float getTranslationY()

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

setAlpha

abstract void setAlpha(float alpha)

The alpha of the drawn area. Setting this to something other than 1 will cause the drawn contents to be translucent and setting it to 0 will cause it to be fully invisible. Default value is 1 and the range is between 0 and 1.

setAmbientShadowColor

default void setAmbientShadowColor(@NonNull Color ambientShadowColor)

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.

setCameraDistance

abstract void setCameraDistance(float cameraDistance)

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

setClip

abstract void setClip(boolean clip)

Set to true to clip the content to the shape. Default value is false

setCompositingStrategy

default void setCompositingStrategy(@NonNull CompositingStrategy compositingStrategy)

Determines the CompositingStrategy used to render the contents of this graphicsLayer into an offscreen buffer first before rendering to the destination

setRenderEffect

default void setRenderEffect(RenderEffect renderEffect)

Configure the RenderEffect to apply to this GraphicsLayerScope. This will apply a visual effect to the results of the GraphicsLayerScope 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 GraphicsLayerScope 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.

setRotationX

abstract void setRotationX(float rotationX)

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

setRotationY

abstract void setRotationY(float rotationY)

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

setRotationZ

abstract void setRotationZ(float rotationZ)

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

setScaleX

abstract void setScaleX(float scaleX)

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

setScaleY

abstract void setScaleY(float scaleY)

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

setShadowElevation

abstract void setShadowElevation(float shadowElevation)

Sets the elevation for the shadow in pixels. With the shadowElevation 0f and shape set, a shadow is produced. Default value is 0 and the value must not be negative.

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

setShape

abstract void setShape(@NonNull Shape shape)

The Shape of the layer. When shadowElevation is non-zero a shadow is produced using this shape. When clip is true contents will be clipped to this shape. When clipping, the content will be redrawn when the shape changes. Default value is RectangleShape

setSpotShadowColor

default void setSpotShadowColor(@NonNull Color spotShadowColor)

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.

setTransformOrigin

abstract void setTransformOrigin(@NonNull TransformOrigin transformOrigin)

Offset percentage along the x and y axis for which contents are rotated and scaled. The default value of 0.5f, 0.5f indicates the pivot point will be at the midpoint of the left and right as well as the top and bottom bounds of the layer. Default value is TransformOrigin.Center

setTranslationX

abstract void setTranslationX(float translationX)

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

setTranslationY

abstract void setTranslationY(float translationY)

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