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

GraphicsLayerModifierKt

public final class GraphicsLayerModifierKt


Summary

Public methods

static final @NonNull Modifier
graphicsLayer(
    @NonNull Modifier receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull GraphicsLayerScopeUnit> block
)

A Modifier.Node that makes content draw into a draw layer.

static final @NonNull Modifier
graphicsLayer(
    @NonNull Modifier receiver,
    float scaleX,
    float scaleY,
    float alpha,
    float translationX,
    float translationY,
    float shadowElevation,
    float rotationX,
    float rotationY,
    float rotationZ,
    float cameraDistance,
    @NonNull TransformOrigin transformOrigin,
    @NonNull Shape shape,
    boolean clip,
    RenderEffect renderEffect,
    @NonNull Color ambientShadowColor,
    @NonNull Color spotShadowColor,
    @NonNull CompositingStrategy compositingStrategy
)

A Modifier.Element that makes content draw into a draw layer.

static final @NonNull Modifier

A Modifier.Element that adds a draw layer such that tooling can identify an element in the drawn image.

Public methods

graphicsLayer

public static final @NonNull Modifier graphicsLayer(
    @NonNull Modifier receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull GraphicsLayerScopeUnit> block
)

A Modifier.Node that makes content draw into a draw layer. The draw layer can be invalidated separately from parents. A graphicsLayer should be used when the content updates independently from anything above it to minimize the invalidated content.

graphicsLayer can be used to apply effects to content, such as scaling, rotation, opacity, shadow, and clipping. Prefer this version when you have layer properties backed by a androidx.compose.runtime.State or an animated value as reading a state inside block will only cause the layer properties update without triggering recomposition and relayout.

import androidx.compose.animation.core.Animatable
import androidx.compose.material.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.graphicsLayer

val animatedAlpha = remember { Animatable(0f) }
Text(
    "Hello World",
    Modifier.graphicsLayer {
        alpha = animatedAlpha.value
        clip = true
    }
)
LaunchedEffect(animatedAlpha) {
    animatedAlpha.animateTo(1f)
}
Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull GraphicsLayerScopeUnit> block

block on GraphicsLayerScope where you define the layer properties.

graphicsLayer

public static final @NonNull Modifier graphicsLayer(
    @NonNull Modifier receiver,
    float scaleX,
    float scaleY,
    float alpha,
    float translationX,
    float translationY,
    float shadowElevation,
    float rotationX,
    float rotationY,
    float rotationZ,
    float cameraDistance,
    @NonNull TransformOrigin transformOrigin,
    @NonNull Shape shape,
    boolean clip,
    RenderEffect renderEffect,
    @NonNull Color ambientShadowColor,
    @NonNull Color spotShadowColor,
    @NonNull CompositingStrategy compositingStrategy
)

A Modifier.Element that makes content draw into a draw layer. The draw layer can be invalidated separately from parents. A graphicsLayer should be used when the content updates independently from anything above it to minimize the invalidated content.

graphicsLayer can also be used to apply effects to content, such as scaling (scaleX, scaleY), rotation (rotationX, rotationY, rotationZ), opacity (alpha), shadow (shadowElevation, shape), clipping (clip, shape), as well as altering the result of the layer with RenderEffect. Shadow color and ambient colors can be modified by configuring the spotShadowColor and ambientShadowColor respectively.

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.

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.

Also note that alpha values less than 1.0f will have their contents implicitly clipped to their bounds unless CompositingStrategy.ModulateAlpha is specified. This is because an intermediate compositing layer is created to render contents into first before being drawn into the destination with the desired alpha. This layer is sized to the bounds of the composable this modifier is configured on, and contents outside of these bounds are omitted.

If the layer parameters are backed by a androidx.compose.runtime.State or an animated value prefer an overload with a lambda block on GraphicsLayerScope as reading a state inside the block will only cause the layer properties update without triggering recomposition and relayout.

import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.graphicsLayer

Text("Hello World", Modifier.graphicsLayer(alpha = 0.5f, clip = true))
import androidx.compose.foundation.Canvas
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.CompositingStrategy
import androidx.compose.ui.graphics.drawscope.inset
import androidx.compose.ui.graphics.graphicsLayer
import androidx.compose.ui.unit.dp

Canvas(
    modifier =
        Modifier.size(100.dp)
        .background(Color.Black)
        .graphicsLayer(
            alpha = 0.5f,
            compositingStrategy = CompositingStrategy.ModulateAlpha
        )
) {
    // Configuring an alpha less than 1.0 and specifying
    // CompositingStrategy.ModulateAlpha ends up with the overlapping region
    // of the 2 draw rect calls to blend transparent blue and transparent red
    // against the black background instead of just transparent blue which is what would
    // occur with CompositingStrategy.Auto or CompositingStrategy.Offscreen
    inset(0f, 0f, size.width / 3, size.height / 3) {
        drawRect(color = Color.Red)
    }
    inset(size.width / 3, size.height / 3, 0f, 0f) {
        drawRect(color = Color.Blue)
    }
}

toolingGraphicsLayer

public static final @NonNull Modifier toolingGraphicsLayer(@NonNull Modifier receiver)

A Modifier.Element that adds a draw layer such that tooling can identify an element in the drawn image.