Skip to content

Code-first video & image, rendered natively on WebGPU.

fix(engine): first-key holds, dashed strokes, compound fills, keyed volume, instanced strokes

okanasl1835ddf9d86e
diff --git a/.changeset/arrow-head-boil.md b/.changeset/arrow-head-boil.md
new file mode 100644
index 00000000..d50e43f1
--- /dev/null
+++ b/.changeset/arrow-head-boil.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+A hand-drawn arrow's head no longer spins. `Annotate`'s arrow aimed its head from the tip to the last point of the wobbled shaft, a segment a few pixels long that the boil moved on every re-pose, so the head swung round (fully, on short arrows), and the wobbled shaft stopped short of it. The head now follows the clean curve's direction a head's length back from the tip, the same in every pose, and the hand lets go of the shaft toward the tip so the two always meet.
diff --git a/.changeset/compound-path-fills.md b/.changeset/compound-path-fills.md
new file mode 100644
index 00000000..219edd0a
--- /dev/null
+++ b/.changeset/compound-path-fills.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+Paths with several subpaths fill as drawn. A `path` shape's fill joined every subpath into one polygon, so a map's states and islands, a ring or a letter with a counter came out as wedges bridging them. Each subpath is now a contour; contours nest, holes follow SVG's nonzero rule, and each filled contour is triangulated with its holes (earcut). Fills are cached by path data, so a large path is triangulated once rather than every frame. Animating `d` (path morphs) also passes schema validation now: its keyframes are path data, not numbers, which `Annotate`'s hand-drawn boil relies on.
diff --git a/.changeset/dashed-strokes.md b/.changeset/dashed-strokes.md
new file mode 100644
index 00000000..acbfbe00
--- /dev/null
+++ b/.changeset/dashed-strokes.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+`strokeDashArray` renders. It is written as SVG writes it (`"12 8"`, `"4,8"`), but the string reached the path pipeline as if it were a list of numbers, the dash arithmetic came out NaN, and the whole stroke was dropped: dashed lines, circles and outlines drew nothing. It is now read by SVG's rules (an odd list repeats; a negative, unreadable or zero-length pattern draws solid).
diff --git a/.changeset/instanced-strokes.md b/.changeset/instanced-strokes.md
new file mode 100644
index 00000000..60c240c3
--- /dev/null
+++ b/.changeset/instanced-strokes.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+Strokes draw in one call per path. The path pipeline drew every straight piece of a stroke (and of the hairline that antialiases a solid fill) as its own draw, with two buffer uploads each, so a curve, a dashed line or a map's coastline cost thousands of native calls a frame. Each segment is now an instance of one draw: the path's transform, color, width and cap are uploaded once, its segments in one buffer, and the vertex shader builds each segment's quad. Output is unchanged; a scene of map coastlines and a hundred filled circles renders about twice as fast.
diff --git a/.changeset/keyed-volume.md b/.changeset/keyed-volume.md
new file mode 100644
index 00000000..67ee797b
--- /dev/null
+++ b/.changeset/keyed-volume.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+A layer keyed up from `volume: 0`, or keyed out of `muted: true`, plays. The mix baked a layer's resting volume and mute into its sources (skipping a source at 0 altogether) and the layer's keys only rescaled what was left, so a fade in from a resting volume of 0 stayed silent for good. Props a layer keys are now applied by its keys alone; resting values it does not key are applied as before. A ducked music bed written `Layer.audio(music, { volume: 0 }).animate(LayerAnimation.keys("volume", …))` is heard.
diff --git a/.changeset/keyframe-first-value.md b/.changeset/keyframe-first-value.md
new file mode 100644
index 00000000..d8551cd4
--- /dev/null
+++ b/.changeset/keyframe-first-value.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+A keyframe track holds its first value until it is reached. Baked tracks showed the layer's own value before their first key, so `keys("opacity", [[40, 0], [48, 1]])` drew the layer fully opaque for 40 frames and then snapped it out to fade in, and `keys("y", [[30, 440], [40, 400]])` sat at 400 before jumping to 440. Draw-time tracks (signals, stepped layers, path morphs) already held the first key, so the same track now plays the same either way. Discrete props (`hidden`, `muted`) still step from the layer's own value, as sets do.
diff --git a/nodes/node-compositor/src/renderers/audio-processor.ts b/nodes/node-compositor/src/renderers/audio-processor.ts
index fe8ed349..2d01617c 100644
--- a/nodes/node-compositor/src/renderers/audio-processor.ts
+++ b/nodes/node-compositor/src/renderers/audio-processor.ts
@@ -1,3 +1,4 @@
+import { keyedGain } from "@framefields/compositions";
import type { LayerAnimation } from "@framefields/compositions/program";
import type { VirtualMediaData } from "@framefields/core";
import {
@@ -51,18 +52,9 @@ export const compositorLayerAudioProcessor: AudioProcessor = async (
const animation = op.animation;
const fps = ctx?.fps ?? 24;
- // Check if there are active volume or muted animation tracks with keyframes
- const tracks = animation?.tracks || [];
- const hasVolumeKeys = tracks.some(
- (t) => t.prop === "volume" && t.keyframes && t.keyframes.length > 0,
- );
- const hasMutedKeys = tracks.some(
- (t) => t.prop === "muted" && t.keyframes && t.keyframes.length > 0,
- );
-
- if (!hasVolumeKeys && !hasMutedKeys) {
- // If no animated volume/muted tracks exist, the static volume and mute state
- // have already been applied by the child clip or audio extractor.
+ const keyed = keyedGain(op);
+ if (!keyed.volume && !keyed.muted) {
+ // Nothing keyed: the mix already applied the resting volume and mute.
return;
}
@@ -86,7 +78,9 @@ export const compositorLayerAudioProcessor: AudioProcessor = async (
let lastVol = stub.volume;
let lastMuted = stub.muted;
- const baseGain = muted ? 0 : volume;
+ // What the mix already applied: the resting values of the props this
+ // layer does not key (see `keyedGain`). The keyed ones are applied here.
+ const applied = (keyed.volume ? 1 : volume) * (!keyed.muted && muted ? 0 : 1);
for (let i = 0; i < numSamples; i += subChunkSize) {
const nextI = Math.min(numSamples, i + subChunkSize);
@@ -109,7 +103,7 @@ export const compositorLayerAudioProcessor: AudioProcessor = async (
const currentMuted = j - i < (nextI - i) / 2 ? lastMuted : nextMuted;
const finalGain = currentMuted ? 0 : currentVol;
- const relativeGain = baseGain === 0 ? 0 : finalGain / baseGain;
+ const relativeGain = applied === 0 ? 0 : finalGain / applied;
if (relativeGain !== 1) {
for (let c = 0; c < numChannels; c++) {
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 6d80292c..13f21780 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -58,6 +58,7 @@ import {
measureMaxCaptionHeight,
type PrimitiveGeometryOptions,
parseColor,
+ parseDashArray,
poseNodes,
type RenderContextValue,
Renderer3D,
@@ -5239,7 +5240,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const strokeColor =
target?.strokeColor ?? lop.strokeColor ?? lop.stroke ?? "#ffffff";
const strokeLineCap = lop.strokeLineCap ?? "round";
- const strokeDashArray = lop.strokeDashArray;
+ // The program writes dashes as SVG does ("16 12"); the path pipeline takes numbers.
+ const strokeDashArray = parseDashArray(lop.strokeDashArray);
const strokeDashOffset =
target?.strokeDashOffset ?? lop.strokeDashOffset ?? 0;
const trimStart = target?.trimStart ?? lop.trimStart ?? 0;
diff --git a/nodes/node-compositor/src/shared/compiler.test.ts b/nodes/node-compositor/src/shared/compiler.test.ts
index 5529cddf..2b3e155d 100644
--- a/nodes/node-compositor/src/shared/compiler.test.ts
+++ b/nodes/node-compositor/src/shared/compiler.test.ts
@@ -414,7 +414,7 @@ describe("Compositor GSAP Compiler", () => {
expect(stub.x).toBe(200);
});
- it("should hold the correct base/pre-seeded values at limits", () => {
+ it("should hold the first key before it, and after the last", () => {
const virtualMedia = {
operation: {
op: "Compositor",
@@ -458,9 +458,10 @@ describe("Compositor GSAP Compiler", () => {
const stub = targetsById["layer-1"];
expect(stub).toBeDefined();
- // Before first keyframe (at frame 6), should hold the layer base value 100
+ // Before the first keyframe (frame 6) the track holds that key's value,
+ // not the layer's resting x of 100
tl.seek(6 / 24);
- expect(stub.x).toBe(100);
+ expect(stub.x).toBe(200);
// At first keyframe frame 12
tl.seek(12 / 24);
@@ -479,6 +480,55 @@ describe("Compositor GSAP Compiler", () => {
expect(stub.x).toBe(300);
});
+ it("keeps a later entrance in its first pose; discrete props step from the layer's value", () => {
+ const layer = (
+ id: string,
+ props: Record<string, unknown>,
+ prop: string,
+ keyframes: Array<{ frame: number; value: number | boolean }>,
+ ) => ({
+ operation: {
+ op: "CompositorLayer",
+ id,
+ startFrame: 0,
+ durationFrames: 100,
+ ...props,
+ animation: {
+ tracks: [
+ {
+ id: `${id}-track`,
+ prop,
+ keyframes: keyframes.map((k, i) => ({ id: `${id}-${i}`, ...k })),
+ },
+ ],
+ },
+ },
+ });
+ const { tl, targetsById } = compileTimeline(
+ "render-entrance",
+ {
+ operation: { op: "Compositor", width: 1920, height: 1080 },
+ children: [
+ // Keys listed out of order: the earliest one is the pose held.
+ layer("fade", {}, "opacity", [
+ { frame: 33, value: 1 },
+ { frame: 30, value: 0 },
+ ]),
+ layer("reveal", { hidden: true }, "hidden", [
+ { frame: 30, value: false },
+ ]),
+ ],
+ } as never,
+ { fps: 30, durationSec: 4 },
+ );
+ tl.seek(10 / 30);
+ expect(targetsById.fade?.opacity).toBe(0);
+ expect(targetsById.reveal?.hidden).toBe(true);
+ tl.seek(40 / 30);
+ expect(targetsById.fade?.opacity).toBe(1);
+ expect(targetsById.reveal?.hidden).toBe(false);
+ });
+
it("should support spring easing function solver", () => {
const virtualMedia = {
operation: {
diff --git a/nodes/node-compositor/src/shared/compiler.ts b/nodes/node-compositor/src/shared/compiler.ts
index c3603e66..98031ec1 100644
--- a/nodes/node-compositor/src/shared/compiler.ts
+++ b/nodes/node-compositor/src/shared/compiler.ts
@@ -400,6 +400,9 @@ export function mappedEase(
return `${easeName}.${dir}${suffix}`;
}
+/** Props that switch rather than tween: each key is a set from its frame on. */
+const DISCRETE_PROPS: ReadonlySet<string> = new Set(["hidden", "muted"]);
+
function compileTrackToTimeline(
tl: gsap.core.Timeline,
stub: Record<string, any>,
@@ -503,7 +506,7 @@ function compileTrackToTimeline(
return { dropped, maxAuthoredFrame };
}
- const isDiscrete = prop === "hidden" || prop === "muted";
+ const isDiscrete = DISCRETE_PROPS.has(prop);
if (isDiscrete) {
for (const kf of validKeyframes) {
@@ -925,15 +928,19 @@ export function compileTimeline(
{ startFrame: lop.startFrame ?? 0, baseValues: stub, signals },
);
} else if (track.keyframes && track.keyframes.length > 0) {
- const kf0 = track.keyframes[0];
+ const keyframes: AnimationTrack["keyframes"] = track.keyframes;
+ const first = keyframes.reduce((a, b) => (b.frame < a.frame ? b : a));
const seeded = stub as Record<string, unknown>;
- if (kf0.frame === 0) {
- seeded[track.prop] = kf0.value;
+ if (!DISCRETE_PROPS.has(track.prop) || first.frame === 0) {
+ // Until its first key a track holds that key's value, as the
+ // program evaluator does for draw-time tracks: an entrance keyed
+ // at frame 40 waits in its first pose, it doesn't show the
+ // layer's resting value and then jump.
+ seeded[track.prop] = first.value;
} else if (seeded[track.prop] === undefined) {
- // GSAP only tweens props that exist on its target; props the stub
- // doesn't model (trimEnd, borderWidth, …) start from the node's own
- // value, else hold the first key until it's reached.
- seeded[track.prop] = lop[track.prop] ?? kf0.value;
+ // Discrete props step like sets: the node's own value until the
+ // first key. GSAP only tweens props its target has.
+ seeded[track.prop] = lop[track.prop] ?? first.value;
}
}
}
diff --git a/packages/components/src/core/draw.test.ts b/packages/components/src/core/draw.test.ts
index 557e677b..a0538155 100644
--- a/packages/components/src/core/draw.test.ts
+++ b/packages/components/src/core/draw.test.ts
@@ -55,6 +55,31 @@ describe("draw", () => {
expect(squigglePath([0, 0], [120, 0], { amplitude: 5 })).toMatch(/^M0 0/);
});
+ it("keeps a hand-drawn arrow's head pointing the same way in every boil pose", () => {
+ // Short arrows and the swoop are where the head used to spin.
+ for (const [to, curve] of [
+ [[60, 20], "arc"],
+ [[300, 120], "swoop"],
+ ] as const) {
+ const angles = [0, 1, 2, 3, 4, 5].map((v) => {
+ const { shaft, head } = arrowPaths(
+ [0, 0],
+ [to[0], to[1]],
+ { curve, wobble: 4, seed: 7 },
+ v,
+ );
+ // The shaft meets the tip, whatever the pose.
+ expect(shaft.endsWith(`L${to[0]} ${to[1]}`)).toBe(true);
+ const [x, y] = (head.match(/^M(-?[\d.]+) (-?[\d.]+)/) ?? [])
+ .slice(1)
+ .map(Number) as [number, number];
+ return Math.atan2(to[1] - y, to[0] - x);
+ });
+ const spread = Math.max(...angles) - Math.min(...angles);
+ expect(spread, curve).toBeLessThan(1e-6);
+ }
+ });
+
it("boils between poses with hold keys", () => {
const keys = boilKeys((v) => `pose-${v}`, {
start: 0,
diff --git a/packages/components/src/core/draw.ts b/packages/components/src/core/draw.ts
index cf154991..7ebe59b3 100644
--- a/packages/components/src/core/draw.ts
+++ b/packages/components/src/core/draw.ts
@@ -188,6 +188,27 @@ export interface ArrowGeometry {
head: string;
}
+const smoothstep = (t: number) => {
+ const k = Math.min(1, Math.max(0, t));
+ return k * k * (3 - 2 * k);
+};
+
+/** The point `distance` back along a polyline from its end (its start, if shorter). */
+function pointBack(points: readonly Vec2[], distance: number): Vec2 {
+ let left = distance;
+ for (let i = points.length - 1; i > 0; i--) {
+ const b = points[i] as Vec2;
+ const a = points[i - 1] as Vec2;
+ const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+ if (len >= left && len > 0) {
+ const k = left / len;
+ return [b[0] + (a[0] - b[0]) * k, b[1] + (a[1] - b[1]) * k];
+ }
+ left -= len;
+ }
+ return points[0] as Vec2;
+}
+
/** An arrow from `from` to `to` with a separate head path. */
export function arrowPaths(
from: Vec2,
@@ -229,9 +250,24 @@ export function arrowPaths(
to,
];
const points = bend === 0 ? [from, to] : catmullRom(controls, 12);
- const wobbled = wobblePoints(points, { wobble, seed }, variant);
- const tail = wobbled[wobbled.length - 2] ?? from;
- const angle = Math.atan2(to[1] - tail[1], to[0] - tail[0]);
+ // The hand wobbles the shaft but lets go of it toward the tip, so it
+ // always meets the head there.
+ const wobbled = wobblePoints(points, { wobble, seed }, variant).map(
+ (p, i): Vec2 => {
+ const t = points.length === 1 ? 0 : i / (points.length - 1);
+ const hold = t <= 0.75 ? 1 : 1 - smoothstep((t - 0.75) / 0.25);
+ const clean = points[i] as Vec2;
+ return [
+ clean[0] + (p[0] - clean[0]) * hold,
+ clean[1] + (p[1] - clean[1]) * hold,
+ ];
+ },
+ );
+ // The head follows the clean curve's direction about a head's length back
+ // from the tip, the same for every pose: from the last (short, wobbled)
+ // segment it swung round each time the boil re-posed the stroke.
+ const back = pointBack(points, headSize);
+ const angle = Math.atan2(to[1] - back[1], to[0] - back[0]);
const wing = (side: 1 | -1): Vec2 => [
to[0] - Math.cos(angle + side * 0.5) * headSize,
to[1] - Math.sin(angle + side * 0.5) * headSize,
diff --git a/packages/compositions/src/program/schema.test.ts b/packages/compositions/src/program/schema.test.ts
index fadfef74..d269ad41 100644
--- a/packages/compositions/src/program/schema.test.ts
+++ b/packages/compositions/src/program/schema.test.ts
@@ -4,6 +4,7 @@ import {
CompositorProgramSchema,
EaseRefSchema,
type FlexNode,
+ LayerAnimationSchema,
type LayoutNode,
LayoutNodeSchema,
} from "./schema.js";
@@ -82,6 +83,39 @@ const heroConfig = {
],
} as const;
+describe("keyframe values", () => {
+ const track = (prop: string, values: unknown[]) => ({
+ tracks: [
+ {
+ id: `${prop}-track`,
+ prop,
+ keyframes: values.map((value, i) => ({
+ id: `k${i}`,
+ frame: i * 4,
+ value,
+ })),
+ },
+ ],
+ });
+
+ it("keys path morphs with SVG path data", () => {
+ expect(
+ LayerAnimationSchema.safeParse(
+ track("d", ["M0 0 L10 0 L10 10 Z", "M0 0 L12 0 L10 12 Z"]),
+ ).success,
+ ).toBe(true);
+ expect(LayerAnimationSchema.safeParse(track("d", [0, 1])).success).toBe(
+ false,
+ );
+ });
+
+ it("keeps numeric props numeric", () => {
+ expect(LayerAnimationSchema.safeParse(track("x", [0, "10"])).success).toBe(
+ false,
+ );
+ });
+});
+
describe("CompositorProgramSchema (document v2)", () => {
it("parses the spec hero example with defaults applied", () => {
const parsed = CompositorProgramSchema.safeParse(heroConfig);
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index c6646410..abf5f343 100644
--- a/packages/compositions/src/program/schema.ts
+++ b/packages/compositions/src/program/schema.ts
@@ -567,6 +567,8 @@ const animationInvariants = (
track.prop === "strokeColor" ||
track.prop === "fill" ||
track.prop === "color";
+ // Path morphs key SVG path data.
+ const isPath = track.prop === "d";
for (let kIdx = 0; kIdx < keyframes.length; kIdx++) {
const kf = keyframes[kIdx];
if (kIdx > 0) {
@@ -602,6 +604,14 @@ const animationInvariants = (
path: ["tracks", tIdx, "keyframes", kIdx, "value"],
});
}
+ } else if (isPath) {
+ if (valType !== "string") {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: "Keyframe value for 'd' must be SVG path data (a string).",
+ path: ["tracks", tIdx, "keyframes", kIdx, "value"],
+ });
+ }
} else if (
valType !== "number" ||
Number.isNaN(kf.value as number) ||
diff --git a/packages/compositions/src/utils/audio-extractor.ts b/packages/compositions/src/utils/audio-extractor.ts
index 5090d59e..225ad70b 100644
--- a/packages/compositions/src/utils/audio-extractor.ts
+++ b/packages/compositions/src/utils/audio-extractor.ts
@@ -546,6 +546,28 @@ const RANGE_MARGIN_SEC = 0.05;
const GAIN_ONLY_PROCESSORS = new Set(["Compositor", "CompositorLayer"]);
/** Adds `src` into `dest` starting at `destStart` (which may be negative). */
+/**
+ * Which of a layer's gain props (`volume`, `muted`) it keys. Those the mix
+ * leaves to the layer's audio processor, which reads them per sample; the
+ * rest are applied as constants. Shared so both sides agree on the split.
+ */
+export function keyedGain(operation: unknown): {
+ volume: boolean;
+ muted: boolean;
+} {
+ const tracks =
+ (
+ operation as {
+ animation?: {
+ tracks?: ReadonlyArray<{ prop?: string; keyframes?: unknown[] }>;
+ };
+ } | null
+ )?.animation?.tracks ?? [];
+ const keys = (prop: string) =>
+ tracks.some((t) => t.prop === prop && (t.keyframes?.length ?? 0) > 0);
+ return { volume: keys("volume"), muted: keys("muted") };
+}
+
function addInto(dest: Float32Array, src: Float32Array, destStart: number) {
const from = Math.max(0, -destStart);
const to = Math.min(src.length, dest.length - destStart);
@@ -904,11 +926,15 @@ export async function mixAudioTracks(
return bus.channels;
}
+ // A layer that keys its volume or mute applies them itself, over time
+ // (the CompositorLayer audio processor); only resting values it does
+ // not key are baked into its sources here.
+ const keyed = keyedGain(op);
const volume =
inheritedVolume *
- (op.volume ?? 1) *
+ (keyed.volume ? 1 : (op.volume ?? 1)) *
(op.opacity === 0 ? 0 : 1) *
- ((op as Record<string, unknown>).muted ? 0 : 1);
+ (!keyed.muted && (op as Record<string, unknown>).muted ? 0 : 1);
const speedMultiplier = inheritedSpeed;
const nodeStartFrame = op.startFrame ?? op.timeline?.startFrame ?? 0;
diff --git a/packages/framefields/src/audio-layer-timing.test.ts b/packages/framefields/src/audio-layer-timing.test.ts
index 222b49d6..ba9687d1 100644
--- a/packages/framefields/src/audio-layer-timing.test.ts
+++ b/packages/framefields/src/audio-layer-timing.test.ts
@@ -76,6 +76,52 @@ describe("audio layer timing", () => {
expect(rms(ch, 0.24, 0.26)).toBeLessThan(full * 0.65);
});
+ it("plays a layer keyed up from a resting volume of 0, or unmuted by its keys", async () => {
+ // The resting value is what shows before any animation; the keys take
+ // over from there. A layer at volume 0 or muted is the natural way to
+ // write a fade in, and used to stay silent for good.
+ const faded = await mix(
+ Layer.audio(source, {
+ trimStartSec: 1,
+ durationFrames: 30,
+ volume: 0,
+ }).animate(
+ LayerAnimation.keys("volume", [
+ [0, 0],
+ [15, 0.5],
+ ]),
+ ),
+ );
+ const unmuted = await mix(
+ Layer.audio(source, {
+ trimStartSec: 1,
+ durationFrames: 30,
+ muted: true,
+ }).animate(
+ LayerAnimation.keys("muted", [
+ [0, true],
+ [15, false],
+ ]),
+ ),
+ );
+ // Each mix is auto-gained by its own peak, so compare like with like:
+ // the fade's plateau with a layer resting at the same volume, the
+ // unmuted layer with one never muted.
+ const level = async (volume: number) =>
+ rms(
+ await mix(
+ Layer.audio(source, { trimStartSec: 1, durationFrames: 30, volume }),
+ ),
+ 0.6,
+ 0.9,
+ );
+ const [half, full] = [await level(0.5), await level(1)];
+ expect(rms(faded, 0, 0.03)).toBeLessThan(half * 0.1);
+ expect(rms(faded, 0.6, 0.9)).toBeCloseTo(half, 2);
+ expect(rms(unmuted, 0.1, 0.4)).toBeLessThan(full * 0.01);
+ expect(rms(unmuted, 0.6, 0.9)).toBeCloseTo(full, 2);
+ });
+
it("counts volume keyframes from the layer's own start", async () => {
// The layer enters at frame 30 (1.0 s); its fade-in runs over its own
// first 15 frames, i.e. 1.0–1.5 s of the composition.
diff --git a/packages/framefields/src/dashed-stroke-render.test.ts b/packages/framefields/src/dashed-stroke-render.test.ts
new file mode 100644
index 00000000..7b0d2996
--- /dev/null
+++ b/packages/framefields/src/dashed-stroke-render.test.ts
@@ -0,0 +1,65 @@
+import { Canvas, loadImage } from "skia-canvas";
+import { describe, expect, it } from "vitest";
+import { Composition, Layer } from "./index.js";
+
+async function decode(png: Buffer) {
+ const img = await loadImage(png);
+ const canvas = new Canvas(img.width, img.height);
+ const ctx = canvas.getContext("2d");
+ ctx.drawImage(img, 0, 0);
+ const { data } = ctx.getImageData(0, 0, img.width, img.height);
+ return (x: number, y: number) =>
+ data[(Math.round(y) * img.width + Math.round(x)) * 4]!;
+}
+
+describe("dashed strokes", () => {
+ // `strokeDashArray` is written as SVG writes it; it used to reach the path
+ // pipeline as a string, which dropped the whole stroke.
+ it("draws an SVG dash list on paths and parametric shapes, with gaps", async () => {
+ const c = new Composition({
+ width: 400,
+ height: 200,
+ fps: 30,
+ durationMs: 1000,
+ backgroundColor: "#000000",
+ });
+ c.add([
+ Layer.shape("path", {
+ id: "line",
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: 400,
+ height: 200,
+ d: "M0 40 L400 40",
+ fillType: "none",
+ strokeColor: "#ffffff",
+ strokeWidth: 8,
+ strokeLineCap: "butt",
+ strokeDashArray: "20 20",
+ }),
+ Layer.shape("rect", {
+ id: "box",
+ position: "absolute",
+ x: 40,
+ y: 100,
+ width: 320,
+ height: 80,
+ fillType: "none",
+ strokeColor: "#ffffff",
+ strokeWidth: 8,
+ strokeLineCap: "butt",
+ strokeDashArray: "40, 40",
+ }),
+ ]);
+ const at = await decode(await c.renderFrame({ frame: 0 }));
+ // Dashes on the line at 0–20, 40–60 …; gaps at 20–40, 60–80 …
+ expect(at(10, 40)).toBeGreaterThan(200);
+ expect(at(50, 40)).toBeGreaterThan(200);
+ expect(at(30, 40)).toBeLessThan(40);
+ expect(at(70, 40)).toBeLessThan(40);
+ // The rect's top edge runs from its corner: a dash, then a gap.
+ expect(at(60, 100)).toBeGreaterThan(200);
+ expect(at(100, 100)).toBeLessThan(40);
+ });
+});
diff --git a/packages/webgpu-renderers/src/renderer2d/path-fill.test.ts b/packages/webgpu-renderers/src/renderer2d/path-fill.test.ts
new file mode 100644
index 00000000..4b34a2bb
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer2d/path-fill.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { cachedPathFill, pathContours } from "./path-geometry.js";
+
+/** The area the triangles cover (they never overlap). */
+function covered(tris: Float32Array): number {
+ let area = 0;
+ for (let i = 0; i < tris.length; i += 6) {
+ const [ax = 0, ay = 0, bx = 0, by = 0, cx = 0, cy = 0] = tris.subarray(
+ i,
+ i + 6,
+ );
+ area += Math.abs(((bx - ax) * (cy - ay) - (cx - ax) * (by - ay)) / 2);
+ }
+ return area;
+}
+
+const square = (x: number, y: number, s: number, reverse = false) =>
+ reverse
+ ? `M${x} ${y} L${x} ${y + s} L${x + s} ${y + s} L${x + s} ${y} Z`
+ : `M${x} ${y} L${x + s} ${y} L${x + s} ${y + s} L${x} ${y + s} Z`;
+
+describe("compound path fills", () => {
+ it("splits a path into its subpaths, even one starting where the last closed", () => {
+ const d = `${square(0, 0, 10)} M0 0 L-10 0 L-10 -10 Z`;
+ expect(pathContours(d).map((c) => c.length)).toEqual([4, 3]);
+ });
+
+ it("fills separate subpaths separately, with nothing bridging them", () => {
+ const d = `${square(0, 0, 10)} ${square(100, 0, 10)}`;
+ expect(covered(cachedPathFill(d))).toBeCloseTo(200);
+ });
+
+ it("cuts a hole wound the other way, and fills one wound the same way (nonzero)", () => {
+ expect(
+ covered(
+ cachedPathFill(`${square(0, 0, 100)} ${square(25, 25, 50, true)}`),
+ ),
+ ).toBeCloseTo(10000 - 2500);
+ expect(
+ covered(cachedPathFill(`${square(0, 0, 100)} ${square(25, 25, 50)}`)),
+ ).toBeCloseTo(10000);
+ });
+
+ it("fills an island in a lake", () => {
+ const d = `${square(0, 0, 100)} ${square(20, 20, 60, true)} ${square(40, 40, 20)}`;
+ expect(covered(cachedPathFill(d))).toBeCloseTo(10000 - 3600 + 400);
+ });
+
+ it("fills neighbours that share an edge, as states on a map do", () => {
+ const d = `${square(0, 0, 50)} ${square(50, 0, 50)} ${square(0, 50, 100)}`;
+ expect(covered(cachedPathFill(d))).toBeCloseTo(2500 + 2500 + 10000);
+ });
+
+ it("fills curves and arcs as their flattened outline", () => {
+ // A circle of radius 50 from two arcs (sweep 0 runs counter-clockwise on
+ // screen), with a square hole wound the other way.
+ const d = `M0 50 A50 50 0 1 0 100 50 A50 50 0 1 0 0 50 Z ${square(40, 40, 20)}`;
+ const area = covered(cachedPathFill(d));
+ expect(area).toBeGreaterThan(Math.PI * 2500 * 0.97 - 400);
+ expect(area).toBeLessThan(Math.PI * 2500 - 400 + 1);
+ });
+});
diff --git a/packages/webgpu-renderers/src/renderer2d/path-fill.ts b/packages/webgpu-renderers/src/renderer2d/path-fill.ts
new file mode 100644
index 00000000..42d3683f
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer2d/path-fill.ts
@@ -0,0 +1,145 @@
+/**
+ * Filling compound paths: every subpath is a contour, contours nest, and a
+ * region is filled by SVG's nonzero rule (the windings of the contours
+ * around it, summed, are not zero). Each filled contour is triangulated with
+ * its direct children as holes, so a map's coastlines and islands, a
+ * letter's counter or a ring fill as drawn instead of being bridged into
+ * one polygon.
+ *
+ * Contours are taken not to cross each other (each pair is nested or
+ * apart), which holds for maps, glyphs and icons; a contour that crosses
+ * itself is still triangulated as well as earcut can.
+ */
+import earcut from "earcut";
+import type { Point } from "./path-geometry.js";
+
+interface Contour {
+ points: Point[];
+ /** Signed area: its sign is the winding direction. */
+ area: number;
+ box: { x0: number; y0: number; x1: number; y1: number };
+ /** A point strictly inside, for containment (a vertex may lie on a neighbour's edge). */
+ inside: Point;
+ parent: number;
+ winding: number;
+}
+
+export function signedArea(points: readonly Point[]): number {
+ let area = 0;
+ for (let i = 0; i < points.length; i++) {
+ const a = points[i] as Point;
+ const b = points[(i + 1) % points.length] as Point;
+ area += a.x * b.y - b.x * a.y;
+ }
+ return area / 2;
+}
+
+function flat(points: readonly Point[]): number[] {
+ const out: number[] = [];
+ for (const p of points) out.push(p.x, p.y);
+ return out;
+}
+
+function boxOf(points: readonly Point[]): Contour["box"] {
+ const box = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
+ for (const p of points) {
+ box.x0 = Math.min(box.x0, p.x);
+ box.y0 = Math.min(box.y0, p.y);
+ box.x1 = Math.max(box.x1, p.x);
+ box.y1 = Math.max(box.y1, p.y);
+ }
+ return box;
+}
+
+/** The centroid of the contour's largest triangle: inside it, away from its edges. */
+function insidePoint(points: readonly Point[]): Point {
+ const coords = flat(points);
+ const tris = earcut(coords);
+ const at = (k: number): Point => ({
+ x: coords[k * 2] as number,
+ y: coords[k * 2 + 1] as number,
+ });
+ let best = -1;
+ let inside = points[0] as Point;
+ for (let i = 0; i < tris.length; i += 3) {
+ const a = at(tris[i] as number);
+ const b = at(tris[i + 1] as number);
+ const c = at(tris[i + 2] as number);
+ const size = Math.abs(
+ (b.x - a.x) * (c.y - a.y) - (c.x - a.x) * (b.y - a.y),
+ );
+ if (size > best) {
+ best = size;
+ inside = { x: (a.x + b.x + c.x) / 3, y: (a.y + b.y + c.y) / 3 };
+ }
+ }
+ return inside;
+}
+
+function contains(points: readonly Point[], p: Point): boolean {
+ let inside = false;
+ for (let i = 0, j = points.length - 1; i < points.length; j = i++) {
+ const a = points[i] as Point;
+ const b = points[j] as Point;
+ if (
+ a.y > p.y !== b.y > p.y &&
+ p.x < ((b.x - a.x) * (p.y - a.y)) / (b.y - a.y) + a.x
+ )
+ inside = !inside;
+ }
+ return inside;
+}
+
+const encloses = (p: Contour, c: Contour) =>
+ p.box.x0 <= c.box.x0 &&
+ p.box.y0 <= c.box.y0 &&
+ p.box.x1 >= c.box.x1 &&
+ p.box.y1 >= c.box.y1 &&
+ contains(p.points, c.inside);
+
+/** Triangles filling closed `contours` by the nonzero rule, as flat [x, y, …] vertices. */
+export function fillContours(contours: readonly Point[][]): Float32Array {
+ const all: Contour[] = contours.map((points) => ({
+ points,
+ area: signedArea(points),
+ box: boxOf(points),
+ inside: insidePoint(points),
+ parent: -1,
+ winding: 0,
+ }));
+ // Largest first, so a contour's parent has its winding before it is reached.
+ const order = all
+ .map((_, i) => i)
+ .sort(
+ (a, b) =>
+ Math.abs((all[b] as Contour).area) - Math.abs((all[a] as Contour).area),
+ );
+ order.forEach((ci, rank) => {
+ const c = all[ci] as Contour;
+ // Its parent is the smallest larger contour around it.
+ for (let r = rank - 1; r >= 0; r--) {
+ const pi = order[r] as number;
+ if (encloses(all[pi] as Contour, c)) {
+ c.parent = pi;
+ break;
+ }
+ }
+ const around = c.parent >= 0 ? (all[c.parent] as Contour).winding : 0;
+ c.winding = around + Math.sign(c.area);
+ });
+
+ const out: number[] = [];
+ all.forEach((c, ci) => {
+ if (c.winding === 0) return;
+ const coords = flat(c.points);
+ const holeStarts: number[] = [];
+ for (const h of all) {
+ if (h.parent !== ci) continue;
+ holeStarts.push(coords.length / 2);
+ for (const p of h.points) coords.push(p.x, p.y);
+ }
+ for (const k of earcut(coords, holeStarts))
+ out.push(coords[k * 2] as number, coords[k * 2 + 1] as number);
+ });
+ return new Float32Array(out);
+}
diff --git a/packages/webgpu-renderers/src/renderer2d/path-geometry.test.ts b/packages/webgpu-renderers/src/renderer2d/path-geometry.test.ts
index 2cc387f9..e1abd463 100644
--- a/packages/webgpu-renderers/src/renderer2d/path-geometry.test.ts
+++ b/packages/webgpu-renderers/src/renderer2d/path-geometry.test.ts
@@ -8,6 +8,7 @@ import {
buildShapeSvgPath,
buildStarPath,
dashPathSegments,
+ parseDashArray,
parseSvgPathToSegments,
sampleCubicBezier,
sampleQuadraticBezier,
@@ -155,6 +156,27 @@ describe("path-geometry", () => {
});
});
+ describe("parseDashArray", () => {
+ it("reads SVG dash lists, with spaces or commas", () => {
+ expect(parseDashArray("16 12")).toEqual([16, 12]);
+ expect(parseDashArray(" 4, 8 ,2 6 ")).toEqual([4, 8, 2, 6]);
+ expect(parseDashArray([10, 5])).toEqual([10, 5]);
+ });
+
+ it("repeats an odd list, as SVG does", () => {
+ expect(parseDashArray("5")).toEqual([5, 5]);
+ expect(parseDashArray("4 2 1")).toEqual([4, 2, 1, 4, 2, 1]);
+ });
+
+ it("means a solid stroke for nothing, negatives, junk or zero length", () => {
+ expect(parseDashArray(undefined)).toBeUndefined();
+ expect(parseDashArray("")).toBeUndefined();
+ expect(parseDashArray("4 -2")).toBeUndefined();
+ expect(parseDashArray("4 px")).toBeUndefined();
+ expect(parseDashArray("0 0")).toBeUndefined();
+ });
+ });
+
describe("dashPathSegments", () => {
const line = [{ p0: { x: 0, y: 0 }, p1: { x: 100, y: 0 } }];
diff --git a/packages/webgpu-renderers/src/renderer2d/path-geometry.ts b/packages/webgpu-renderers/src/renderer2d/path-geometry.ts
index 245b724a..5a15a87b 100644
--- a/packages/webgpu-renderers/src/renderer2d/path-geometry.ts
+++ b/packages/webgpu-renderers/src/renderer2d/path-geometry.ts
@@ -1,3 +1,5 @@
+import { fillContours, signedArea } from "./path-fill.js";
+
export interface Point {
x: number;
y: number;
@@ -147,8 +149,27 @@ export function sampleSvgArc(
* Parse an SVG path string (M, L, H, V, C, S, Q, T, A, Z) into line segments.
*/
export function parseSvgPathToSegments(d: string): PathSegment[] {
+ return parseSvgPath(d).segments;
+}
+
+/**
+ * The path's segments, and for each the subpath it belongs to (every M
+ * starts one): fills need to know where each subpath begins.
+ */
+function parseSvgPath(d: string): {
+ segments: PathSegment[];
+ subpaths: number[];
+} {
const segments: PathSegment[] = [];
- if (!d || typeof d !== "string") return segments;
+ const subpaths: number[] = [];
+ if (!d || typeof d !== "string") return { segments, subpaths };
+ let subpath = -1;
+ const emit = (...added: PathSegment[]) => {
+ for (const seg of added) {
+ segments.push(seg);
+ subpaths.push(subpath);
+ }
+ };
// Tokenize SVG path commands and numeric values
const tokens: Array<string | number> = [];
@@ -197,10 +218,11 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
if (first) {
current = { x, y };
subpathStart = { x, y };
+ subpath++;
first = false;
} else {
// Subsequent pairs in M/m are treated as L/l
- segments.push({ p0: current, p1: { x, y } });
+ emit({ p0: current, p1: { x, y } });
current = { x, y };
}
}
@@ -216,7 +238,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
x += current.x;
y += current.y;
}
- segments.push({ p0: current, p1: { x, y } });
+ emit({ p0: current, p1: { x, y } });
current = { x, y };
}
lastCubicControl = null;
@@ -228,7 +250,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
let x = getNum();
if (isRelative) x += current.x;
const next: Point = { x, y: current.y };
- segments.push({ p0: current, p1: next });
+ emit({ p0: current, p1: next });
current = next;
}
lastCubicControl = null;
@@ -240,7 +262,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
let y = getNum();
if (isRelative) y += current.y;
const next: Point = { x: current.x, y };
- segments.push({ p0: current, p1: next });
+ emit({ p0: current, p1: next });
current = next;
}
lastCubicControl = null;
@@ -266,7 +288,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
const p1: Point = { x: x1, y: y1 };
const p2: Point = { x: x2, y: y2 };
const end: Point = { x, y };
- segments.push(...sampleCubicBezier(current, p1, p2, end));
+ emit(...sampleCubicBezier(current, p1, p2, end));
current = end;
lastCubicControl = p2;
}
@@ -296,7 +318,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
}
const p2: Point = { x: x2, y: y2 };
const end: Point = { x, y };
- segments.push(...sampleCubicBezier(current, p1, p2, end));
+ emit(...sampleCubicBezier(current, p1, p2, end));
current = end;
lastCubicControl = p2;
}
@@ -317,7 +339,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
}
const p1: Point = { x: x1, y: y1 };
const end: Point = { x, y };
- segments.push(...sampleQuadraticBezier(current, p1, end));
+ emit(...sampleQuadraticBezier(current, p1, end));
current = end;
lastQuadControl = p1;
}
@@ -342,7 +364,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
p1 = { x: current.x, y: current.y };
}
const end: Point = { x, y };
- segments.push(...sampleQuadraticBezier(current, p1, end));
+ emit(...sampleQuadraticBezier(current, p1, end));
current = end;
lastQuadControl = p1;
}
@@ -363,7 +385,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
y += current.y;
}
const end: Point = { x, y };
- segments.push(
+ emit(
...sampleSvgArc(current, rx, ry, rotation, largeArc, sweep, end),
);
current = end;
@@ -377,7 +399,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
Math.hypot(current.x - subpathStart.x, current.y - subpathStart.y) >
1e-5
) {
- segments.push({ p0: current, p1: subpathStart });
+ emit({ p0: current, p1: subpathStart });
}
current = subpathStart;
lastCubicControl = null;
@@ -389,7 +411,7 @@ export function parseSvgPathToSegments(d: string): PathSegment[] {
}
}
- return segments;
+ return { segments, subpaths };
}
/**
@@ -480,6 +502,30 @@ export function trimPathSegments(
}
}
+/**
+ * A dash pattern as SVG's `stroke-dasharray` writes it ("16 12", "4,8") or as
+ * numbers, ready for {@link dashPathSegments}. Following SVG, an odd list is
+ * repeated to make it even, and a negative or unreadable entry, or a pattern
+ * of zero length, means a solid stroke (`undefined`).
+ */
+export function parseDashArray(
+ value: string | readonly number[] | undefined,
+): number[] | undefined {
+ if (value === undefined) return undefined;
+ const parts =
+ typeof value === "string"
+ ? value
+ .trim()
+ .split(/[\s,]+/)
+ .filter(Boolean)
+ .map(Number)
+ : [...value];
+ if (parts.length === 0 || parts.some((n) => !Number.isFinite(n) || n < 0))
+ return undefined;
+ if (parts.reduce((sum, n) => sum + n, 0) <= 0) return undefined;
+ return parts.length % 2 === 1 ? [...parts, ...parts] : parts;
+}
+
/**
* Apply dash patterns along linear path segments.
*/
@@ -833,6 +879,49 @@ export function triangulatePolygon(contour: Point[]): Point[] {
return triangles;
}
+/** A path's subpaths as closed point lists, degenerate ones dropped. */
+export function pathContours(d: string): Point[][] {
+ const bySubpath = new Map<number, Point[]>();
+ const { segments, subpaths } = parseSvgPath(d);
+ segments.forEach((seg, i) => {
+ const id = subpaths[i] ?? 0;
+ let points = bySubpath.get(id);
+ if (!points) {
+ points = [seg.p0];
+ bySubpath.set(id, points);
+ }
+ points.push(seg.p1);
+ });
+ const contours: Point[][] = [];
+ for (const points of bySubpath.values()) {
+ const first = points[0] as Point;
+ const last = points[points.length - 1] as Point;
+ if (Math.hypot(last.x - first.x, last.y - first.y) < 1e-5) points.pop();
+ if (points.length >= 3 && Math.abs(signedArea(points)) > 1e-6)
+ contours.push(points);
+ }
+ return contours;
+}
+
+/** Path fills are redrawn every frame from the same data: keep the last few. */
+const PATH_FILL_CACHE = 64;
+const pathFills = new Map<string, Float32Array>();
+
+/** Triangles filling path `d` by the nonzero rule (see {@link fillContours}). */
+export function cachedPathFill(d: string): Float32Array {
+ const hit = pathFills.get(d);
+ if (hit) {
+ pathFills.delete(d);
+ pathFills.set(d, hit);
+ return hit;
+ }
+ const tris = fillContours(pathContours(d));
+ pathFills.set(d, tris);
+ if (pathFills.size > PATH_FILL_CACHE)
+ pathFills.delete(pathFills.keys().next().value as string);
+ return tris;
+}
+
/**
* Triangulate a shape geometry into a flat Float32Array of 2D vertex pairs [x, y, x, y, ...].
*/
@@ -970,18 +1059,7 @@ export function triangulateShape(config: ShapeGeometryConfig): Float32Array {
]);
}
- if (shapeType === "path" && config.path) {
- const segments = parseSvgPathToSegments(config.path);
- if (segments.length === 0) return new Float32Array(0);
- const contour = segments.map((s) => s.p0);
- const tris = triangulatePolygon(contour);
- const out = new Float32Array(tris.length * 2);
- for (let i = 0; i < tris.length; i++) {
- out[i * 2] = tris[i].x;
- out[i * 2 + 1] = tris[i].y;
- }
- return out;
- }
+ if (shapeType === "path" && config.path) return cachedPathFill(config.path);
return new Float32Array(0);
}
diff --git a/packages/webgpu-renderers/src/renderer2d/path-pipeline.ts b/packages/webgpu-renderers/src/renderer2d/path-pipeline.ts
index f183fd2f..c854c397 100644
--- a/packages/webgpu-renderers/src/renderer2d/path-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer2d/path-pipeline.ts
@@ -5,11 +5,10 @@ import type { Color, DrawOpts } from "./index.js";
import {
dashPathSegments,
type PathSegment,
- type Point,
parseSvgPathToSegments,
trimPathSegments,
} from "./path-geometry.js";
-import { createUniformLayout, createVec2Pipeline } from "./pipeline-utils.js";
+import { createUniformLayout, PREMULTIPLIED_OVER } from "./pipeline-utils.js";
import type { TransformStack } from "./transform-stack.js";
import { UniformBindGroupCache } from "./uniform-bind-group-cache.js";
@@ -22,15 +21,18 @@ export interface PathDrawOpts extends DrawOpts {
strokeDashOffset?: number;
}
+/** A straight segment's two ends, the instance the stroke shader expands into a quad. */
+const SEGMENT_FLOATS = 4;
+
export class PathPipeline {
private device: GPUDevice;
private pipeline: GPURenderPipeline;
private maxPipeline: GPURenderPipeline;
private uniformLayout: GPUBindGroupLayout;
private uniformPool: BufferPool;
- private vertexPool: BufferPool;
+ private segmentPool: BufferPool;
private uniformBindGroupCache = new UniformBindGroupCache();
- private scratchData = new Float32Array(28);
+ private scratchData = new Float32Array(24);
constructor(device: GPUDevice, format: GPUTextureFormat) {
this.device = device;
@@ -38,7 +40,7 @@ export class PathPipeline {
4096,
GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
);
- this.vertexPool = new BufferPool(
+ this.segmentPool = new BufferPool(
4096,
GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
);
@@ -49,39 +51,43 @@ export class PathPipeline {
});
this.uniformLayout = createUniformLayout(device);
-
- this.pipeline = createVec2Pipeline(device, {
- label: "PathPipeline",
- module,
- uniformLayout: this.uniformLayout,
- format,
- topology: "triangle-strip",
- });
-
- this.maxPipeline = createVec2Pipeline(device, {
- label: "PathPipeline.max",
- module,
- uniformLayout: this.uniformLayout,
- format,
- topology: "triangle-strip",
- blend: {
- color: {
- srcFactor: "one",
- dstFactor: "one",
- operation: "max",
+ const create = (label: string, blend: GPUBlendState) =>
+ device.createRenderPipeline({
+ label,
+ layout: device.createPipelineLayout({
+ bindGroupLayouts: [this.uniformLayout],
+ }),
+ vertex: {
+ module,
+ entryPoint: "vs",
+ buffers: [
+ {
+ arrayStride: SEGMENT_FLOATS * 4,
+ stepMode: "instance",
+ attributes: [
+ { shaderLocation: 0, offset: 0, format: "float32x4" },
+ ],
+ },
+ ],
},
- alpha: {
- srcFactor: "one",
- dstFactor: "one",
- operation: "max",
+ fragment: {
+ module,
+ entryPoint: "fs",
+ targets: [{ format, blend }],
},
- },
+ primitive: { topology: "triangle-strip" },
+ });
+
+ this.pipeline = create("PathPipeline", PREMULTIPLIED_OVER);
+ this.maxPipeline = create("PathPipeline.max", {
+ color: { srcFactor: "one", dstFactor: "one", operation: "max" },
+ alpha: { srcFactor: "one", dstFactor: "one", operation: "max" },
});
}
resetPools(): void {
this.uniformPool.reset();
- this.vertexPool.reset();
+ this.segmentPool.reset();
}
drawPath(
@@ -94,53 +100,16 @@ export class PathPipeline {
surfaceHeight: number,
opts?: PathDrawOpts,
): void {
- let segments = parseSvgPathToSegments(pathStr);
- if (segments.length === 0) return;
-
- if (
- opts?.trimStart !== undefined ||
- opts?.trimEnd !== undefined ||
- opts?.trimOffset !== undefined
- ) {
- segments = trimPathSegments(
- segments,
- opts.trimStart ?? 0,
- opts.trimEnd ?? 1,
- opts.trimOffset ?? 0,
- );
- }
-
- if (opts?.strokeDashArray && opts.strokeDashArray.length > 0) {
- segments = dashPathSegments(
- segments,
- opts.strokeDashArray,
- opts.strokeDashOffset ?? 0,
- );
- }
-
- if (segments.length === 0) return;
-
- const c = parseColor(color);
- const opacity = opts?.opacity ?? 1.0;
- let capType = 0;
- if (opts?.strokeLineCap === "butt") capType = 1;
- else if (opts?.strokeLineCap === "square") capType = 2;
-
- for (const segment of segments) {
- this.drawSegment(
- pass,
- transformStack,
- segment.p0,
- segment.p1,
- c,
- strokeWidth,
- capType,
- surfaceWidth,
- surfaceHeight,
- opacity,
- opts,
- );
- }
+ this.drawSegments(
+ pass,
+ transformStack,
+ parseSvgPathToSegments(pathStr),
+ color,
+ strokeWidth,
+ surfaceWidth,
+ surfaceHeight,
+ opts,
+ );
}
drawSegments(
@@ -175,110 +144,65 @@ export class PathPipeline {
);
}
- if (activeSegments.length === 0) return;
-
- const c = parseColor(color);
- const opacity = opts?.opacity ?? 1.0;
- let capType = 0;
- if (opts?.strokeLineCap === "butt") capType = 1;
- else if (opts?.strokeLineCap === "square") capType = 2;
-
- for (const segment of activeSegments) {
- this.drawSegment(
- pass,
- transformStack,
- segment.p0,
- segment.p1,
- c,
- strokeWidth,
- capType,
- surfaceWidth,
- surfaceHeight,
- opacity,
- opts,
- );
+ // One instance per segment; a segment of no length draws nothing.
+ const ends = new Float32Array(activeSegments.length * SEGMENT_FLOATS);
+ let count = 0;
+ for (const { p0, p1 } of activeSegments) {
+ if (Math.hypot(p1.x - p0.x, p1.y - p0.y) < 1e-6) continue;
+ const at = count++ * SEGMENT_FLOATS;
+ ends[at] = p0.x;
+ ends[at + 1] = p0.y;
+ ends[at + 2] = p1.x;
+ ends[at + 3] = p1.y;
}
- }
+ if (count === 0) return;
- private drawSegment(
- pass: GPURenderPassEncoder,
- transformStack: TransformStack,
- p0: Point,
- p1: Point,
- color: Color,
- strokeWidth: number,
- capType: number,
- surfaceWidth: number,
- surfaceHeight: number,
- opacity: number,
- opts?: DrawOpts,
- ): void {
+ const c = parseColor(color);
const data = this.scratchData;
transformStack.packIntoBuffer(
data,
- opacity,
+ opts?.opacity ?? 1.0,
surfaceWidth,
surfaceHeight,
opts?.transform,
);
-
data[15] = strokeWidth;
- data[16] = color.r;
- data[17] = color.g;
- data[18] = color.b;
- data[19] = color.a;
- data[20] = capType;
+ data[16] = c.r;
+ data[17] = c.g;
+ data[18] = c.b;
+ data[19] = c.a;
+ data[20] =
+ opts?.strokeLineCap === "butt"
+ ? 1
+ : opts?.strokeLineCap === "square"
+ ? 2
+ : 0;
data[21] = 0;
data[22] = 0;
data[23] = 0;
- data[24] = p0.x;
- data[25] = p0.y;
- data[26] = p1.x;
- data[27] = p1.y;
-
const uniformBuffer = this.uniformPool.getBuffer(this.device, data);
-
- // Calculate a quad that covers the line segment plus strokeWidth padding
- const dx = p1.x - p0.x;
- const dy = p1.y - p0.y;
- const len = Math.sqrt(dx * dx + dy * dy);
- if (len < 1e-6) return;
-
- const padding = strokeWidth * 0.5 + 2.0;
- const nx = (dx / len) * padding;
- const ny = (dy / len) * padding;
- const px = -ny;
- const py = nx;
-
- const vertexData = new Float32Array([
- p0.x - nx - px,
- p0.y - ny - py,
- p0.x - nx + px,
- p0.y - ny + py,
- p1.x + nx - px,
- p1.y + ny - py,
- p1.x + nx + px,
- p1.y + ny + py,
- ]);
- const vertexBuffer = this.vertexPool.getBuffer(this.device, vertexData);
-
- const useMax = opts?.blendMode === ("max" as any);
- const pipeline = useMax ? this.maxPipeline : this.pipeline;
-
- pass.setPipeline(pipeline);
- const uniformBindGroup = this.uniformBindGroupCache.getBindGroup(
+ const segmentBuffer = this.segmentPool.getBuffer(
this.device,
- this.uniformLayout,
- uniformBuffer,
+ ends.subarray(0, count * SEGMENT_FLOATS),
+ );
+
+ const useMax = (opts?.blendMode as string | undefined) === "max";
+ pass.setPipeline(useMax ? this.maxPipeline : this.pipeline);
+ pass.setBindGroup(
+ 0,
+ this.uniformBindGroupCache.getBindGroup(
+ this.device,
+ this.uniformLayout,
+ uniformBuffer,
+ ),
);
- pass.setBindGroup(0, uniformBindGroup);
- pass.setVertexBuffer(0, vertexBuffer);
- pass.draw(4);
+ pass.setVertexBuffer(0, segmentBuffer);
+ pass.draw(4, count);
}
destroy(): void {
this.uniformPool.destroy();
- this.vertexPool.destroy();
+ this.segmentPool.destroy();
this.uniformBindGroupCache.destroy();
}
}
diff --git a/packages/webgpu-renderers/src/shaders/path.ts b/packages/webgpu-renderers/src/shaders/path.ts
index dedfd8b7..d5995867 100644
--- a/packages/webgpu-renderers/src/shaders/path.ts
+++ b/packages/webgpu-renderers/src/shaders/path.ts
@@ -1,3 +1,10 @@
+/**
+ * Strokes a path in one instanced draw: each instance is one straight
+ * segment (p0, p1), expanded by the vertex shader into a quad that covers it
+ * plus half the stroke width and 2 px of antialiasing; the fragment shader
+ * shades the segment's capped distance field. Everything shared by the
+ * path (transform, colour, width, cap) is in the uniforms.
+ */
export const pathWgsl = `
struct Uniforms {
transformCol0 : vec4<f32>,
@@ -6,8 +13,6 @@ struct Uniforms {
params : vec4<f32>, // x = opacity, y = surfaceWidth, z = surfaceHeight, w = strokeWidth
color : vec4<f32>,
style : vec4<f32>, // x = capType (0 = round, 1 = butt, 2 = square)
- p0 : vec2<f32>,
- p1 : vec2<f32>,
};
@group(0) @binding(0) var<uniform> u : Uniforms;
@@ -15,17 +20,30 @@ struct Uniforms {
struct VSOut {
@builtin(position) pos : vec4<f32>,
@location(0) localPos : vec2<f32>,
+ @location(1) @interpolate(flat) p0 : vec2<f32>,
+ @location(2) @interpolate(flat) p1 : vec2<f32>,
};
-@vertex fn vs(@location(0) xy : vec2<f32>) -> VSOut {
+@vertex fn vs(@builtin(vertex_index) corner : u32, @location(0) seg : vec4<f32>) -> VSOut {
+ let p0 = seg.xy;
+ let p1 = seg.zw;
+ let d = p1 - p0;
+ let len = max(length(d), 1e-6);
+ let padding = u.params.w * 0.5 + 2.0;
+ let along = (d / len) * padding;
+ let across = vec2<f32>(-along.y, along.x);
+ // Triangle strip: p0 −along ∓across, then p1 +along ∓across.
+ let atEnd = corner >= 2u;
+ let side = select(-1.0, 1.0, (corner & 1u) == 1u);
+ let xy = select(p0 - along, p1 + along, atEnd) + across * side;
+
let transform = mat3x3<f32>(u.transformCol0.xyz, u.transformCol1.xyz, u.transformCol2.xyz);
let p = transform * vec3<f32>(xy, 1.0);
-
let surfaceSize = u.params.yz;
let clipX = (p.x / surfaceSize.x) * 2.0 - 1.0;
let clipY = 1.0 - (p.y / surfaceSize.y) * 2.0;
- return VSOut(vec4<f32>(clipX, clipY, 0.0, 1.0), xy);
+ return VSOut(vec4<f32>(clipX, clipY, 0.0, 1.0), xy, p0, p1);
}
fn sdSegmentWithCap(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>, radius: f32, capType: f32) -> f32 {
@@ -37,10 +55,10 @@ fn sdSegmentWithCap(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>, radius: f32, capTy
let dir = ba / len;
let normal = vec2<f32>(-dir.y, dir.x);
let pa = p - a;
-
+
let proj = dot(pa, dir);
let perp = abs(dot(pa, normal));
-
+
if (capType > 0.5 && capType < 1.5) {
// Butt cap: terminates strictly at endpoints a and b
let dx = max(-proj, proj - len);
@@ -64,15 +82,15 @@ fn sdSegmentWithCap(p: vec2<f32>, a: vec2<f32>, b: vec2<f32>, radius: f32, capTy
@fragment fn fs(in : VSOut) -> @location(0) vec4<f32> {
let radius = u.params.w * 0.5;
- let d = sdSegmentWithCap(in.localPos, u.p0, u.p1, radius, u.style.x);
-
+ let d = sdSegmentWithCap(in.localPos, in.p0, in.p1, radius, u.style.x);
+
let fw = max(fwidth(d), 1e-5);
let edgeAlpha = clamp(0.5 - d / fw, 0.0, 1.0);
let alpha = u.color.a * u.params.x * edgeAlpha;
if (alpha <= 0.0) {
discard;
}
-
+
return vec4<f32>(u.color.rgb * alpha, alpha);
}
`;
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index b3e2c72b..324bc747 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -94,7 +94,7 @@ All `Layer.*` builders return `AnimatableNode<T>` instances with chainable `.ani
| `Layer.svg(src, options)` | `"media"` | Vector SVG asset. Options: `fit: "contain"`. |
| `Layer.lottie(src, options)` | `"media"` | Lottie vector animation file (`.json`, `.lottie`). Decoded and rendered via ThorVG. Options: `fit: "contain" \| "cover" \| "fill"`, `width`, `height`. |
| `Layer.audio(src, options)` | `"media"` | Audio track layer. Options: `volume`, `startFrame`, `durationFrames`. |
-| `Layer.shape(type, options)` | `"shape"` | Parametric vector graphics (`"rect"`, `"circle"`, `"ellipse"`, `"polygon"`, `"star"`, `"arrow"`, `"path"`). Options: `fill` (a color or CSS gradient), `d` (SVG path data with arcs; keyframe it to morph shapes), `strokeWidth`, `strokeColor`, `trimStart`, `trimEnd`. |
+| `Layer.shape(type, options)` | `"shape"` | Parametric vector graphics (`"rect"`, `"circle"`, `"ellipse"`, `"polygon"`, `"star"`, `"arrow"`, `"path"`). Options: `fill` (a color or CSS gradient), `d` (SVG path data with arcs; several subpaths fill by the nonzero rule, so holes and islands work; keyframe it to morph shapes), `strokeWidth`, `strokeColor`, `strokeDashArray` (SVG syntax, `"12 8"`), `trimStart`, `trimEnd`. |
| `Layer.particles(options)` | `"media"` | GPU particle system (see *GPU Particles*). |
| `Layer.vfx(options)` | `"media"` | Procedural full-frame VFX: smoke, fire, rain, snow, aurora… (see *Procedural VFX*). |
| `Layer.caption(src, options)` | `"media"` | SRT-driven synchronized subtitle engine. Bottom-anchored auto-wrapping cues. |
@@ -173,7 +173,7 @@ const pop = LayerAnimation.create()
// Static form: LayerAnimation.keys("rotation", [[0, -8], [20, 0, "expo.out"]])
```
-Keyframes past the layer's `durationFrames` never play; the render warns (`animation_truncated`) and `renderVideo({ qa: true })` reports it.
+Until its first key a track holds that key's value, and after its last key the last: `keys("opacity", [[40, 0], [48, 1]])` keeps a layer hidden until frame 40, with no hold key at 0 needed. Keyframes past the layer's `durationFrames` never play; the render warns (`animation_truncated`) and `renderVideo({ qa: true })` reports it.
### 2. Kinetic Typography (`TextAnimator`)
Text animators operate at the GPU glyph instancing level, cascading offsets across characters, words, or lines: