zinc:lottie

Lottie (Bodymovin JSON) animations rendered natively, without a JavaScript engine: the file is parsed once in C++ into a compact scene, and each frame is evaluated, flattened and drawn through the shared software rasterizer (gfx.path polygons, anti-aliased). Plugin: plugins/lottie/ (module zinc:lottie).

import { Lottie } from 'zinc:lottie';
// UI node (zinc:ui canvas), played on the UI engine clock
<Lottie src="spinner.json" loop autoplay className="w-24 h-24" />

import * as gfx from 'zinc:gfx';
import * as lottie from 'zinc:lottie';

const p = new lottie.Player(lottie.load('spinner.json'));  // asset name (embedded), else a file path
p.loop = true; p.play();
gfx.onFrame((dt) => { p.update(dt); gfx.clear(0); p.draw(0, 0, 200, 200); });

• functions: load(name), parse(json) → handle (-1 on error), width, height, frames, fps, duration (s), layers, draw(a, frame, x, y, w, h) (frame 0 = first; the composition is fitted into the box, aspect ratio kept, centered and clipped), free, drawMs() (time spent in Player.draw since the last call).
• Player(anim): play, pause, stop, seek(frame), segment(from, to), update(dt), draw(x, y, w, h), shown(); fields frame, speed (negative plays backwards), loop, playing, alpha, subframe (default false: whole frames at the file’s rate, see performance), from/to. cache(w, h, bg, maxBytes) switches to render-to-image mode (below).
• <Lottie> props: src, loop, autoplay, speed, class, subframe, cacheBg (render-to-image mode on that background colour), player (callback receiving the Player, for play/pause from the app).

Examples: examples/ui/lottie-gallery (12 animations in a grid with a fps readout, click a card to pause it), src/view.ts there (one file, full window: LOTTIE=file.json [LOTTIE_FRAME=n]), src/bench.ts there (numbers below).

Supported features

Verified on macOS by screenshots of the gallery at 0.5 s, 1.5 s and of single files, compared with lottie-web 5.12 (SVG renderer) in Chrome at the same frames: all 12 gallery files match in shape, position, colour and timing (differences: flat gradient on the ellipse of shapes.json, hairlines slightly fainter than Chrome’s retina rendering). Found on the way: lottie-web evaluates layer properties in composition time (a layer’s st and sr only shift/stretch a precomp’s inner time); Zinc does the same.

How it is fast

• Parse once: JSON → a temporary DOM → flat arrays (layers, shape items, transforms) with every animatable property either a static value or a keyframe table in one float pool. The DOM is freed after loading.
• Evaluate only what is visible: layers outside their in/out range, hidden layers, matte sources and nulls are skipped before any evaluation.
• Per-layer command cache: each top-level layer keeps the commands it emitted with their key (frame, box). A layer with no keyframes anywhere in its content, transform or parent chain is evaluated and flattened once; an animated layer only when its frame or the box changes. Redrawing the same frame (paused player, a 30 fps file on a 60 Hz loop with subframe = false) is a replay of stored commands (a few µs); the frame diff then finds nothing changed and the rasterizer does no work — an idle Lottie costs nothing to rasterize.
• Device-space flattening: beziers are transformed first, then flattened with a 0.25 px tolerance, so a small icon gets few segments and a full-screen one stays smooth.
• Cheap strokes: a stroke is one outline per polyline (left side, cap, right side, cap), 2 edges per vertex, with proper miter/round/bevel joins; sharp inner turns fall back to the rasterizer’s quad + disc stroker.
• Rasterizer-friendly output: axis-aligned rects and solid layers become rounded-rect commands (row fills), and large paths with many edges are cut into 16-row bands (exact, no seams) so the scanline filler only walks the edges of each band.
• Render-to-image mode (Player.cache(w, h, bg, maxBytes), <Lottie cacheBg={...}>): for small looping icons, each frame is rasterized once into a runtime image atlas (w × h·frames, opaque on bg) and then drawn as a 1:1 row copy. Memory: w·h·4 bytes per frame (a 48 px, 54-frame icon: 500 KiB); refused above maxBytes.

Performance (macOS, M1 Pro, release build, zinc run examples/ui/lottie-gallery/src/bench.ts)

Every frame of each file rendered off screen at 256×256 (gfx.beginImage), ms per frame: vector = evaluation + flattening + command emission, raster = rasterization, replay = redrawing an unchanged frame.

Evaluation is in the µs range; the rasterizer dominates and scales with the covered area (big fills and long strokes), not with the number of layers. Measured with the machine under load (other builds running); numbers are CPU time on one core.

Whole programs (release, ZINC_FIXED_DT=1/60, 600 frames, /usr/bin/time, user CPU per frame):

Support matrix

Command budgets: the frame holds at most ZRT_MAX_DRAW_CMDS commands and ZRT_POINT_POOL floats of polygon points; the plugin raises the point pool to 256 Ki floats on hosts (128 Ki on rpi1/wasm) and lowers it to 4 Ki on esp32 (with 256 commands there), so only small animations fit on esp32. Extra commands are dropped, not crashed on.

Follow-ups

• Dashes, even-odd fill, mattes and non-rectangular masks need rasterizer support (a coverage mask or a per-command fill rule); gradients on arbitrary paths need a gradient paint mode for polygons.
• The scanline filler walks every edge of a command for each sub-scanline; an active-edge table in raster.cpp would help big, complex paths more than the banding done here.
• Per-group caching inside animated layers (static groups are re-flattened when a sibling animates).

Edit this page on GitHub ↗