`draw_canvas`

fn def draw_canvas(mut dst: Canvas, src: Canvas, x: Int, y: Int)

Composite src onto dst with its top-left corner at (x, y).

Clipped to dst’s bounds and to its active clip region – both a rectangle clip and a clip path – so a source hanging off an edge draws its visible part rather than raising or wrapping. Fully transparent source pixels leave the destination untouched.

Args:

dst (Canvas): Canvas composited onto.
src (Canvas): Canvas to draw. Unchanged.
x (Int): Destination column for src’s left edge.
y (Int): Destination row for src’s top edge.

fn def draw_canvas(mut dst: Canvas, src: Canvas, x: Int, y: Int, opacity: UInt8)

draw_canvas with the whole source scaled to opacity first – the usual way a layer is faded, without having to have rendered it translucent in the first place.

opacity multiplies each source pixel’s own alpha, so a pixel already half-transparent in a layer drawn at half opacity ends up at a quarter. 255 leaves the source’s alpha untouched and is what the three-argument overload passes.

Under a canvas transform only its translation applies: (x, y) maps through the transform and src is composited there unscaled and unrotated. Pass a Matrix2D instead to draw it scaled or rotated.

Args:

dst (Canvas): Canvas composited onto.
src (Canvas): Canvas to draw. Unchanged.
x (Int): Destination column for src’s left edge.
y (Int): Destination row for src’s top edge.
opacity (UInt8): Scales every source pixel’s alpha, 255 for unchanged.

fn def draw_canvas(mut dst: Canvas, src: Canvas, x: Int, y: Int, mask: Mask)

draw_canvas through a mask: each source pixel’s alpha is scaled by the mask’s coverage at the same position in the source before it is composited, so a layer fades where the mask does. The mask is aligned with the source’s top-left corner, not the destination’s; source pixels the mask does not reach draw nothing.

Args:

dst (Canvas): Canvas composited onto.
src (Canvas): Canvas to draw. Unchanged.
x (Int): Destination column for src’s left edge.
y (Int): Destination row for src’s top edge.
mask (Mask): Coverage over src, see canvas.mask.

fn def draw_canvas(mut dst: Canvas, src: Canvas, matrix: Matrix2D, opacity: Float64 = 1, filter: Filter = Filter.BILINEAR)

Draw src onto dst through matrix: scaled, rotated, skewed or mirrored, the equivalent of cairo_set_source_surface under the CTM or the HTML5 canvas’s drawImage with a transform.

matrix maps the source’s texel space – pixel (i, j) covering the unit square from (i, j) to (i + 1, j + 1), so a w x h source occupies [0, w] x [0, h] – to destination pixels. When dst carries a transform, matrix is applied first and the canvas transform second, so matrix is read in the coordinates the caller is drawing in.

Every destination pixel in the mapped rectangle’s bounding box is mapped back through the inverse and sampled at that point, under filter. A pixel whose sample point falls outside the source is not drawn; along the outer edge, a bilinear sample’s missing neighbors are the edge pixel itself.

Bilinear interpolation weights each neighbor premultiplied by its alpha and divides the mix back out, so a transparent neighbor contributes its alpha and none of its color. Alpha itself is interpolated the same way the colors are.

Writes go through the canvas’s pixel-write path, so the active rectangle clip, clip path and blend mode all apply. A translation by whole pixels is composited by the integer blit above, which is what either filter samples there.

Args:

dst (Canvas): Canvas drawn onto.
src (Canvas): Canvas to draw. Unchanged.
matrix (Matrix2D): Map from src’s texel space to destination pixels.
opacity (Float64): Scales every source pixel’s alpha, 1.0 for unchanged.
filter (Filter): How the source is sampled between its pixels.

Raises:

Error: matrix, composed with the canvas transform, is singular, so it collapses the source to a line or a point.

fn def draw_canvas(mut dst: Canvas, src: Canvas, sx: Int, sy: Int, sw: Int, sh: Int, matrix: Matrix2D, opacity: Float64 = 1, filter: Filter = Filter.BILINEAR)

draw_canvas through a matrix, drawing only the sw x sh rectangle of src at (sx, sy) – one sprite out of a sheet, or one panel out of a rendered figure.

matrix maps the cropped rectangle’s own texel space, its top-left corner at (0, 0), so the crop and the placement are independent: changing (sx, sy) picks a different part of the source without moving where it lands. A rectangle reaching past an edge of src draws the part that exists, in the place that part maps to.

Sampling, edge handling, opacity and clipping are the whole-source overload’s.

Args:

dst (Canvas): Canvas drawn onto.
src (Canvas): Canvas to draw from. Unchanged.
sx (Int): Left edge of the source rectangle, in source pixels.
sy (Int): Top edge of the source rectangle, in source pixels.
sw (Int): Width of the source rectangle, in source pixels.
sh (Int): Height of the source rectangle, in source pixels.
matrix (Matrix2D): Map from the rectangle’s texel space to destination pixels.
opacity (Float64): Scales every source pixel’s alpha, 1.0 for unchanged.
filter (Filter): How the source is sampled between its pixels.

Raises:

Error: matrix, composed with the canvas transform, is singular, so it collapses the source to a line or a point.

Filter draw_image