androidx.compose.ui.graphics.drawscope

Interfaces

DrawTransform

Defines transformations that can be applied to a drawing environment

Classes

DrawScope

Creates a scoped drawing environment with the provided Canvas.

DrawStyle

Represents how the shapes should be drawn within a DrawScope

Stroke

DrawStyle that provides information for drawing content with a stroke

Annotations

DrawScopeMarker

DSL marker used to distinguish between drawing operations and canvas transform operations

Extension functions summary

For DrawScope
Unit
DrawScope.clipPath(path: Path, clipOp: ClipOp = ClipOp.Intersect, block: DrawScope.() -> Unit)

Reduces the clip region to the intersection of the current clip and the given rounded rectangle.

Unit
DrawScope.clipRect(left: Float = 0.0f, top: Float = 0.0f, right: Float = size.width, bottom: Float = size.height, clipOp: ClipOp = ClipOp.Intersect, block: DrawScope.() -> Unit)

Reduces the clip region to the intersection of the current clip and the given rectangle indicated by the given left, top, right and bottom bounds.

Unit
DrawScope.drawCanvas(block: (Canvas, Size) -> Unit)

Provides access to draw directly with the underlying Canvas along with the current size of the DrawScope.

Unit
DrawScope.inset(left: Float, top: Float, right: Float, bottom: Float, block: DrawScope.() -> Unit)

Simultaneously translate the DrawScope coordinate space by left and top as well as modify the dimensions of the current painting area.

Unit
DrawScope.inset(dx: Float = 0.0f, dy: Float = 0.0f, block: DrawScope.() -> Unit)

Convenience method modifies the DrawScope bounds to inset both left and right bounds by dx as well as the top and bottom by dy.

Unit
DrawScope.rotate(degrees: Float, pivotX: Float = center.x, pivotY: Float = center.y, block: DrawScope.() -> Unit)

Add a rotation (in degrees clockwise) to the current transform at the given pivot point.

Unit
DrawScope.rotateRad(radians: Float, pivotX: Float = center.x, pivotY: Float = center.y, block: DrawScope.() -> Unit)

Add a rotation (in radians clockwise) to the current transform at the given pivot point.

Unit
DrawScope.scale(scaleX: Float, scaleY: Float = scaleX, pivotX: Float = center.x, pivotY: Float = center.y, block: DrawScope.() -> Unit)

Add an axis-aligned scale to the current transform, scaling by the first argument in the horizontal direction and the second in the vertical direction at the given pivot coordinate.

Unit
DrawScope.translate(left: Float = 0.0f, top: Float = 0.0f, block: DrawScope.() -> Unit)

Translate the coordinate space by the given delta in pixels in both the x and y coordinates respectively

Unit
DrawScope.withTransform(transformBlock: DrawTransform.() -> Unit, drawBlock: DrawScope.() -> Unit)

Perform 1 or more transformations and execute drawing commands with the specified transformations applied.

For DrawTransform
Unit
DrawTransform.inset(dx: Float = 0.0f, dy: Float = 0.0f)

Convenience method modifies the DrawTransform bounds to inset both left and right bounds by dx as well as the top and bottom by dy.

Unit
DrawTransform.rotateRad(radians: Float, pivotX: Float = center.x, pivotY: Float = center.y)

Add a rotation (in radians clockwise) to the current transform at the given pivot point.

Extension functions

clipPath

inline fun DrawScope.clipPath(
    path: Path,
    clipOp: ClipOp = ClipOp.Intersect,
    block: DrawScope.() -> Unit
): Unit

Reduces the clip region to the intersection of the current clip and the given rounded rectangle.

Parameters
path: Path Shape to clip drawing content within
clipOp: ClipOp = ClipOp.Intersect Clipping operation to conduct on the given bounds, defaults to ClipOp.Intersect
block: DrawScope.() -> Unit Lambda callback with this CanvasScope as a receiver scope to issue drawing commands within the provided clip

clipRect

inline fun DrawScope.clipRect(
    left: Float = 0.0f,
    top: Float = 0.0f,
    right: Float = size.width,
    bottom: Float = size.height,
    clipOp: ClipOp = ClipOp.Intersect,
    block: DrawScope.() -> Unit
): Unit

Reduces the clip region to the intersection of the current clip and the given rectangle indicated by the given left, top, right and bottom bounds.

Use ClipOp.Difference to subtract the provided rectangle from the current clip.

Parameters
left: Float = 0.0f Left bound of the rectangle to clip
top: Float = 0.0f Top bound of the rectangle to clip
right: Float = size.width Right bound ofthe rectangle to clip
bottom: Float = size.height Bottom bound of the rectangle to clip
clipOp: ClipOp = ClipOp.Intersect Clipping operation to conduct on the given bounds, defaults to ClipOp.Intersect
block: DrawScope.() -> Unit Lambda callback with this CanvasScope as a receiver scope to issue drawing commands within the provided clip

drawCanvas

inline fun DrawScope.drawCanvas(block: (Canvas, Size) -> Unit): Unit

Provides access to draw directly with the underlying Canvas along with the current size of the DrawScope. This is helpful for situations to re-use alternative drawing logic in combination with DrawScope

Parameters
block: (Canvas, Size) -> Unit Lambda callback to issue drawing commands on the provided Canvas and given size

inset

inline fun DrawScope.inset(
    left: Float,
    top: Float,
    right: Float,
    bottom: Float,
    block: DrawScope.() -> Unit
): Unit

Simultaneously translate the DrawScope coordinate space by left and top as well as modify the dimensions of the current painting area. This provides a callback to issue more drawing instructions within the modified coordinate space. This method modifies the width of the DrawScope to be equivalent to width - (left + right) as well as height to height - (top + bottom)

Parameters
left: Float number of pixels to inset the left drawing bound
top: Float number of pixels to inset the top drawing bound
right: Float number of pixels to inset the right drawing bound
bottom: Float number of pixels to inset the bottom drawing bound
block: DrawScope.() -> Unit lambda that is called to issue drawing commands within the inset coordinate space

inset

inline fun DrawScope.inset(
    dx: Float = 0.0f,
    dy: Float = 0.0f,
    block: DrawScope.() -> Unit
): Unit

Convenience method modifies the DrawScope bounds to inset both left and right bounds by dx as well as the top and bottom by dy. If only dx is provided, the same inset is applied to all 4 bounds

Parameters
dx: Float = 0.0f number of pixels to inset both left and right bounds
dy: Float = 0.0f Optional number of pixels to inset both top and bottom bounds, by default this also insets the top and bottom by dx pixels
block: DrawScope.() -> Unit lambda that is called to issue additional drawing commands within the modified coordinate space

inset

inline fun DrawTransform.inset(
    dx: Float = 0.0f,
    dy: Float = 0.0f
): Unit

Convenience method modifies the DrawTransform bounds to inset both left and right bounds by dx as well as the top and bottom by dy. If only dx is provided, the same inset is applied to all 4 bounds

Parameters
dx: Float = 0.0f number of pixels to inset both left and right bounds
dy: Float = 0.0f Optional number of pixels to inset both top and bottom bounds, by default this also insets the top and bottom by dx pixels

rotate

inline fun DrawScope.rotate(
    degrees: Float,
    pivotX: Float = center.x,
    pivotY: Float = center.y,
    block: DrawScope.() -> Unit
): Unit

Add a rotation (in degrees clockwise) to the current transform at the given pivot point. The pivot coordinate remains unchanged by the rotation transformation. After the provided lambda is invoked, the rotation transformation is undone.

Parameters
degrees: Float to rotate clockwise
pivotX: Float = center.x The x-coordinate for the pivot point, defaults to the center of the coordinate space horizontally
pivotY: Float = center.y The y-coordinate for the pivot point, defaults to the center of the coordinate space vertically
block: DrawScope.() -> Unit lambda that is called to issue drawing commands within the rotated coordinate space

rotateRad

inline fun DrawScope.rotateRad(
    radians: Float,
    pivotX: Float = center.x,
    pivotY: Float = center.y,
    block: DrawScope.() -> Unit
): Unit

Add a rotation (in radians clockwise) to the current transform at the given pivot point. The pivot coordinate remains unchanged by the rotation transformation

Parameters
radians: Float to rotate clockwise
pivotX: Float = center.x The x-coordinate for the pivot point, defaults to the center of the coordinate space horizontally
pivotY: Float = center.y The y-coordinate for the pivot point, defaults to the center of the coordinate space vertically
block: DrawScope.() -> Unit lambda that is called to issue drawing commands within the rotated coordinate space

rotateRad

inline fun DrawTransform.rotateRad(
    radians: Float,
    pivotX: Float = center.x,
    pivotY: Float = center.y
): Unit

Add a rotation (in radians clockwise) to the current transform at the given pivot point. The pivot coordinate remains unchanged by the rotation transformation

Parameters
radians: Float to rotate clockwise
pivotX: Float = center.x The x-coordinate for the pivot point, defaults to the center of the coordinate space horizontally
pivotY: Float = center.y The y-coordinate for the pivot point, defaults to the center of the coordinate space vertically

scale

inline fun DrawScope.scale(
    scaleX: Float,
    scaleY: Float = scaleX,
    pivotX: Float = center.x,
    pivotY: Float = center.y,
    block: DrawScope.() -> Unit
): Unit

Add an axis-aligned scale to the current transform, scaling by the first argument in the horizontal direction and the second in the vertical direction at the given pivot coordinate. The pivot coordinate remains unchanged by the scale transformation.

If scaleY is unspecified, scaleX will be used for the scale in both directions.

Parameters
scaleX: Float The amount to scale in X
scaleY: Float = scaleX The amount to scale in Y
pivotX: Float = center.x The x-coordinate for the pivot point, defaults to the center of the coordinate space horizontally
pivotY: Float = center.y The y-coordinate for the pivot point, defaults to the center of the coordinate space vertically
block: DrawScope.() -> Unit lambda used to issue drawing commands within the scaled coordinate space

translate

inline fun DrawScope.translate(
    left: Float = 0.0f,
    top: Float = 0.0f,
    block: DrawScope.() -> Unit
): Unit

Translate the coordinate space by the given delta in pixels in both the x and y coordinates respectively

Parameters
left: Float = 0.0f Pixels to translate the coordinate space in the x-axis
top: Float = 0.0f Pixels to translate the coordinate space in the y-axis
block: DrawScope.() -> Unit lambda that is called to issue drawing commands within the translated coordinate space

withTransform

inline fun DrawScope.withTransform(
    transformBlock: DrawTransform.() -> Unit,
    drawBlock: DrawScope.() -> Unit
): Unit

Perform 1 or more transformations and execute drawing commands with the specified transformations applied. After this call is complete, the transformation before this call was made is restored

import androidx.compose.foundation.Canvas
import androidx.compose.foundation.layout.preferredSize
import androidx.compose.ui.graphics.drawscope.inset
import androidx.compose.ui.graphics.drawscope.rotate
import androidx.compose.ui.graphics.drawscope.withTransform

Canvas(Modifier.preferredSize(120.dp)) { // CanvasScope
    inset(20.0f) {
        // Use withTransform to batch multiple transformations for 1 or more drawing calls
        // that are to be drawn.
        // This is more efficient than issuing nested translation, rotation and scaling
        // calls as the internal state is saved once before and after instead of multiple
        // times between each transformation if done individually
        withTransform({
            translate(10.0f, 12.0f)
            rotate(45.0f)
            scale(2.0f, 0.5f)
        }) {
            drawRect(Color.Cyan)
            drawCircle(Color.Blue)
        }
        drawRect(Color.Red, alpha = 0.25f)
    }
}
Parameters
transformBlock: DrawTransform.() -> Unit Callback invoked to issue transformations to be made before the drawing operations are issued
drawBlock: DrawScope.() -> Unit Callback invoked to issue drawing operations after the transformations are applied