androidx.compose.ui.graphics.drawscope

Interfaces

ContentDrawScope

Receiver scope for drawing content into a layout, where the content can be drawn between other canvas operations.

Cmn
DrawContext

Object that provides the dependencies to support a DrawScope drawing environment.

Cmn
DrawScope

Creates a scoped drawing environment with the provided Canvas.

Cmn
DrawTransform

Defines transformations that can be applied to a drawing environment

Cmn

Classes

CanvasDrawScope

Implementation of DrawScope that issues drawing commands into the specified canvas and bounds via CanvasDrawScope.draw

Cmn
DrawStyle

Represents how the shapes should be drawn within a DrawScope

Cmn
Stroke

DrawStyle that provides information for drawing content with a stroke

Cmn

Objects

Fill

Default DrawStyle indicating shapes should be drawn completely filled in with the provided color or pattern

Cmn

Annotations

DrawScopeMarker

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

Cmn

Extension functions summary

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

Reduces the clip region to the intersection of the current clip and the given path.

Cmn
inline Unit
DrawScope.clipRect(
    left: Float,
    top: Float,
    right: Float,
    bottom: Float,
    clipOp: ClipOp,
    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.

Cmn
inline Unit
DrawScope.draw(
    density: Density,
    layoutDirection: LayoutDirection,
    canvas: Canvas,
    size: Size,
    graphicsLayer: GraphicsLayer?,
    block: DrawScope.() -> Unit
)

Draws into the provided Canvas with the commands specified in the lambda with this DrawScope as a receiver

Cmn
inline Unit

Provides access to draw directly with the underlying Canvas.

Cmn
inline Unit

Convenience method modifies the DrawScope bounds to inset both left, top, right and bottom bounds by inset.

Cmn
inline Unit
DrawTransform.inset(horizontal: Float, vertical: Float)

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

Cmn
inline Unit
DrawScope.inset(inset: Float, block: DrawScope.() -> Unit)

Convenience method modifies the DrawScope bounds to inset both left, top, right and bottom bounds by inset.

Cmn
inline Unit
DrawScope.inset(horizontal: Float, vertical: Float, block: DrawScope.() -> Unit)

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

Cmn
inline 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.

Cmn
inline Unit
DrawScope.rotate(degrees: Float, pivot: Offset, block: DrawScope.() -> Unit)

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

Cmn
inline Unit
DrawTransform.rotateRad(radians: Float, pivot: Offset)

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

Cmn
inline Unit
DrawScope.rotateRad(radians: Float, pivot: Offset, block: DrawScope.() -> Unit)

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

Cmn
inline Unit
DrawTransform.scale(scale: Float, pivot: Offset)

Add an axis-aligned scale to the current transform, scaling uniformly in both directions by the provided scale factor at the pivot coordinate.

Cmn
inline Unit
DrawScope.scale(scale: Float, pivot: Offset, block: DrawScope.() -> Unit)

Add an axis-aligned scale to the current transform, scaling both the horizontal direction and the vertical direction at the given pivot coordinate.

Cmn
inline Unit
DrawScope.scale(
    scaleX: Float,
    scaleY: Float,
    pivot: Offset,
    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.

Cmn
inline Unit
DrawScope.translate(left: Float, top: Float, block: DrawScope.() -> Unit)

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

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

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

Cmn

Extension functions

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 path. This method provides a callback to issue drawing commands within the region defined by the clipped path. After this method is invoked, this clip is no longer applied.

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

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. This provides a callback to issue drawing commands within the clipped region. After this method is invoked, this clip is no longer applied.

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 of the 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

inline fun DrawScope.draw(
    density: Density,
    layoutDirection: LayoutDirection,
    canvas: Canvas,
    size: Size,
    graphicsLayer: GraphicsLayer? = null,
    block: DrawScope.() -> Unit
): Unit

Draws into the provided Canvas with the commands specified in the lambda with this DrawScope as a receiver

import androidx.compose.foundation.Canvas
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.drawWithCache
import androidx.compose.ui.graphics.drawscope.draw
import androidx.compose.ui.graphics.drawscope.drawIntoCanvas
import androidx.compose.ui.graphics.nativeCanvas
import androidx.compose.ui.unit.dp

Box(
    modifier =
        Modifier.size(120.dp).drawWithCache {
            // Example that shows how to redirect rendering to an Android Picture and then
            // draw the picture into the original destination
            // Note:
            // Canvas#drawPicture is supported with hardware acceleration on Android API 23+
            // Check
            // https://developer.android.com/topic/performance/hardware-accel#drawing-support
            // for details of which drawing operations are supported with hardware acceleration
            val picture = android.graphics.Picture()
            val width = this.size.width.toInt()
            val height = this.size.height.toInt()
            onDrawWithContent {
                val pictureCanvas =
                    androidx.compose.ui.graphics.Canvas(picture.beginRecording(width, height))
                draw(this, this.layoutDirection, pictureCanvas, this.size) {
                    this@onDrawWithContent.drawContent()
                }
                picture.endRecording()

                drawIntoCanvas { canvas -> canvas.nativeCanvas.drawPicture(picture) }
            }
        }
)
Parameters
density: Density

Density used to assist in conversions of density independent pixels to raw pixels to draw

layoutDirection: LayoutDirection

LayoutDirection of the layout being drawn in.

canvas: Canvas

target canvas to render into

size: Size

bounds relative to the current canvas translation in which the DrawScope should draw within

graphicsLayer: GraphicsLayer? = null

Current GraphicsLayer we are drawing into. Might be null if the canvas is not provided by a GraphicsLayer, for example in the case of a software-accelerated drawing

block: DrawScope.() -> Unit

lambda that is called to issue drawing commands on this DrawScope

drawIntoCanvas

inline fun DrawScope.drawIntoCanvas(block: (Canvas) -> Unit): Unit

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

Parameters
block: (Canvas) -> Unit

Lambda callback to issue drawing commands on the provided Canvas

inset

inline fun DrawTransform.inset(inset: Float): Unit

Convenience method modifies the DrawScope bounds to inset both left, top, right and bottom bounds by inset. After this method is invoked, the coordinate space is returned to the state before this inset was applied.

Parameters
inset: Float

number of pixels to inset left, top, right, and bottom bounds.

inset

inline fun DrawTransform.inset(horizontal: Float = 0.0f, vertical: Float = 0.0f): Unit

Convenience method modifies the DrawTransform bounds to inset both left and right bounds by horizontal as well as the top and bottom by vertical. After this method is invoked, the coordinate space is returned to the state before the inset was applied

Parameters
horizontal: Float = 0.0f

number of pixels to inset both left and right bounds. Zero by default.

vertical: Float = 0.0f

number of pixels to inset both top and bottom bounds. Zero by default.

inset

inline fun DrawScope.inset(inset: Float, block: DrawScope.() -> Unit): Unit

Convenience method modifies the DrawScope bounds to inset both left, top, right and bottom bounds by inset. After this method is invoked, the coordinate space is returned to the state before this inset was applied.

Parameters
inset: Float

number of pixels to inset left, top, right, and bottom bounds.

block: DrawScope.() -> Unit

lambda that is called to issue additional drawing commands within the modified coordinate space

inset

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

Convenience method modifies the DrawScope bounds to inset both left and right bounds by horizontal as well as the top and bottom by vertical. After this method is invoked, the coordinate space is returned to the state before this inset was applied.

Parameters
horizontal: Float = 0.0f

number of pixels to inset both left and right bounds. Zero by default

vertical: Float = 0.0f

Optional number of pixels to inset both top and bottom bounds. Zero by default

block: DrawScope.() -> Unit

lambda that is called to issue additional drawing commands within the modified coordinate space

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). After this method is invoked, the coordinate space is returned to the state before the inset was applied.

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

inline fun DrawScope.rotate(degrees: Float, pivot: Offset = center, 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

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

block: DrawScope.() -> Unit

lambda that is called to issue drawing commands within the rotated coordinate space

inline fun DrawTransform.rotateRad(radians: Float, pivot: Offset = center): 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

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

inline fun DrawScope.rotateRad(radians: Float, pivot: Offset = center, 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

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

block: DrawScope.() -> Unit

lambda that is called to issue drawing commands within the rotated coordinate space

inline fun DrawTransform.scale(scale: Float, pivot: Offset = center): Unit

Add an axis-aligned scale to the current transform, scaling uniformly in both directions by the provided scale factor at the pivot coordinate. The pivot coordinate remains unchanged by the scale transformation.

Parameters
scale: Float

The amount to scale

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

inline fun DrawScope.scale(scale: Float, pivot: Offset = center, block: DrawScope.() -> Unit): Unit

Add an axis-aligned scale to the current transform, scaling both the horizontal direction and the vertical direction at the given pivot coordinate. The pivot coordinate remains unchanged by the scale transformation. After this method is invoked, the coordinate space is returned to the state before the scale was applied.

Parameters
scale: Float

The amount to scale uniformly in both directions

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

block: DrawScope.() -> Unit

lambda used to issue drawing commands within the scaled coordinate space

inline fun DrawScope.scale(
    scaleX: Float,
    scaleY: Float,
    pivot: Offset = center,
    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. After this method is invoked, the coordinate space is returned to the state before the scale was applied.

Parameters
scaleX: Float

The amount to scale in X

scaleY: Float

The amount to scale in Y

pivot: Offset = center

The coordinate for the pivot point, defaults to the center of the coordinate space

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.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.drawscope.draw
import androidx.compose.ui.graphics.drawscope.inset
import androidx.compose.ui.graphics.drawscope.rotate
import androidx.compose.ui.graphics.drawscope.withTransform
import androidx.compose.ui.unit.dp

Canvas(Modifier.size(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, center)
            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