compose
Mojo module 🡭
compose
Compositing one canvas onto another: everything else in this package draws shapes into a buffer, and this draws a buffer into a buffer.
Three things use it: layers, where each part of a figure is drawn onto
its own transparent canvas and composed in order; marker caching, where
one rasterized marker is stamped per point instead of re-filled; and
supersampling a region, where an area is rendered large, downsampled
and placed.
draw_canvas composites through the same straight-alpha src-over every
primitive uses (Color.blend_over), so a translucent source blends as a
translucent shape would and a transparent source pixel leaves the
destination untouched.
Drawing a canvas under a matrix
The overloads taking a Matrix2D draw the source scaled, rotated,
skewed or cropped – what cairo_set_source_surface under the CTM and
the HTML5 canvas’s drawImage do. Each destination pixel in the mapped
source’s bounding box is inverse-mapped into the source and sampled
there, Filter.NEAREST taking the pixel the point lands in and
Filter.BILINEAR mixing the four around it.
These overloads work in texel coordinates: source pixel (i, j) covers
the unit square from (i, j) to (i + 1, j + 1), so its center is at
(i + 0.5, j + 0.5) and a w x h source occupies [0, w] x [0, h]. That
is the convention Cairo and the HTML5 canvas use for an image, and the
one that makes Matrix2D.scaling(2.0, 2.0) land each source pixel on
exactly four destination pixels. It differs from the pixel-center
convention the shape rasterizers use (see CONTRIBUTING.md), and the two
agree wherever it matters here: under a translation by whole pixels
both put source pixel (i, j) at destination pixel (i + tx, j + ty), and
that call takes the blit path above.
Structs
Filter: How a transformeddraw_canvasreads the source between its pixels:NEARESTtakes the one the sample point lands in, giving hard pixel edges and no color the source did not already hold, andBILINEARmixes the four around it, giving smooth edges and intermediate colors.