raster library

CPU sparse-strip rasterization core (vello_hybrid-style): adaptive path flattening, stroke-to-contour expansion, and 4-px strip generation with a column-major RGBA8888 alpha atlas.

Pure Dart - runs on the VM, on the web, and in worker isolates. Deliberately NOT exported from the main pdf_graphics barrel: this is the substrate for dart_pdf_editor's strip shader device (and future worker-isolate strip generation), not part of the stable device API.

Classes

CachedGlyphStrips

One glyph's emitted strips in relocatable form, packed into a single allocation: [xy... | widthFlags... | alphaOffset... | alphaTexels...] with stripCount entries per strip section. xy is glyph-local (x | y<<16, y row-aligned), alphaOffset indexes the texel section, color is omitted (the replay overrides it). Immutable once built.

CachedShapeStrips

One shape's emitted strips in relocatable form (same packed layout as CachedGlyphStrips) plus the full content record the entry was keyed on - the map key is a 32-bit content hash, so every hit re-verifies the content before replaying (a collision falls back to direct raster, never to the wrong pixels).

DoubleBuilder

Growable Float64List: unboxed accumulation for geometry in device pixels.

FlatBounds

Axis-aligned bounds of subpaths, or null when empty.

FlatSubpath

One flattened subpath: [x0,y0, x1,y1, ...]. points is Float64List-backed (unboxed indexing).

FlattenedOutline

A glyph outline flattened once in em space (y-up, origin on the baseline) and cached per outline identity.

FloatBuilder

Growable Float32List: vertex/segment data in its final upload layout, emplaced without a conversion copy.

GlyphBands

Per-glyph horizontal band lists over a quadratic curve set.

GlyphCurveTexture

A glyph's curves + band tables packed for GPU consumption (layout in the library header). pixels is rgba8888 at width x height with zero padding; band geometry rides as plain fields for uniforms.

GlyphStripCache

LRU cache of rasterized glyph strips, replayed by StripGenerator.fillOutline.

QuadCurve

One quadratic Bezier segment in em space (y-up, origin on the baseline): p0 = (x0,y0), control (cx,cy), p1 = (x1,y1).

ShapeStripCache

Content-keyed cache of rasterized stroke/fill strips, replayed by StripGenerator.fillPath and StripGenerator.strokePath.

SlugBatchBuilder

Accumulates one painter-order Slug window without any dart:ui objects.

SlugBatchData

One painter-order Slug batch in worker-transferable form.

SlugChunkData

One drawVertices-sized slice of a Slug batch.

SlugGlyphData

Per-outline relocatable curve stream, memoized by outline identity.

StripBatchData

A flush batch in portable form: everything needed to draw its strips with one shader paint - chunks draw calls sharing one alpha atlas - tagged with the flushOrdinal of the flush point that emitted it.

StripBinningDevice

PdfDevice base that bins solid fills, strokes, and embedded-outline text into sparse strips (StripGenerator) and routes everything else - and every flush-point decision - through abstract hooks.

StripBuffer

The strip list under construction. Typed arrays grow geometrically and are reused across pages (reset keeps capacity).

StripChunkData

One drawVertices-sized slice of a StripBatchData: raw vertex arrays for up to stripMaxQuadsPerDraw strip quads.

StripGenerator

Fine-rasterizes fills, strokes, and glyph outlines into a StripBuffer.

StripPlan

The strip batches of one full binning walk, tagged with the geometry they were binned for. Only valid for a device with the exact same pageToDevice matrix, viewport, and tolerance; the consuming device verifies totalFlushPoints and full batch consumption at finish and falls back to local binning on any mismatch.

StripPlanBinner

Headless subclass of the binning core: collects the StripBatchData emitted at each flush point (delegated ops are no-ops) into a StripPlan. Feed it the page's command list with bin - which honors a PdfCancellationToken cooperatively - then take finish's plan.

StripReplayProfile

Cheap, geometry-free estimate of how a command transcript fragments when replayed through the sparse-strip device.

StrokeContours

Closed polygon contours accumulated as one flat point list plus ring boundaries; reused across strokes (clear + refill, no reallocation).

Constants

glyphFlattenTolerance → const double

Flattening tolerance for cached em-space glyph outlines, in em units.

slugAtlasWidth → const int

Curve atlas width in texels.

slugMaxQuadsPerDraw → const int

Maximum glyph quads in one drawVertices call (Uint16 indices).

stripAtlasWidth → const int

Alpha atlas width in texels (4 bytes each -> 4 KB rows).

stripFlagEvenOdd → const int

widthFlags bit: the fill that produced this strip used the even-odd rule (informational - coverage is already resolved CPU-side).

stripFlagSolid → const int

widthFlags bit: strip is fully covered - no alpha bytes, alphaOffset is stripSolidSentinel.

stripFlattenTolerance → const double

Curve-flattening tolerance (device px) for strip-routed paths. The raster core's 0.25 default (the GPU experiment's) leaves curve edges up to 0.25 px off the true curve - against Skia's much finer flattening that showed up as 50/255 coverage diffs on glyph-sized cubics. 0.02 px keeps curve-edge parity within a few counts for ~3.5x the segment count on curves (Wang's n grows with 1/sqrt(tolerance)); lines are unaffected.

stripMaxAlphaColumnsPerDraw → const int

Maximum alpha-texel span (u texcoord range) of one draw's strips.

stripMaxQuadsPerDraw → const int

ui.Vertices indices are Uint16, so one draw holds at most 65535 / 4 quads; batches chunk at this many strips per draw.

stripSolidSentinel → const int

alphaOffset value for solid strips.

Properties

decodeStripPlanMicros ↔ int

Telemetry: microseconds spent in decodeStripPlan (accumulated) - this runs on the consuming (UI) isolate, so it counts toward the residual UI-thread cost of a worker-binned settle.

getter/setter pair

Functions

buildBands(List<QuadCurve> curves, {int bandCount = 8, int maxCurvesPerBand = GlyphBands.maxCurvesPerBandDefault}) → GlyphBands

Builds GlyphBands for curves. Empty input yields zero bands.

dashSubpaths(List<FlatSubpath> subpaths, List<double> pattern, double phase) → List<FlatSubpath>

Re-cuts subpaths into dash segments (§8.4.3.6). pattern and phase are already in device pixels. Zero-length "on" dashes survive as single-point subpaths so round caps still paint dots.

decodeStripPlan(Uint8List bytes) → StripPlan

Decodes a buffer produced by encodeStripPlan. Throws on a version or structure mismatch (producer and consumer ship together; a mismatch is a programming error, and callers treat any throw as "no plan").

emToFixed(double v) → int

Fixed-point encode: em coordinate -> biased u16 (see library header).

encodeGlyphStream(List<QuadCurve> curves, GlyphBands bands) → Uint8List

The raw texel stream of one glyph (4 bytes per texel, layout in the library header), relocatable: all internal offsets are relative to the stream start, so streams concatenate into a per-flush atlas unchanged. Throws ArgumentError past u16 addressability - callers fall back to outline strips.

encodeGlyphTexels(List<QuadCurve> curves, GlyphBands bands, {int width = 256}) → GlyphCurveTexture

Packs curves + bands into texels (see the library header for the layout). Throws ArgumentError when the stream exceeds u16 addressability (65535 texels) - callers fall back to outline strips.

encodeStripPlan(StripPlan plan) → Uint8List

Serializes plan into one compact buffer (see the layout above).

fixedToEm(int u16) → double

Fixed-point decode.

flattenPath(PdfPath path, PdfMatrix transform, {double tolerance = 0.25}) → List<FlatSubpath>

Flattens path through transform (page space -> device pixels) into polylines. Cubics subdivide adaptively to stay within tolerance device pixels of the true curve (Wang's bound on the second differences).

glyphCoverageAA(List<QuadCurve> curves, GlyphBands bands, double x, double y, double pxPerEmX, double pxPerEmY) → double

Anti-aliased coverage at em-space (x, y), the Slug-style dual-ray evaluation the B3 shader mirrors step for step (see the library header for the formula). pxPerEmX/pxPerEmY are the glyph's device-pixels-per-em along each axis - they set the width of the AA ramp (one device pixel).

glyphWindingAt(List<QuadCurve> curves, GlyphBands bands, double x, double y) → int

Winding number of the horizontal ray x' > x at em-space point (x, y), evaluated exactly the way the B3 shader will: pick the band for y, walk its (max-x descending) curve list with the early-out, and accumulate signed ray crossings from the quadratic roots of Y(t) = y, t in [0, 1).

outlineToQuads(PdfPath outline, {double tolerance = 1e-3}) → List<QuadCurve>

Converts a glyph outline (em space; lines and cubics) into quadratic curves within tolerance em of the original geometry.

premulRgba8(PdfColor color, double alpha) → int

Packs color at alpha into premultiplied RGBA8 (r | g<<8 | b<<16 | a<<24 - RGBA8888 memory byte order on little-endian targets).

stripArgbColor(PdfColor color, double alpha) → int

Straight (non-premultiplied) ARGB for strip vertex colors; the engine premultiplies vertex colors before BlendMode.modulate applies coverage.

strokeToContours(List<FlatSubpath> subpaths, {required double width, required int cap, required int join, required double miterLimit, required StrokeContours out}) → void

Expands stroked subpaths (already flattened, already dashed, device pixels) into closed contours appended to out. See the library comment for parameter semantics.

Typedefs

GlyphStripKey = (FlattenedOutline, int, int, int, int, int, int)

Cache key: outline identity + quantized transform (2x2 in 1/64 steps, x offset in 1/4 px, y offset in 1/4 px within the 4-px strip row).

Exceptions / Errors

StripPlanMismatchError

Thrown when a StripPlan does not match the device consuming it (stale geometry, or a flush-ordinal/batch-count desync). Callers catch it, discard the picture, and re-run with local binning.