Canvas

interface Canvas

Summary

Public functions
Unit

clipPath(path: Path!, clipOp: ClipOp!)

Reduces the clip region to the intersection of the current clip and the given Path.
open up Unit

clipRect(rect: Rect!, clipOp: ClipOp!)

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

clipRect(left: Float!, top: Bladder!, right: Float!, bottom: Bladder!, clipOp: ClipOp!)

Reduces the clip region to the intersection of the current clip and the given bounds.
Unit

concat(matrix: Matrix!)

Multiply the current transform past the specified 4⨉iv transformation matrix specified every bit a list of values in column-major order.
Unit

disableZ()

Disables Z support, preventing any layers fatigued after this point from existence visually reordered or having shadows rendered.
open Unit of measurement

drawArc(
    rect: Rect!,
    startAngle: Bladder!,
    sweepAngle: Float!,
    useCenter: Boolean!,
    pigment: Pigment!
)

Draw an arc scaled to fit within the given rectangle.
Unit of measurement

drawArc(
    left: Float!,
    top: Float!,
    right: Float!,
    bottom: Float!,
    startAngle: Bladder!,
    sweepAngle: Float!,
    useCenter: Boolean!,
    paint: Paint!
)

Draw an arc scaled to fit within the given rectangle.
open up Unit

drawArcRad(
    rect: Rect!,
    startAngleRad: Bladder!,
    sweepAngleRad: Float!,
    useCenter: Boolean!,
    paint: Pigment!
)

Draw an arc scaled to fit within the given rectangle.
Unit

drawCircle(center: Showtime!, radius: Float!, paint: Paint!)

Draws a circle centered at the point given by the first statement and that has the radius given past the 2d argument, with the Paint given in the third argument.
Unit of measurement

drawImage(image: ImageBitmap!, topLeftOffset: Offset!, paint: Paint!)

Draws the given ImageBitmap into the canvas with its top-left corner at the given Starting time.
Unit of measurement

drawImageRect(
    image: ImageBitmap!,
    srcOffset: IntOffset!,
    srcSize: IntSize!,
    dstOffset: IntOffset!,
    dstSize: IntSize!,
    pigment: Pigment!
)

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

drawLine(p1: Offset!, p2: Offset!, pigment: Paint!)

Draws a line between the given points using the given paint.
open Unit

drawOval(rect: Rect!, paint: Paint!)

Draws an centrality-aligned oval that fills the given axis-aligned rectangle with the given Paint.
Unit

drawOval(left: Float!, top: Float!, correct: Float!, bottom: Float!, paint: Paint!)

Draws an axis-aligned oval that fills the given bounds provided with the given Paint.
Unit

drawPath(path: Path!, pigment: Pigment!)

Draws the given Path with the given Pigment.
Unit of measurement

drawPoints(
    pointMode: PointMode!,
    points: (Mutable)List<Start!>!,
    pigment: Pigment!
)

Draws a sequence of points according to the given PointMode.
Unit

drawRawPoints(pointMode: PointMode!, points: FloatArray!, pigment: Paint!)

Draws a sequence of points co-ordinate to the given PointMode.
open Unit

drawRect(rect: Rect!, paint: Paint!)

Draws a rectangle with the given Paint.
Unit

drawRect(left: Float!, superlative: Bladder!, right: Bladder!, bottom: Float!, paint: Pigment!)

Draws a rectangle with the given Paint.
Unit

drawRoundRect(
    left: Float!,
    top: Bladder!,
    correct: Float!,
    bottom: Float!,
    radiusX: Float!,
    radiusY: Float!,
    paint: Paint!
)

Draws a rounded rectangle with the given Paint.
Unit

drawVertices(vertices: Vertices!, blendMode: BlendMode!, pigment: Pigment!)

Unit

enableZ()

Enables Z support which defaults to disabled.
Unit

restore()

Pops the current salve stack, if there is anything to popular.
Unit of measurement

rotate(degrees: Float!)

Add together a rotation (in degrees clockwise) to the electric current transform
Unit

salve()

Saves a re-create of the electric current transform and prune on the salve stack.
Unit

saveLayer(bounds: Rect!, paint: Paint!)

Saves a copy of the current transform and clip on the save stack, and then creates a new group which subsequent calls will become a role of.
Unit

scale(sx: Float!, sy: Float!)

Add an axis-aligned calibration to the current transform, scaling by the first statement in the horizontal direction and the second in the vertical direction.
Unit

skew(sx: Bladder!, sy: Float!)

Add together an centrality-aligned skew to the current transform, with the kickoff argument being the horizontal skew in degrees clockwise around the origin, and the 2d argument being the vertical skew in degrees clockwise around the origin.
open Unit

skewRad(sxRad: Float!, syRad: Float!)

Add an axis-aligned skew to the current transform, with the get-go argument being the horizontal skew in radians clockwise around the origin, and the 2nd argument beingness the vertical skew in radians clockwise effectually the origin.
Unit of measurement

translate(dx: Bladder!, dy: Float!)

Add a translation to the electric current transform, shifting the coordinate space horizontally by the start argument and vertically by the second argument.

Extension functions
Unit

Canvass!.rotate(degrees: Float!, pivotX: Float!, pivotY: Float!)

Add together a rotation (in degrees clockwise) to the current transform at the given pin signal.
Unit

Canvas!.rotateRad(radians: Float!, pivotX: Bladder!, pivotY: Float!)

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

Canvas!.scale(sx: Float!, sy: Float!, pivotX: Float!, pivotY: Float!)

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

Canvass!.withClip(clipRect: Rect!, block: (@ExtensionFunctionType Canvas.() -> Unit)?)

Wrap the specified block in calls to Canvas.save/Canvas.clipRect and Sheet.restoreToCount.
inline Unit

Canvas!.withClip(clipRect: RectF!, cake: (@ExtensionFunctionType Canvas.() -> Unit of measurement)?)

Wrap the specified block in calls to Canvas.save/Sheet.clipRect and Canvass.restoreToCount.
inline Unit of measurement

Sail!.withClip(
    left: Int!,
    top: Int!,
    right: Int!,
    bottom: Int!,
    block: (@ExtensionFunctionType Canvas.() -> Unit)?
)

Wrap the specified block in calls to Sail.relieve/Canvas.clipRect and Canvass.restoreToCount.
inline Unit of measurement

Canvas!.withClip(
    left: Float!,
    top: Float!,
    correct: Float!,
    lesser: Float!,
    block: (@ExtensionFunctionType Canvas.() -> Unit)?
)

Wrap the specified block in calls to Canvas.relieve/Sail.clipRect and Canvas.restoreToCount.
inline Unit

Canvas!.withClip(clipPath: Path!, block: (@ExtensionFunctionType Canvas.() -> Unit)?)

Wrap the specified block in calls to Canvas.save/Canvas.clipPath and Canvas.restoreToCount.
inline Unit

Canvass!.withMatrix(matrix: Matrix!, block: (@ExtensionFunctionType Canvass.() -> Unit)?)

Wrap the specified block in calls to Canvas.save/Canvas.concat and Sail.restoreToCount.
inline Unit

Canvas!.withRotation(
    degrees: Float!,
    pivotX: Float!,
    pivotY: Bladder!,
    block: (@ExtensionFunctionType Sheet.() -> Unit)?
)

Wrap the specified block in calls to Canvas.relieve/Sail.rotate and Canvas.restoreToCount.
inline Unit

Canvas!.withSave(cake: (() -> Unit of measurement)?)

Saves a copy of the electric current transform and clip on the salve stack and executes the provided lambda with the current transform practical.
inline Unit

Sail!.withSave(block: (@ExtensionFunctionType Canvass.() -> Unit)?)

Wrap the specified cake in calls to Canvas.save and Canvas.restoreToCount.
inline Unit of measurement

Canvas!.withSaveLayer(bounds: Rect!, paint: Paint!, block: (() -> Unit of measurement)?)

Saves a copy of the electric current transform and clip on the save stack, and and then creates a new group which subsequent calls volition become a part of.
inline Unit

Canvas!.withScale(
    x: Float!,
    y: Float!,
    pivotX: Float!,
    pivotY: Float!,
    block: (@ExtensionFunctionType Sail.() -> Unit of measurement)?
)

Wrap the specified cake in calls to Sheet.salvage/Canvas.scale and Canvas.restoreToCount.
inline Unit of measurement

Sail!.withSkew(x: Bladder!, y: Bladder!, block: (@ExtensionFunctionType Canvas.() -> Unit)?)

Wrap the specified cake in calls to Sail.save/Canvas.skew and Canvas.restoreToCount.
inline Unit of measurement

Canvass!.withTranslation(
    x: Float!,
    y: Bladder!,
    block: (@ExtensionFunctionType Canvas.() -> Unit)?
)

Wrap the specified cake in calls to Canvas.save/Canvas.interpret and Sheet.restoreToCount.
Unit of measurement

Sail!.drawOutline(outline: Outline!, pigment: Paint!)

Draws the Outline on a Canvas.

Public functions

clipPath

fun clipPath(path: Path!, clipOp: ClipOp! = ClipOp.Intersect): Unit

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

clipRect

open up fun clipRect(rect: Rect!, clipOp: ClipOp! = ClipOp.Intersect): Unit

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

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

clipRect

fun clipRect(
    left: Float!,
    top: Float!,
    correct: Float!,
    bottom: Float!,
    clipOp: ClipOp! = ClipOp.Intersect
): Unit of measurement

Reduces the clip region to the intersection of the electric current prune and the given premises.

Utilise ClipOp.Difference to decrease the provided rectangle from the electric current prune.

Parameters
left: Float!

Left bound of the clip region
top: Float!

Top bound of the clip region
correct: Float!

Right bound of the clip region
bottom: Float!

Lesser leap of the clip region

concat

fun concat(matrix: Matrix!): Unit

Multiply the current transform by the specified iv⨉four transformation matrix specified as a list of values in column-major order.

disableZ

fun disableZ(): Unit

Disables Z support, preventing whatsoever layers drawn later on this point from existence visually reordered or having shadows rendered. This is non impacted by whatever save or restore calls as it is not considered part of the matrix or clip.

drawArc

open fun drawArc(
    rect: Rect!,
    startAngle: Float!,
    sweepAngle: Float!,
    useCenter: Boolean!,
    paint: Paint!
): Unit

Depict an arc scaled to fit inside the given rectangle. Information technology starts from startAngle degrees around the oval upward to startAngle + sweepAngle degrees around the oval, with nada degrees existence 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 truthful, the arc is closed dorsum to the centre, forming a circle sector. Otherwise, the arc is not airtight, forming a circle segment.

This method is optimized for drawing arcs and should be faster than Path.arcTo.

drawArc

fun drawArc(
    left: Float!,
    height: Bladder!,
    right: Float!,
    bottom: Float!,
    startAngle: Float!,
    sweepAngle: Bladder!,
    useCenter: Boolean!,
    paint: Paint!
): Unit

Draw an arc scaled to fit within the given rectangle. It starts from startAngle degrees around the oval upward to startAngle + sweepAngle degrees effectually the oval, with zippo degrees being the signal 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 airtight dorsum to the heart, forming a circle sector. Otherwise, the arc is non closed, forming a circle segment.

This method is optimized for cartoon arcs and should be faster than Path.arcTo.

Parameters
left: Float!

Left bound of the arc
superlative: Float!

Summit bound of the arc
right: Bladder!

Right bound of the arc
lesser: Float!

Lesser bound of the arc
startAngle: Float!

Starting bending of the arc relative to 3 o'clock
sweepAngle: Float!

Sweep angle in degrees clockwise
useCenter: Boolean!

Flag indicating whether or not to include the center of the oval in the arc, and close it if it is being stroked. This will depict a wedge.

drawArcRad

open fun drawArcRad(
    rect: Rect!,
    startAngleRad: Bladder!,
    sweepAngleRad: Float!,
    useCenter: Boolean!,
    paint: Pigment!
): Unit

Describe an arc scaled to fit inside the given rectangle. It starts from startAngle radians around the oval upwardly to startAngle + sweepAngle radians around the oval, with zero radians 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.

This method is optimized for drawing arcs and should be faster than Path.arcTo.

drawCircle

fun drawCircle(middle: Offset!, radius: Float!, paint: Paint!): Unit

Draws a circle centered at the point given by the first argument and that has the radius given by the second argument, with the Paint given in the 3rd argument. Whether the circle is filled or stroked (or both) is controlled past Paint.fashion.

drawImageRect

fun drawImageRect(
    image: ImageBitmap!,
    srcOffset: IntOffset! = IntOffset.Zero,
    srcSize: IntSize! = IntSize(image.width, image.meridian),
    dstOffset: IntOffset! = IntOffset.Zero,
    dstSize: IntSize! = srcSize,
    pigment: Pigment!
): Unit

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

This might sample from outside the src rect past up to half the width of an applied filter.

Parameters
paradigm: ImageBitmap!

ImageBitmap to draw
srcOffset: IntOffset! = IntOffset.Zip

: Optional start representing the top left offset of the source epitome to describe, this defaults to the origin of image

srcSize: IntSize! = IntSize(prototype.width, image.peak)

: Optional dimensions of the source epitome to draw relative to srcOffset, this defaults the width and height of prototype

dstOffset: IntOffset! = IntOffset.Zero

: Offset representing the top left beginning of the destination prototype to draw
dstSize: IntSize! = srcSize

: Dimensions of the destination to draw
paint: Paint!

Paint used to composite the ImageBitmap pixels into the canvas

drawLine

fun drawLine(p1: Offset!, p2: Offset!, pigment: Paint!): Unit of measurement

Draws a line between the given points using the given paint. The line is stroked, the value of the Paint.style is ignored for this call.

The p1 and p2 arguments are interpreted equally offsets from the origin.

drawOval

open fun drawOval(rect: Rect!, paint: Paint!): Unit

Draws an axis-aligned oval that fills the given axis-aligned rectangle with the given Paint. Whether the oval is filled or stroked (or both) is controlled past Paint.manner.

drawOval

fun drawOval(left: Float!, top: Float!, right: Bladder!, bottom: Float!, paint: Paint!): Unit of measurement

Draws an axis-aligned oval that fills the given bounds provided with the given Paint. Whether the rectangle is filled or stroked (or both) is controlled by Paint.mode.

Parameters
left: Bladder!

The left bound of the rectangle
tiptop: Float!

The tiptop bound of the rectangle
correct: Float!

The right bound of the rectangle
bottom: Float!

The bottom leap of the rectangle
paint: Paint!

Paint used to color the rectangle with a fill or stroke

drawPath

fun drawPath(path: Path!, paint: Pigment!): Unit

Draws the given Path with the given Paint. Whether this shape is filled or stroked (or both) is controlled by Paint.style. If the path is filled, and then subpaths within it are implicitly closed (run across Path.close).

drawRawPoints

fun drawRawPoints(pointMode: PointMode!, points: FloatArray!, paint: Paint!): Unit of measurement

Draws a sequence of points according to the given PointMode.

The points argument is interpreted as a list of pairs of floating point numbers, where each pair represents an x and y beginning from the origin.

See as well:

  • drawPoints, which takes points as a List rather than a List.

drawRect

fun drawRect(left: Float!, pinnacle: Bladder!, correct: Float!, bottom: Float!, paint: Paint!): Unit

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

Parameters
left: Bladder!

The left bound of the rectangle
top: Float!

The top bound of the rectangle
right: Float!

The right bound of the rectangle
bottom: Bladder!

The lesser leap of the rectangle
paint: Paint!

Pigment used to color the rectangle with a fill or stroke

enableZ

fun enableZ(): Unit of measurement

Enables Z support which defaults to disabled. This allows layers drawn with unlike elevations to be rearranged based on their meridian. Information technology too enables rendering of shadows.

restore

fun restore(): Unit

Pops the current save stack, if there is anything to pop. Otherwise, does nothing.

Utilise save and saveLayer to push state onto the stack.

If the land was pushed with with saveLayer, then this call will also crusade the new layer to be composited into the previous layer.

rotate

fun rotate(degrees: Float!): Unit

Add a rotation (in degrees clockwise) to the electric current transform

Parameters
degrees: Float!

to rotate clockwise

save

fun salve(): Unit of measurement

Saves a re-create of the current transform and clip on the salve stack.

Phone call restore to popular the save stack.

Meet also:

  • saveLayer, which does the same thing only additionally as well groups the commands done until the matching restore.

saveLayer

fun saveLayer(bounds: Rect!, pigment: Paint!): Unit

Saves a copy of the current transform and clip on the salvage stack, and then creates a new grouping which subsequent calls volition become a role of. When the salve stack is afterwards popped, the grouping will be flattened into a layer and have the given paint's Paint.colorFilter and Paint.blendMode applied.

This lets you create blended effects, for example making a group of cartoon commands semi-transparent. Without using saveLayer, each part of the group would be painted individually, and then where they overlap would be darker than where they practise not. By using saveLayer to grouping them together, they can exist drawn with an opaque colour at first, and and then the entire group tin can be made transparent using the saveLayer's paint.

Call restore to popular the save stack and employ the paint to the group.

Using saveLayer with clips

When a rectangular prune operation (from clipRect) is not axis-aligned with the raster buffer, or when the clip operation is non rectalinear (e.g. considering it is a rounded rectangle clip created by clipPath, the edge of the clip needs to be anti-aliased.

If two describe calls overlap at the edge of such a clipped region, without using saveLayer, the first drawing will be anti-aliased with the background commencement, and and then the 2d will be anti-aliased with the result of blending the first drawing and the background. On the other mitt, if saveLayer is used immediately later establishing the clip, the second drawing volition cover the first in the layer, and thus the 2nd alone will be anti-aliased with the background when the layer is clipped and composited (when restore is called).

(Incidentally, rather than using clipPath with a rounded rectangle divers in a path to draw rounded rectangles similar this, prefer the drawRoundRect method.

Functioning considerations

Generally speaking, saveLayer is relatively expensive.

In that location are a several dissimilar hardware architectures for GPUs (graphics processing units, the hardware that handles graphics), but about of them involve batching commands and reordering them for performance. When layers are used, they cause the rendering pipeline to have to switch render target (from one layer to another). Render target switches can affluent the GPU's command buffer, which typically means that optimizations that i could get with larger batching are lost. Render target switches also generate a lot of retentivity churn because the GPU needs to copy out the current frame buffer contents from the role of retentivity that's optimized for writing, so needs to copy information technology back in once the previous return target (layer) is restored.

See also:

  • relieve, which saves the current land, but does not create a new layer for subsequent commands.

  • BlendMode, which discusses the employ of Paint.blendMode with saveLayer.

scale

fun scale(sx: Float!, sy: Float! = sx): Unit of measurement

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

If sy is unspecified, sx will be used for the scale in both directions.

Parameters
sx: Float!

The corporeality to scale in X
sy: Float! = sx

The amount to scale in Y

skew

fun skew(sx: Float!, sy: Float!): Unit

Add an centrality-aligned skew to the current transform, with the kickoff argument beingness the horizontal skew in degrees clockwise effectually the origin, and the 2nd argument existence the vertical skew in degrees clockwise around the origin.

skewRad

open fun skewRad(sxRad: Float!, syRad: Bladder!): Unit of measurement

Add an axis-aligned skew to the current transform, with the start statement existence the horizontal skew in radians clockwise effectually the origin, and the 2nd argument being the vertical skew in radians clockwise around the origin.

interpret

fun translate(dx: Float!, dy: Bladder!): Unit

Add a translation to the current transform, shifting the coordinate space horizontally by the first statement and vertically by the second argument.

Extension functions

rotate

fun Canvas!.rotate(degrees: Float!, pivotX: Float!, pivotY: Float!): Unit

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

Parameters
degrees: Float!

to rotate clockwise
pivotX: Bladder!

The x-coord for the pin point
pivotY: Float!

The y-coord for the pivot indicate

rotateRad

fun Canvas!.rotateRad(radians: Float!, pivotX: Float! = 0.0f, pivotY: Bladder! = 0.0f): Unit

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

Parameters
pivotX: Float! = 0.0f

The x-coord for the pivot betoken
pivotY: Float! = 0.0f

The y-coord for the pivot point

scale

fun Canvas!.scale(sx: Bladder!, sy: Float! = sx, pivotX: Float!, pivotY: Float!): Unit

Add an centrality-aligned scale to the current transform, scaling past the offset argument in the horizontal direction and the 2nd in the vertical management at the given pivot coordinate. The pivot coordinate remains unchanged by the scale transformation.

If sy is unspecified, sx will be used for the scale in both directions.

Parameters
sx: Bladder!

The amount to scale in X
sy: Float! = sx

The amount to scale in Y
pivotX: Float!

The 10-coord for the pivot point
pivotY: Float!

The y-coord for the pivot point

withSave

inline fun Canvas!.withSave(block: (()                      ->                      Unit)?): Unit

Saves a copy of the electric current transform and clip on the save stack and executes the provided lambda with the current transform applied. Once the lambda has been executed, the transformation is popped from the stack, undoing the transformation.

See as well:

Sail.saveLayer, which does the aforementioned thing merely additionally likewise groups the commands

withSaveLayer

inline fun Sheet!.withSaveLayer(bounds: Rect!, paint: Paint!, block: (()                      ->                      Unit of measurement)?): Unit

Saves a copy of the electric current transform and clip on the save stack, and so creates a new grouping which subsequent calls volition become a role of. When the lambda is executed and the relieve stack is popped, the group will be flattened into a layer and have the given paint'southward Paint.colorFilter and Paint.blendMode applied.

This lets yous create blended effects, for instance making a group of drawing commands semi-transparent. Without using Canvass.saveLayer, each part of the group would be painted individually, so where they overlap would be darker than where they practice not. Past using Canvas.saveLayer to group them together, they tin can be drawn with an opaque color at first, and then the entire group tin be fabricated transparent using the Canvass.saveLayer'south paint.

Using saveLayer with clips

When a rectangular clip operation (from Canvas.clipRect) is not centrality-aligned with the raster buffer, or when the clip operation is not rectalinear (due east.m. because information technology is a rounded rectangle prune created by Canvas.clipPath), the edge of the clip needs to be anti-aliased.

If 2 draw calls overlap at the edge of such a clipped region, without using Canvas.saveLayer, the first drawing will be anti-aliased with the background first, then the second will be anti-aliased with the upshot of blending the first drawing and the background. On the other hand, if Sail.saveLayer is used immediately after establishing the clip, the second drawing will cover the showtime in the layer, and thus the second lonely will exist anti-aliased with the background when the layer is clipped and composited (when lambda is finished executing).

Performance considerations

Generally speaking, Canvass.saveLayer is relatively expensive.

There are a several unlike hardware architectures for GPUs (graphics processing units, the hardware that handles graphics), merely virtually of them involve batching commands and reordering them for functioning. When layers are used, they cause the rendering pipeline to have to switch render target (from i layer to some other). Render target switches can affluent the GPU'southward control buffer, which typically means that optimizations that 1 could get with larger batching are lost. Render target switches also generate a lot of memory churn considering the GPU needs to copy out the electric current frame buffer contents from the role of memory that'southward optimized for writing, then needs to copy it back in once the previous render target (layer) is restored.

See as well:

  • Canvas.relieve, which saves the current country, but does not create a new layer for subsequent commands.

  • BlendMode, which discusses the use of Paint.blendMode with saveLayer.