androidx.compose.ui.draw

Interfaces

BuildDrawCacheParams

The set of parameters which could be used to build the drawing cache.

Cmn
CacheDrawModifierNode

Expands on the androidx.compose.ui.node.DrawModifierNode by adding the ability to invalidate the draw cache for changes in things like shapes and bitmaps (see Modifier.border for a usage examples).

Cmn
DrawCacheModifier

DrawModifier implementation that supports building a cache of objects to be referenced across draw calls

Cmn
DrawModifier

A Modifier.Element that draws into the space of the layout.

Cmn

Classes

BlurredEdgeTreatment

Determines the strategy used to render pixels in the blurred result that may extend beyond the bounds of the original input.

Cmn
CacheDrawScope

Handle to a drawing environment that enables caching of content based on the resolved size.

Cmn
DrawResult

Holder to a callback to be invoked during draw operations.

Cmn

Top-level functions summary

Extension functions summary

Modifier

Draw content with modified alpha that may be less than 1.

Cmn
Modifier
Modifier.blur(radius: Dp, edgeTreatment: BlurredEdgeTreatment)

Draw content blurred with the specified radii.

Cmn
Modifier
Modifier.blur(
    radiusX: Dp,
    radiusY: Dp,
    edgeTreatment: BlurredEdgeTreatment
)

Draw content blurred with the specified radii.

Cmn
Modifier

Clip the content to shape.

Cmn
Modifier

Clip the content to the bounds of a layer defined at this modifier.

Cmn
Modifier

Draw into a Canvas behind the modified content.

Cmn
Modifier

Draw into a DrawScope with content that is persisted across draw calls as long as the size of the drawing area is the same or any state objects that are read have not changed.

Cmn
Modifier

Creates a DrawModifier that allows the developer to draw before or after the layout's contents.

Cmn
Modifier
Modifier.paint(
    painter: Painter,
    sizeToIntrinsics: Boolean,
    alignment: Alignment,
    contentScale: ContentScale,
    alpha: Float,
    colorFilter: ColorFilter?
)

Paint the content using painter.

Cmn
Modifier
Modifier.rotate(degrees: Float)

Sets the degrees the view is rotated around the center of the composable.

Cmn
Modifier

Scale the contents of both the horizontal and vertical axis uniformly by the same scale factor.

Cmn
Modifier
Modifier.scale(scaleX: Float, scaleY: Float)

Scale the contents of the composable by the following scale factors along the horizontal and vertical axis respectively.

Cmn
Modifier
Modifier.shadow(
    elevation: Dp,
    shape: Shape,
    clip: Boolean,
    ambientColor: Color,
    spotColor: Color
)

Creates a graphicsLayer that draws a shadow.

Cmn

Top-level functions

CacheDrawModifierNode

fun CacheDrawModifierNode(onBuildDrawCache: CacheDrawScope.() -> DrawResult): CacheDrawModifierNode

Extension functions

alpha

fun Modifier.alpha(alpha: Float): Modifier

Draw content with modified alpha that may be less than 1.

Usage of this API renders this composable into a separate graphics layer. Note when an alpha less than 1.0f is provided, contents are implicitly clipped to their bounds. 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.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.alpha

Box(Modifier.size(100.dp).alpha(alpha = 0.5f).background(Color.Red))
Parameters
alpha: Float

the fraction of children's alpha value and must be between 0 and 1, inclusive.

See also
graphicsLayer

Example usage:

blur

fun Modifier.blur(
    radius: Dp,
    edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle
): Modifier

Draw content blurred with the specified radii. Note this effect is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

Usage of this API renders the corresponding composable into a separate graphics layer. Because the blurred content renders a larger area by the blur radius, this layer is explicitly clipped to the content bounds. It is recommended introduce additional space around the drawn content by the specified blur radius to remain within the content bounds.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.blur

Box(
    Modifier.size(300.dp)
        // Blur content allowing the result to extend beyond the bounds of the original content
        .blur(
            30.dp,
            edgeTreatment = BlurredEdgeTreatment.Unbounded
        )
        .background(Color.Red, CircleShape)
)
import androidx.compose.foundation.Image
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.res.painterResource

Image(
    painter = painterResource(R.drawable.circus),
    contentDescription = "sample blurred image",
    // Blur content within the original bounds, clipping the result to a rounded rectangle
    modifier = Modifier.blur(30.dp, BlurredEdgeTreatment(RoundedCornerShape(5.dp)))
)
Parameters
radius: Dp

Radius of the blur along both the x and y axis

edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle

Strategy used to render pixels outside of bounds of the original input

See also
graphicsLayer

Example usage:

blur

fun Modifier.blur(
    radiusX: Dp,
    radiusY: Dp,
    edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle
): Modifier

Draw content blurred with the specified radii. Note this effect is only supported on Android 12 and above. Attempts to use this Modifier on older Android versions will be ignored.

Usage of this API renders the corresponding composable into a separate graphics layer. Because the blurred content renders a larger area by the blur radius, this layer is explicitly clipped to the content bounds. It is recommended introduce additional space around the drawn content by the specified blur radius to remain within the content bounds.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.blur

Box(
    Modifier.size(300.dp)
        // Blur content allowing the result to extend beyond the bounds of the original content
        .blur(
            30.dp,
            edgeTreatment = BlurredEdgeTreatment.Unbounded
        )
        .background(Color.Red, CircleShape)
)
import androidx.compose.foundation.Image
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.ui.draw.BlurredEdgeTreatment
import androidx.compose.ui.draw.blur
import androidx.compose.ui.res.painterResource

Image(
    painter = painterResource(R.drawable.circus),
    contentDescription = "sample blurred image",
    // Blur content within the original bounds, clipping the result to a rounded rectangle
    modifier = Modifier.blur(30.dp, BlurredEdgeTreatment(RoundedCornerShape(5.dp)))
)
Parameters
radiusX: Dp

Radius of the blur along the x axis

radiusY: Dp

Radius of the blur along the y axis

edgeTreatment: BlurredEdgeTreatment = BlurredEdgeTreatment.Rectangle

Strategy used to render pixels outside of bounds of the original input

See also
graphicsLayer

Example usage:

clip

fun Modifier.clip(shape: Shape): Modifier

Clip the content to shape.

Parameters
shape: Shape

the content will be clipped to this Shape.

clipToBounds

fun Modifier.clipToBounds(): Modifier

Clip the content to the bounds of a layer defined at this modifier.

drawBehind

fun Modifier.drawBehind(onDraw: DrawScope.() -> Unit): Modifier

Draw into a Canvas behind the modified content.

drawWithCache

fun Modifier.drawWithCache(onBuildDrawCache: CacheDrawScope.() -> DrawResult): Modifier

Draw into a DrawScope with content that is persisted across draw calls as long as the size of the drawing area is the same or any state objects that are read have not changed. In the event that the drawing area changes, or the underlying state values that are being read change, this method is invoked again to recreate objects to be used during drawing

For example, a androidx.compose.ui.graphics.LinearGradient that is to occupy the full bounds of the drawing area can be created once the size has been defined and referenced for subsequent draw calls without having to re-allocate.

import androidx.compose.foundation.layout.Box
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset

Box(
    Modifier.drawWithCache {
        val gradient = Brush.linearGradient(
            colors = listOf(Color.Red, Color.Blue),
            start = Offset.Zero,
            end = Offset(size.width, size.height)
        )
        onDrawBehind {
            drawRect(gradient)
        }
    }
)
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset

val colors1 = listOf(Color.Red, Color.Blue)
val colors2 = listOf(Color.Yellow, Color.Green)
var toggle by remember { mutableStateOf(true) }
Box(
    Modifier.clickable { toggle = !toggle }.drawWithCache {
        val gradient = Brush.linearGradient(
            colors = if (toggle) colors1 else colors2,
            start = Offset.Zero,
            end = Offset(size.width, size.height)
        )
        onDrawBehind {
            drawRect(gradient)
        }
    }
)
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.SolidColor
import androidx.compose.ui.graphics.vector.Path
import androidx.compose.ui.graphics.vector.PathData
import androidx.compose.ui.graphics.vector.rememberVectorPainter

val vectorPainter = rememberVectorPainter(24.dp, 24.dp, autoMirror = true) {
        viewportWidth, viewportHeight ->
    Path(
        pathData = PathData {
            lineTo(viewportWidth, 0f)
            lineTo(0f, viewportHeight)
            close()
        },
        fill = SolidColor(Color.Black)
    )
}
Image(
    painter = vectorPainter,
    contentDescription = null,
    modifier = Modifier.requiredSize(120.dp).drawWithCache {
        val gradient = Brush.linearGradient(
            colors = listOf(Color.Red, Color.Blue),
            start = Offset.Zero,
            end = Offset(0f, size.height)
        )
        onDrawWithContent {
            drawContent()
            drawRect(gradient, blendMode = BlendMode.Plus)
        }
    }
)

drawWithContent

fun Modifier.drawWithContent(onDraw: ContentDrawScope.() -> Unit): Modifier

Creates a DrawModifier that allows the developer to draw before or after the layout's contents. It also allows the modifier to adjust the layout's canvas.

paint

fun Modifier.paint(
    painter: Painter,
    sizeToIntrinsics: Boolean = true,
    alignment: Alignment = Alignment.Center,
    contentScale: ContentScale = ContentScale.Inside,
    alpha: Float = DefaultAlpha,
    colorFilter: ColorFilter? = null
): Modifier

Paint the content using painter.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.draw.paint
import androidx.compose.ui.geometry.Size

class CustomPainter : Painter() {

    override val intrinsicSize: Size
        get() = Size(300.0f, 300.0f)

    override fun DrawScope.onDraw() {
        drawCircle(
            center = center,
            radius = size.minDimension / 2.0f,
            color = Color.Red
        )
    }
}

Box(
    modifier =
        Modifier.background(color = Color.Gray)
            .padding(30.dp)
            .background(color = Color.Yellow)
            .paint(CustomPainter())
) { /** intentionally empty */ }
Parameters
sizeToIntrinsics: Boolean = true

true to size the element relative to Painter.intrinsicSize

alignment: Alignment = Alignment.Center

specifies alignment of the painter relative to content

contentScale: ContentScale = ContentScale.Inside

strategy for scaling painter if its size does not match the content size

alpha: Float = DefaultAlpha

opacity of painter

colorFilter: ColorFilter? = null

optional ColorFilter to apply to painter

rotate

fun Modifier.rotate(degrees: Float): Modifier

Sets the degrees the view is rotated around the center of the composable. Increasing values result in clockwise rotation. Negative degrees are used to rotate in the counter clockwise direction

Usage of this API renders this composable into a separate graphics layer.

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.rotate

Box(
    Modifier.rotate(45f)
        .size(100.dp, 100.dp)
)
See also
graphicsLayer

Example usage:

scale

fun Modifier.scale(scale: Float): Modifier

Scale the contents of both the horizontal and vertical axis uniformly by the same scale factor.

Usage of this API renders this composable into a separate graphics layer

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.scale

Box(
    Modifier.scale(2f)
        .size(100.dp, 100.dp)
)
Parameters
scale: Float

Multiplier to scale content along the horizontal and vertical axis

See also
graphicsLayer

Example usage:

scale

fun Modifier.scale(scaleX: Float, scaleY: Float): Modifier

Scale the contents of the composable by the following scale factors along the horizontal and vertical axis respectively. Negative scale factors can be used to mirror content across the corresponding horizontal or vertical axis.

Example usage:

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.scale

Box(
    Modifier.scale(scaleX = 2f, scaleY = 3f)
        .size(100.dp, 100.dp)
)

Usage of this API renders this composable into a separate graphics layer

Parameters
scaleX: Float

Multiplier to scale content along the horizontal axis

scaleY: Float

Multiplier to scale content along the vertical axis

See also
graphicsLayer

shadow

fun Modifier.shadow(
    elevation: Dp,
    shape: Shape = RectangleShape,
    clip: Boolean = elevation > 0.dp,
    ambientColor: Color = DefaultShadowColor,
    spotColor: Color = DefaultShadowColor
): Modifier

Creates a graphicsLayer that draws a shadow. The elevation defines the visual depth of the physical object. The physical object has a shape specified by shape.

If the passed shape is concave the shadow will not be drawn on Android versions less than 10.

Note that elevation is only affecting the shadow size and doesn't change the drawing order. Use a androidx.compose.ui.zIndex modifier if you want to draw the elements with larger elevation after all the elements with a smaller one.

Usage of this API renders this composable into a separate graphics layer

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.draw.shadow

Box(
    Modifier.shadow(12.dp, RectangleShape)
        .size(100.dp, 100.dp)
)
Parameters
elevation: Dp

The elevation for the shadow in pixels

shape: Shape = RectangleShape

Defines a shape of the physical object

clip: Boolean = elevation > 0.dp

When active, the content drawing clips to the shape.

See also
graphicsLayer

Example usage: