DrawScope

Interface
Common
@DrawScopeMarker
@JvmDefaultWithCompatibility
interface DrawScope : Density

Creates a scoped drawing environment with the provided Canvas. This provides a declarative, stateless API to draw shapes and paths without requiring consumers to maintain underlying Canvas state information. DrawScope implementations are also provided sizing information and transformations are done relative to the local translation. That is left and top coordinates are always the origin and the right and bottom coordinates are always the specified width and height respectively. Drawing content is not clipped, so it is possible to draw outside of the specified bounds.

Properties

Common
val drawContext: DrawContext

The current DrawContext that contains the dependencies needed to create the drawing environment

Common
val center: Offset

Center of the current bounds of the drawing environment

Common
val size: Size

Provides the dimensions of the current drawing environment

Common
val layoutDirection: LayoutDirection

The layout direction of the layout being drawn in.

Functions

fun drawLine(
        brush: Brush,
        start: Offset,
        end: Offset,
        strokeWidth: Float = Stroke.HairlineWidth,
        cap: StrokeCap = Stroke.DefaultCap,
        pathEffect: PathEffect? = null,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a line between the given points using the given paint. The line is stroked.

Parameters
brush the color or fill to be applied to the line
start first point of the line to be drawn
end second point of the line to be drawn
strokeWidth stroke width to apply to the line
cap treatment applied to the ends of the line segment
pathEffect optional effect or pattern to apply to the line
alpha opacity to be applied to the brush from 0.0f to 1.0f representing fully transparent to fully opaque respectively
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode the blending algorithm to apply to the brush 
fun drawLine(
        color: Color,
        start: Offset,
        end: Offset,
        strokeWidth: Float = Stroke.HairlineWidth,
        cap: StrokeCap = Stroke.DefaultCap,
        pathEffect: PathEffect? = null,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a line between the given points using the given paint. The line is stroked.

Parameters
color the color to be applied to the line
start first point of the line to be drawn
end second point of the line to be drawn
strokeWidth The stroke width to apply to the line
cap treatment applied to the ends of the line segment
pathEffect optional effect or pattern to apply to the line
alpha opacity to be applied to the color from 0.0f to 1.0f representing fully transparent to fully opaque respectively
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode the blending algorithm to apply to the color 
fun drawRect(
        brush: Brush,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a rectangle with the given offset and size. If no offset from the top left is provided, it is drawn starting from the origin of the current translation. If no size is provided, the size of the current environment is used.

Parameters
brush The color or fill to be applied to the rectangle
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
alpha Opacity to be applied to the brush from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the rectangle is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to apply to destination 
fun drawRect(
        color: Color,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a rectangle with the given offset and size. If no offset from the top left is provided, it is drawn starting from the origin of the current translation. If no size is provided, the size of the current environment is used.

Parameters
color The color to be applied to the rectangle
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
alpha Opacity to be applied to the color from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the rectangle is stroked or filled in
colorFilter ColorFilter to apply to the color source pixels
blendMode Blending algorithm to apply to destination 
fun drawImage(
        image: ImageBitmap,
        topLeft: Offset = Offset.Zero,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws the given ImageBitmap into the canvas with its top-left corner at the given Offset. The image is composited into the canvas using the given Paint.

Parameters
image The ImageBitmap to draw
topLeft Offset from the local origin of 0, 0 relative to the current translation
alpha Opacity to be applied to image from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Specifies whether the image is to be drawn filled in or as a rectangular stroke
colorFilter ColorFilter to apply to the image when drawn into the destination
blendMode Blending algorithm to apply to destination 
fun drawImage(
        image: ImageBitmap,
        srcOffset: IntOffset = IntOffset.Zero,
        srcSize: IntSize = IntSize(image.width, image.height),
        dstOffset: IntOffset = IntOffset.Zero,
        dstSize: IntSize = srcSize,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws the subset of the given image described by the src argument into the canvas in the axis-aligned rectangle given by the dst argument.

If no src rect is provided, the entire image is scaled into the corresponding destination bounds

Parameters
image The source image to draw
srcOffset Optional offset representing the top left offset of the source image to draw, this defaults to the origin of image
srcSize Optional dimensions of the source image to draw relative to srcOffset, this defaults the width and height of image
dstOffset Optional offset representing the top left offset of the destination to draw the given image, this defaults to the origin of the current translation tarting top left offset in the destination to draw the image
dstSize Optional dimensions of the destination to draw, this defaults to srcSize
alpha Opacity to be applied to image from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Specifies whether the image is to be drawn filled in or as a rectangular stroke
colorFilter ColorFilter to apply to the image when drawn into the destination
blendMode Blending algorithm to apply to destination 
fun drawImage(
        image: ImageBitmap,
        srcOffset: IntOffset = IntOffset.Zero,
        srcSize: IntSize = IntSize(image.width, image.height),
        dstOffset: IntOffset = IntOffset.Zero,
        dstSize: IntSize = srcSize,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
        filterQuality: FilterQuality = DefaultFilterQuality,
    )

Draws the subset of the given image described by the src argument into the canvas in the axis-aligned rectangle given by the dst argument.

If no src rect is provided, the entire image is scaled into the corresponding destination bounds

Parameters
image The source image to draw
srcOffset Optional offset representing the top left offset of the source image to draw, this defaults to the origin of image
srcSize Optional dimensions of the source image to draw relative to srcOffset, this defaults the width and height of image
dstOffset Optional offset representing the top left offset of the destination to draw the given image, this defaults to the origin of the current translation tarting top left offset in the destination to draw the image
dstSize Optional dimensions of the destination to draw, this defaults to srcSize
alpha Opacity to be applied to image from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Specifies whether the image is to be drawn filled in or as a rectangular stroke
colorFilter ColorFilter to apply to the image when drawn into the destination
blendMode Blending algorithm to apply to destination
filterQuality Sampling algorithm applied to the image when it is scaled and drawn into the destination. The default is FilterQuality.Low which scales using a bilinear sampling algorithm 
fun drawRoundRect(
        brush: Brush,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        cornerRadius: CornerRadius = CornerRadius.Zero,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a rounded rectangle with the provided size, offset and radii for the x and y axis respectively. This rectangle is drawn with the provided Brush parameter and is filled or stroked based on the given DrawStyle

Parameters
brush The color or fill to be applied to the rounded rectangle
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
cornerRadius Corner radius of the rounded rectangle, negative radii values are clamped to 0
alpha Opacity to be applied to rounded rectangle from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Specifies whether the rounded rectangle is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the brush 
fun drawRoundRect(
        color: Color,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        cornerRadius: CornerRadius = CornerRadius.Zero,
        style: DrawStyle = Fill,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a rounded rectangle with the given Paint. Whether the rectangle is filled or stroked (or both) is controlled by Paint.style.

Parameters
color The color to be applied to the rounded rectangle
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
cornerRadius Corner radius of the rounded rectangle, negative radii values are clamped to 0
alpha Opacity to be applied to rounded rectangle from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Specifies whether the rounded rectangle is stroked or filled in
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the color 
fun drawCircle(
        brush: Brush,
        radius: Float = size.minDimension / 2.0f,
        center: Offset = this.center,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a circle at the provided center coordinate and radius. If no center point is provided the center of the bounds is used.

Parameters
brush The color or fill to be applied to the circle
radius The radius of the circle
center The center coordinate where the circle is to be drawn
alpha Opacity to be applied to the circle from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the circle is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the brush 
fun drawCircle(
        color: Color,
        radius: Float = size.minDimension / 2.0f,
        center: Offset = this.center,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a circle at the provided center coordinate and radius. If no center point is provided the center of the bounds is used.

Parameters
color The color or fill to be applied to the circle
radius The radius of the circle
center The center coordinate where the circle is to be drawn
alpha Opacity to be applied to the circle from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the circle is stroked or filled in
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the brush 
fun drawOval(
        brush: Brush,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws an oval with the given offset and size. If no offset from the top left is provided, it is drawn starting from the origin of the current translation. If no size is provided, the size of the current environment is used.

Parameters
brush Color or fill to be applied to the oval
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
alpha Opacity to be applied to the oval from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the oval is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the brush 
fun drawOval(
        color: Color,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws an oval with the given offset and size. If no offset from the top left is provided, it is drawn starting from the origin of the current translation. If no size is provided, the size of the current environment is used.

Parameters
color Color to be applied to the oval
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the rectangle to draw
alpha Opacity to be applied to the oval from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the oval is stroked or filled in
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the brush 
fun drawArc(
        brush: Brush,
        startAngle: Float,
        sweepAngle: Float,
        useCenter: Boolean,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draw an arc scaled to fit inside the given rectangle. It starts from startAngle degrees around the oval up to startAngle + sweepAngle degrees around the oval, with zero degrees being the point on the right hand side of the oval that crosses the horizontal line that intersects the center of the rectangle and with positive angles going clockwise around the oval. If useCenter is true, the arc is closed back to the center, forming a circle sector. Otherwise, the arc is not closed, forming a circle segment.

Parameters
brush Color or fill to be applied to the arc
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the arc to draw
startAngle Starting angle in degrees. 0 represents 3 o'clock
sweepAngle Size of the arc in degrees that is drawn clockwise relative to startAngle
useCenter Flag indicating if the arc is to close the center of the bounds
alpha Opacity to be applied to the arc from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the arc is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the arc when it is drawn 
fun drawArc(
        color: Color,
        startAngle: Float,
        sweepAngle: Float,
        useCenter: Boolean,
        topLeft: Offset = Offset.Zero,
        size: Size = this.size.offsetSize(topLeft),
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draw an arc scaled to fit inside the given rectangle. It starts from startAngle degrees around the oval up to startAngle + sweepAngle degrees around the oval, with zero degrees being the point on the right hand side of the oval that crosses the horizontal line that intersects the center of the rectangle and with positive angles going clockwise around the oval. If useCenter is true, the arc is closed back to the center, forming a circle sector. Otherwise, the arc is not closed, forming a circle segment.

Parameters
color Color to be applied to the arc
topLeft Offset from the local origin of 0, 0 relative to the current translation
size Dimensions of the arc to draw
startAngle Starting angle in degrees. 0 represents 3 o'clock
sweepAngle Size of the arc in degrees that is drawn clockwise relative to startAngle
useCenter Flag indicating if the arc is to close the center of the bounds
alpha Opacity to be applied to the arc from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the arc is stroked or filled in
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the arc when it is drawn 
fun drawPath(
        path: Path,
        color: Color,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws the given Path with the given Color. Whether this shape is filled or stroked (or both) is controlled by DrawStyle. If the path is filled, then subpaths within it are implicitly closed (see Path.close).

Parameters
path Path to draw
color Color to be applied to the path
alpha Opacity to be applied to the path from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the path is stroked or filled in
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the path when it is drawn 
fun drawPath(
        path: Path,
        brush: Brush,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        style: DrawStyle = Fill,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws the given Path with the given Color. Whether this shape is filled or stroked (or both) is controlled by DrawStyle. If the path is filled, then subpaths within it are implicitly closed (see Path.close).

Parameters
path Path to draw
brush Brush to be applied to the path
alpha Opacity to be applied to the path from 0.0f to 1.0f representing fully transparent to fully opaque respectively
style Whether or not the path is stroked or filled in
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the path when it is drawn 
fun drawPoints(
        points: List<Offset>,
        pointMode: PointMode,
        color: Color,
        strokeWidth: Float = Stroke.HairlineWidth,
        cap: StrokeCap = StrokeCap.Butt,
        pathEffect: PathEffect? = null,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a sequence of points according to the given PointMode.

The points argument is interpreted as offsets from the origin.

Parameters
points List of points to draw with the specified PointMode
pointMode PointMode used to indicate how the points are to be drawn
color Color to be applied to the points
alpha Opacity to be applied to the path from 0.0f to 1.0f representing fully transparent to fully opaque respectively
strokeWidth The stroke width to apply to the line
cap Treatment applied to the ends of the line segment
pathEffect optional effect or pattern to apply to the point
colorFilter ColorFilter to apply to the color when drawn into the destination
blendMode Blending algorithm to be applied to the path when it is drawn 
fun drawPoints(
        points: List<Offset>,
        pointMode: PointMode,
        brush: Brush,
        strokeWidth: Float = Stroke.HairlineWidth,
        cap: StrokeCap = StrokeCap.Butt,
        pathEffect: PathEffect? = null,
        @FloatRange(from = 0.0, to = 1.0) alpha: Float = 1.0f,
        colorFilter: ColorFilter? = null,
        blendMode: BlendMode = DefaultBlendMode,
    )

Draws a sequence of points according to the given PointMode.

The points argument is interpreted as offsets from the origin.

Parameters
points List of points to draw with the specified PointMode
pointMode PointMode used to indicate how the points are to be drawn
brush Brush to be applied to the points
strokeWidth The stroke width to apply to the line
cap Treatment applied to the ends of the line segment
pathEffect optional effect or pattern to apply to the points
alpha Opacity to be applied to the path from 0.0f to 1.0f representing fully transparent to fully opaque respectively.
colorFilter ColorFilter to apply to the brush when drawn into the destination
blendMode Blending algorithm to be applied to the path when it is drawn 
fun GraphicsLayer.record(
        size: IntSize = [email protected](),
        block: DrawScope.() -> Unit,
    ) =
        record(this@DrawScope, [email protected], size) {
            [email protected](
                drawContext.density,
                drawContext.layoutDirection,
                drawContext.canvas,
                drawContext.size,
                drawContext.graphicsLayer,
                block,
            )
        }

Record the corresponding drawing commands for this GraphicsLayer instance using the Density, LayoutDirection and IntSize from the provided DrawScope as defaults. This will retarget the underlying canvas of the provided DrawScope to draw within the layer itself and reset it to the original canvas on the conclusion of this method call.

private fun Size.offsetSize(offset: Offset): Size

Helper method to offset the provided size with the offset in box width and height

Code Examples

DrawScopeSample

/**
 * Sample showing how to use CanvasScope to issue drawing commands into a given canvas as well as
 * providing transformations to the drawing environment
 */
@Composable
fun DrawScopeSample() {
    // Sample showing how to use the DrawScope receiver scope to issue
    // drawing commands
    Canvas(Modifier.size(120.dp)) {
        drawRect(color = Color.Gray) // Draw grey background
        // Inset content by 10 pixels on the left/right sides and 12 by the
        // top/bottom
        inset(10.0f, 12.0f) {
            val quadrantSize = size / 2.0f
            // Draw a rectangle within the inset bounds
            drawRect(size = quadrantSize, color = Color.Red)
            rotate(45.0f) { drawRect(size = quadrantSize, color = Color.Blue) }
        }
    }
}