tiny-skia

CPU raster rendering for Kit using tiny-skia

This package provides the deterministic software-rendering path that kit-tea

needs while kit-wgpu handles the primary GPU path. It exposes tiny-skia's full

drawing model plus CPU text rendering that tiny-skia itself does not provide.

API

The package is organised into three modules, all re-exported from

src/main.kit:

• `Pixmap` (src/pixmap.kit) — pixmap lifecycle, dimensions,

raw pixel-buffer access, pixel reads, and the original high-level helpers

(solid/clipped fills, rounded and per-corner rounded rectangles, vertical and

horizontal gradients, stroked rounded rectangles, RGBA image blitting), plus

TrueType/OpenType font loading, rustybuzz shaping, fontdue rasterization,

coverage probes, font metrics, measurement, and whitespace-preserving wrapping.

• `Render` (src/render.kit) — the full tiny-skia object

model:

- PathBuilder/Path — move/line/quad/cubic, close, push rect/oval/circle,

from-rect/from-circle/from-oval, and path transforms.

- Paint — solid colour; linear, radial, and sweep gradients with arbitrary

multi-stop colours and Pad/Reflect/Repeat spread; pixmap patterns with

Nearest/Bilinear/Bicubic filtering; all 29 blend modes; anti-alias and

colour-space (Linear/Gamma2/SimpleSRGB/FullSRGBGamma) control.

- Stroke — width, miter limit, line caps, line joins, and dashes.

- Mask — anti-aliased path-based clip masks (Winding/EvenOdd).

- fill-path, stroke-path, fill-rect-paint, draw-pixmap, and PNG

save-png/load-png.

• `Transform` (src/transform.kit) — affine transforms

(identity, from-row, translate/scale/rotate/skew, pre/post composition) passed

to every drawing call, matching tiny-skia's row-major matrix.

Bidirectional paragraph layout, hyphenation, glyph caching, and automatic font

fallback selection remain higher-level work on the text side.

Examples

examples/ re-implements each upstream tiny-skia example in Kit;

each renders to examples/output/<name>.png:

kit run examples/fill.kit
kit run examples/stroke.kit
kit run examples/hairline.kit
kit run examples/linear_gradient.kit
kit run examples/pattern.kit
kit run examples/mask.kit
kit run examples/gamma.kit
kit run examples/image_on_image.kit
kit run examples/large_image.kit

Native Build

The package builds a Rust cdylib with Cargo. Kit invokes

tools/build-native.sh through the package manifest when the native library is

needed.

kit task test

Exported Functions & Types

Transform

2D affine transforms mirroring tiny-skia's row-major Transform.

A transform is the 2x3 matrix (sx, ky, kx, sy, tx, ty) that maps a point (x, y) to (sx*x + kx*y + tx, ky*x + sy*y + ty). The field order matches tiny-skia's Transform::from_row, so a Transform value can be passed straight through to the native drawing calls.

A 2x3 affine transform matrix in tiny-skia row order.

identity

The identity transform (no scaling, rotation, or translation).

Transform

from-row

Builds a transform directly from its six row-major components.

Float -> Float -> Float -> Float -> Float -> Float -> Transform

from-translate

Builds a translation transform.

Float -> Float -> Transform

from-scale

Builds a scaling transform.

Float -> Float -> Transform

from-skew

Builds a skewing transform.

Float -> Float -> Transform

from-rotate

Builds a rotation transform (angle in degrees, clockwise).

Float -> Transform

pre-concat

Composes two transforms: pre-concat a b applies b first, then a.

Transform -> Transform -> Transform

post-concat

Composes two transforms: post-concat a b applies a first, then b.

Transform -> Transform -> Transform

pre-translate

Applies a translation before the existing transform.

Transform -> Float -> Float -> Transform

post-translate

Applies a translation after the existing transform.

Transform -> Float -> Float -> Transform

pre-scale

Applies a scale before the existing transform.

Transform -> Float -> Float -> Transform

post-scale

Applies a scale after the existing transform.

Transform -> Float -> Float -> Transform

pre-rotate

Applies a rotation (degrees) before the existing transform.

Transform -> Float -> Transform

post-rotate

Applies a rotation (degrees) after the existing transform.

Transform -> Float -> Transform

pre-skew

Applies a skew before the existing transform.

Transform -> Float -> Float -> Transform

post-skew

Applies a skew after the existing transform.

Transform -> Float -> Float -> Transform

Pixmap

Opaque handle to a tiny-skia pixmap (an RGBA raster surface).

Font

Opaque handle to a loaded font face.

Buffer

Pointer to a raw RGBA byte buffer.

TinySkiaError

Error type for raster rendering failures.

raster-error

Builds a TinySkiaError carrying the most recent native error message.

Takes an ignored argument so callers in other modules invoke it explicitly (a bare value binding would capture the message once at module init).

a -> TinySkiaError

is-null?

Reports whether a native handle is null.

Kit's compiled backend cannot compare an opaque pointer to an integer literal, so handle null-checks route through this native helper instead of == 0.

Ptr -> Bool

create-pixmap

Creates a new pixmap with the given width and height in pixels.

PositiveInt -> PositiveInt -> Result Pixmap TinySkiaError

release

Destroys a pixmap and frees its memory.

Pixmap -> Unit

width

Returns the width of the pixmap in pixels.

Pixmap -> Int

height

Returns the height of the pixmap in pixels.

Pixmap -> Int

data-len

Returns the length in bytes of the pixmap's pixel buffer.

Pixmap -> Int

data

Returns a read-only pointer to the pixmap's pixel buffer.

Pixmap -> Buffer

data-mut

Returns a mutable pointer to the pixmap's pixel buffer.

Pixmap -> Buffer

clear

Fills the entire pixmap with a solid RGBA color.

Pixmap -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-rect

Fills a rectangle with a solid RGBA color.

Pixmap -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-rounded-rect

Fills a rounded rectangle with a uniform corner radius.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-corner-rounded-rect

Fills a rounded rectangle with per-corner radii.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-vertical-gradient-rounded-rect

Fills a rounded rectangle with a vertical (top-to-bottom) color gradient.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-vertical-gradient-corner-rounded-rect

Fills a per-corner rounded rectangle with a vertical (top-to-bottom) gradient.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-horizontal-gradient-rounded-rect

Fills a rounded rectangle with a horizontal (left-to-right) color gradient.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

fill-horizontal-gradient-corner-rounded-rect

Fills a per-corner rounded rectangle with a horizontal (left-to-right) gradient.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

stroke-rounded-rect

Strokes the outline of a rounded rectangle with a uniform corner radius.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

stroke-corner-rounded-rect

Strokes the outline of a rounded rectangle with per-corner radii.

Pixmap -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

set-clip-rect

Restricts subsequent drawing to the given rectangular clip region.

Pixmap -> Int -> Int -> PositiveInt -> PositiveInt -> Result Unit TinySkiaError

clear-clip

Removes any active clip region.

Pixmap -> Unit

get-pixel-r

Returns the red channel value of the pixel at (x, y).

Pixmap -> NonNegativeInt -> NonNegativeInt -> Int

get-pixel-g

Returns the green channel value of the pixel at (x, y).

Pixmap -> NonNegativeInt -> NonNegativeInt -> Int

get-pixel-b

Returns the blue channel value of the pixel at (x, y).

Pixmap -> NonNegativeInt -> NonNegativeInt -> Int

get-pixel-a

Returns the alpha channel value of the pixel at (x, y).

Pixmap -> NonNegativeInt -> NonNegativeInt -> Int

load-font

Loads a font face from the given file path.

NonEmptyString -> Result Font TinySkiaError

release-font

Destroys a loaded font and frees its memory.

Font -> Unit

measure-text

Measures the rendered width of a single line of text.

Font -> String -> Float -> Float -> Result Float TinySkiaError

wrapped-line-count

Returns the number of lines the text wraps to within max-width.

Font -> String -> Float -> Float -> Float -> Result Int TinySkiaError

measure-wrapped-text-height

Measures the total height of text wrapped within max-width.

Font -> String -> Float -> Float -> Float -> Float -> Result Float TinySkiaError

shape-glyph-count

Returns the number of shaped glyphs the text produces.

Font -> String -> Float -> Result Int TinySkiaError

font-has-codepoint?

Reports whether the font contains a glyph for the given codepoint.

Font -> Int -> Result Bool TinySkiaError

font-covers-text?

Reports whether the font can render every character in the text.

Font -> String -> Result Bool TinySkiaError

font-ascent

Returns the font's ascent (baseline-to-top distance) at the given size.

Font -> Float -> Result Float TinySkiaError

font-descent

Returns the font's descent (baseline-to-bottom distance) at the given size.

Font -> Float -> Result Float TinySkiaError

font-line-gap

Returns the font's recommended line gap at the given size.

Font -> Float -> Result Float TinySkiaError

font-line-height

Returns the font's total line height at the given size.

Font -> Float -> Result Float TinySkiaError

draw-rgba

Composites an RGBA image buffer onto the pixmap.

Pixmap -> Buffer -> PositiveInt -> PositiveInt -> PositiveInt -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Float -> Result Unit TinySkiaError

draw-text

Draws a single line of text at the given baseline position.

Pixmap -> Font -> String -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

draw-text-wrapped

Draws text wrapped within max-width, advancing by line-height per line.

Pixmap -> Font -> String -> Float -> Float -> Float -> Float -> Float -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

Paint

Opaque handle to a configurable paint (shader + blend + anti-alias).

Path

Opaque handle to a finished, immutable path.

PathBuilder

Opaque handle to a mutable path builder.

Stroke

Opaque handle to a stroke style (width, caps, joins, dash).

Mask

Opaque handle to an 8-bit clip mask.

no-mask

Sentinel passed to drawing operations to indicate "no clip mask".

Mask

FillRule

Path fill rule.

SpreadMode

Gradient/pattern tiling behaviour outside the defined range.

FilterQuality

Pixmap sampling quality for patterns and image blits.

LineCap

How stroked subpaths are capped at their ends.

LineJoin

How stroked subpaths are joined at corners.

ColorSpace

Gamma handling used when blending colours.

BlendMode

Porter-Duff and separable blend modes (tiny-skia order).

paint-new

Creates a new paint, defaulting to opaque black with anti-aliasing on.

Unit -> Paint

paint-destroy

Destroys a paint and frees its memory.

Paint -> Unit

paint-set-color

Sets the paint to a solid RGBA colour.

Paint -> Int -> Int -> Int -> Int -> Unit

paint-set-anti-alias

Enables or disables anti-aliasing.

Paint -> Bool -> Unit

paint-set-force-hq-pipeline

Toggles the forced high-quality (f32) pipeline.

Paint -> Bool -> Unit

paint-set-blend-mode

Sets the paint's blend mode.

Paint -> BlendMode -> Unit

paint-set-colorspace

Sets the paint's blending colour space.

Paint -> ColorSpace -> Unit

paint-set-shader-linear

Sets a linear-gradient shader (add stops with [[paint-add-gradient-stop]]).

Paint -> Float -> Float -> Float -> Float -> SpreadMode -> Transform -> Unit

paint-set-shader-radial

Sets a radial (two-point conical) gradient shader.

Paint -> Float -> Float -> Float -> Float -> Float -> Float -> SpreadMode -> Transform -> Unit

paint-set-shader-sweep

Sets a sweep (angular) gradient shader. Angles are in degrees.

Paint -> Float -> Float -> Float -> Float -> SpreadMode -> Transform -> Unit

paint-set-shader-pattern

Sets a pattern shader that tiles a source pixmap.

Paint -> Pixmap -> SpreadMode -> FilterQuality -> Float -> Transform -> Unit

paint-add-gradient-stop

Appends a colour stop to the paint's current gradient shader.

Paint -> Float -> Int -> Int -> Int -> Int -> Result Unit TinySkiaError

path-builder-new

Creates a new, empty path builder.

Unit -> PathBuilder

path-builder-destroy

Destroys a path builder and frees its memory.

PathBuilder -> Unit

move-to

Begins a new contour at (x, y).

PathBuilder -> Float -> Float -> Unit

line-to

Adds a line to (x, y).

PathBuilder -> Float -> Float -> Unit

quad-to

Adds a quadratic Bézier curve through control point (x1, y1) to (x, y).

PathBuilder -> Float -> Float -> Float -> Float -> Unit

cubic-to

Adds a cubic Bézier curve through (x1, y1) and (x2, y2) to (x, y).

PathBuilder -> Float -> Float -> Float -> Float -> Float -> Float -> Unit

close

Closes the current contour.

PathBuilder -> Unit

push-rect

Appends a rectangle contour.

PathBuilder -> Float -> Float -> Float -> Float -> Unit

push-oval

Appends an oval contour inscribed in the rectangle.

PathBuilder -> Float -> Float -> Float -> Float -> Unit

push-circle

Appends a circle contour.

PathBuilder -> Float -> Float -> Float -> Unit

path-builder-finish

Consumes the builder's contents and produces a finished path.

PathBuilder -> Result Path TinySkiaError

path-from-rect

Builds a rectangle path.

Float -> Float -> Float -> Float -> Result Path TinySkiaError

path-from-circle

Builds a circle path.

Float -> Float -> Float -> Result Path TinySkiaError

path-from-oval

Builds an oval path inscribed in the rectangle.

Float -> Float -> Float -> Float -> Result Path TinySkiaError

path-transform

Returns a new path with the transform applied to the given path.

Path -> Transform -> Result Path TinySkiaError

path-destroy

Destroys a path and frees its memory.

Path -> Unit

stroke-new

Creates a new stroke style (default width 1.0, butt caps, miter joins).

Unit -> Stroke

stroke-destroy

Destroys a stroke style and frees its memory.

Stroke -> Unit

stroke-set-width

Sets the stroke width.

Stroke -> Float -> Unit

stroke-set-miter-limit

Sets the miter limit.

Stroke -> Float -> Unit

stroke-set-line-cap

Sets the line cap style.

Stroke -> LineCap -> Unit

stroke-set-line-join

Sets the line join style.

Stroke -> LineJoin -> Unit

stroke-dash-clear

Clears the dash pattern.

Stroke -> Unit

stroke-dash-push

Appends one on/off length to the dash pattern.

Stroke -> Float -> Unit

stroke-set-dash-phase

Sets the dash phase (offset into the pattern).

Stroke -> Float -> Unit

mask-new

Allocates a new, empty (all-zero) clip mask.

PositiveInt -> PositiveInt -> Result Mask TinySkiaError

mask-destroy

Destroys a clip mask and frees its memory.

Mask -> Unit

mask-fill-path

Rasterizes a path into the mask using the given fill rule and transform.

Mask -> Path -> FillRule -> Bool -> Transform -> Result Unit TinySkiaError

fill-path

Fills a path on the pixmap with the paint, fill rule, transform, and mask.

Pixmap -> Path -> Paint -> FillRule -> Transform -> Mask -> Result Unit TinySkiaError

stroke-path

Strokes a path on the pixmap with the paint, stroke style, transform, and mask.

Pixmap -> Path -> Paint -> Stroke -> Transform -> Mask -> Result Unit TinySkiaError

fill-rect-paint

Fills an axis-aligned rectangle with a paint under a transform and mask.

Pixmap -> Float -> Float -> Float -> Float -> Paint -> Transform -> Mask -> Result Unit TinySkiaError

draw-pixmap

Composites a source pixmap onto the pixmap at (x, y) under a transform.

Pixmap -> Int -> Int -> Pixmap -> FilterQuality -> Float -> BlendMode -> Transform -> Mask -> Result Unit TinySkiaError

save-png

Encodes the pixmap as a PNG and writes it to the given file path.

Pixmap -> NonEmptyString -> Result Unit TinySkiaError

load-png

Decodes a PNG file at the given path into a new pixmap.

NonEmptyString -> Result Pixmap TinySkiaError