Skip to content

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

fix(compositor): rasterize 2D leaves at their on-screen scale

okanasl7af132c62eea
diff --git a/.changeset/sharp-scaled-leaves.md b/.changeset/sharp-scaled-leaves.md
new file mode 100644
index 00000000..0e488b2d
--- /dev/null
+++ b/.changeset/sharp-scaled-leaves.md
@@ -0,0 +1,5 @@
+---
+"framefields": patch
+---
+
+Text, shapes, images and SVGs stay sharp when an ancestor scales them up. A 2D leaf now rasterizes at its scale on the canvas (up to 4×) instead of magnifying a layout-size texture, so a camera push or a card at `scale: 2` keeps crisp glyphs, round dots and clean borders. Text shadows, masks, motion blur, `LayerStyle` and Gaussian/box `Blur` scale with the layer; a leaf whose effect doesn't declare how far it scales keeps its layout-size raster, as do 3D and deflickered leaves. Layers at scale 1 or below render exactly as before.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8082f79f..47622f5e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,7 +21,7 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb
- `packages/vision-sam`: SAM 2.1 Tiny/Small and SAM 3 trackers (Apache-2.0 code; SAM 3 weights need runtime SAM License acceptance), private; `framefields` bundles it as a lazy chunk (`clip-vision.ts` imports it dynamically for `comp.vision(..., { sam2 | sam3 })`; `index.ts` re-exports types only) and exposes the trackers as `framefields/sam`. No weights ship; `packages/framefields/NOTICE.md` covers their licenses. Pins in `src/models/registry.ts`.
- `packages/core`: shared types, `Effect` base, signals, `emojiPresentation` (the one UTS #51 rule used by layout, preload and lint).
- Others: `renderers`, `media`, `node-sdk`, `server-utils`, `client-utils`, `tensor-webgpu`, `vision`, `tsconfig`.
-- `nodes/node-*`: one VFX/audio/layout node each (`src/shared/`, `src/renderers/`, `src/index.ts`). Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (guarded by `skillmd-check.test.ts`).
+- `nodes/node-*`: one VFX/audio/layout node each (`src/shared/`, `src/renderers/`, `src/index.ts`). Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (guarded by `skillmd-check.test.ts`). Effect renderers declare `reach` and `maxPixelScale` (node-sdk) when they can: without `maxPixelScale` a scaled-up leaf using the effect stays at layout resolution.
- `apps/renderer-service`: HTTP render service (Docker, RunPod).
- `examples/NN_*`: reference films. Study `19_framefields_film` (structure), `22_framefields_launch` (lyric sync), `28_physics_dancer` (physics, vision, GPU particles) before writing one.
- `plugins/framefields/skills/framefields{,-compose,-effects,-render,-vision}`: agent skills, symlinked from `.agents/skills` and `.claude/skills`.
diff --git a/nodes/node-blur/src/renderers/webgpu-renderer.ts b/nodes/node-blur/src/renderers/webgpu-renderer.ts
index 5ef7cfae..8b28a270 100644
--- a/nodes/node-blur/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-blur/src/renderers/webgpu-renderer.ts
@@ -12,6 +12,7 @@ import {
FULLSCREEN_QUAD_WGSL,
fragmentBindGroupLayout,
perDevice,
+ pixelScale,
signalTextureView,
signalTiming,
texturesLayout,
@@ -622,7 +623,7 @@ export const BlurWebGPURenderer: WebGPUNodeRenderer = async (args) => {
props.containerWidth ??
ctx.surface.width /
(typeof window !== "undefined" ? window.devicePixelRatio : 1);
- const dpiScale = width / logicalWidth;
+ const dpiScale = (width / logicalWidth) * pixelScale(args);
const nodeId = op.inputs ? Object.keys(op.inputs)[0] : "blur_node";
const resolveBindable = (
@@ -897,3 +898,21 @@ export const BlurWebGPURenderer: WebGPUNodeRenderer = async (args) => {
// Final Pass: Draw result to targetView using standard drawTexture for blending/opacity
drawTextureToTarget(args, outTex2, op.opacity ?? 1);
};
+
+/**
+ * A Gaussian or box blur of a set strength keeps its look at any pixel
+ * scale: the strength scales with it and neither kernel has a cap (the
+ * Gaussian strides past 20 px). The other kinds stop at fixed radii, and a
+ * strength bound to a signal is read on the GPU, unscaled.
+ */
+BlurWebGPURenderer.maxPixelScale = (operation) => {
+ const op = operation as Partial<BlurOp>;
+ const kind = op.blurType ?? "Gaussian";
+ const bound =
+ typeof op.strengthHandleId === "string" &&
+ op.inputs?.[op.strengthHandleId]?.connectionValid === true;
+ const fixed = op.strength === undefined || typeof op.strength === "number";
+ return (kind === "Gaussian" || kind === "Box") && fixed && !bound
+ ? Number.POSITIVE_INFINITY
+ : 1;
+};
diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.md
index 1da235f7..54a2d4d6 100644
--- a/nodes/node-compositor/SKILL.md
+++ b/nodes/node-compositor/SKILL.md
@@ -218,6 +218,7 @@ Each track represents animatable property modifications:
- **Automatic mesh instancing:** consecutive opaque draws of the same shared mesh with matching material state use one GPU draw with per-object model and normal matrices. Transparent, skinned, morphed, audio-deformed and glass meshes retain separate draws; shadows retain their individual draw submissions.
- **Instanced 3D Meshes (`instances3d`):** `kind: "model3d"` with `instances3d` renders hundreds or thousands of mesh instances in 1 GPU draw call (`drawIndexed(indexCount, instanceCount)`). Supports single or multi-mesh variants with round-robin or variant indexing, dynamic per-instance transforms, and per-instance emissive / color modulation. In `framefields`, created with `Layer3D.instances({ count, mesh, instanceAt, bodies, emissiveBySpeed })`.
- **GPU 3D Swarms (`swarm3d`):** `kind: "model3d"` with `swarm3d` runs continuous 3D particle simulation in a WebGPU compute shader with 3D curl noise, 3D vortex fields (`swirl`, `pull`, `axial`), ground plane collisions with Coulomb sliding friction and rotational roll torque, and kinetic heat accumulation/cooling, packing directly into GPU instance buffers.
+- **Scaled 2D layers stay sharp:** a `text`, `shape` or `media` node rasterizes at its scale on the canvas (an ancestor's `scale` included), up to 4× and within the GPU's texture size, so zooming into a layout shows crisp glyphs and edges; borders follow. Its mask, relighting, motion-blur padding and effects work at that resolution: an effect renderer that declares `maxPixelScale` gets `pixelScale` and scales its pixel-unit parameters by it (`LayerStyle`, Gaussian/box `Blur`). 3D and deflickered nodes, media wrapped in effects/crop/vision, and nodes with an effect lacking `maxPixelScale` keep their layout-size raster.
- **Planar Reflective Floor (`floor` in `environment`):** `kind: "light"` with `lightType: "environment"` and `floor: { y, color, reflectivity, roughness, fadeDistance, opacity }` renders a mirrored-camera reflection pass, subterranean fragment clipping, 2-pass anisotropic roughness blur ($\sigma_y \approx 3.5 \sigma_x$), Schlick Fresnel grazing reflections, and analytical depth unprojection.
## Don't Forget
diff --git a/nodes/node-compositor/src/renderers/transform.test.ts b/nodes/node-compositor/src/renderers/transform.test.ts
index 620347e3..21e11190 100644
--- a/nodes/node-compositor/src/renderers/transform.test.ts
+++ b/nodes/node-compositor/src/renderers/transform.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, it } from "vitest";
import {
buildLayerMatrix,
+ layerRasterScale,
+ MAX_RASTER_SCALE,
type Matrix2D,
multiply,
resolveLayer2DPosition,
@@ -304,3 +306,39 @@ describe("resolveLayer2DPosition (2D parent translation inheritance)", () => {
expect(pos).toEqual({ x: 420, y: 330 });
});
});
+
+describe("layerRasterScale", () => {
+ const roomy = {
+ maxDimension: 8192,
+ maxPixels: 4 * 1920 * 1080,
+ effects: Number.POSITIVE_INFINITY,
+ };
+ const size = { width: 200, height: 100 };
+
+ it("keeps layout scale unscaled and shrunk", () => {
+ expect(layerRasterScale(1, size, roomy)).toBe(1);
+ expect(layerRasterScale(1 + 1e-9, size, roomy)).toBe(1);
+ expect(layerRasterScale(0.3, size, roomy)).toBe(1);
+ });
+
+ it("rounds a zoom up to the next quarter", () => {
+ expect(layerRasterScale(1.7, size, roomy)).toBe(1.75);
+ expect(layerRasterScale(1.75, size, roomy)).toBe(1.75);
+ expect(layerRasterScale(1.76, size, roomy)).toBe(2);
+ expect(layerRasterScale(4, size, roomy)).toBe(4);
+ });
+
+ it("stops at MAX_RASTER_SCALE", () => {
+ expect(layerRasterScale(12, size, roomy)).toBe(MAX_RASTER_SCALE);
+ });
+
+ it("stays inside the texture side, the pixel budget and the effects' limit, rounding down", () => {
+ // 3000 px wide: 8192 / 3000 = 2.73 → 2.5.
+ expect(layerRasterScale(4, { width: 3000, height: 100 }, roomy)).toBe(2.5);
+ // A full 1080p layer under a 4-canvas budget doubles at most.
+ expect(layerRasterScale(4, { width: 1920, height: 1080 }, roomy)).toBe(2);
+ expect(layerRasterScale(4, size, { ...roomy, effects: 1.6 })).toBe(1.5);
+ // Never below layout scale, whatever the limits.
+ expect(layerRasterScale(4, size, { ...roomy, effects: 0.5 })).toBe(1);
+ });
+});
diff --git a/nodes/node-compositor/src/renderers/transform.ts b/nodes/node-compositor/src/renderers/transform.ts
index 08875be4..3a6fd7aa 100644
--- a/nodes/node-compositor/src/renderers/transform.ts
+++ b/nodes/node-compositor/src/renderers/transform.ts
@@ -150,3 +150,33 @@ export function resolveLayer2DPosition(params: {
return transformPoint(pm as Matrix2D, localX, localY);
}
+
+/** Past this many pixels per layout px a scaled-up layer gains nothing visible. */
+export const MAX_RASTER_SCALE = 4;
+
+/**
+ * Pixels per layout px to rasterize a 2D layer at, so it stays sharp when its
+ * transform onto the canvas scales it up by `axisScale` (the transform's
+ * larger axis scale). Rounded up to a quarter, so an animated zoom reuses a
+ * few texture sizes instead of allocating new ones every frame; never below 1
+ * (a shrunk layer keeps its layout raster). Capped, rounded down to a quarter,
+ * by MAX_RASTER_SCALE, by `limits.maxDimension` (the GPU's texture side), by
+ * `limits.maxPixels` (a pixel budget for one texture) and by
+ * `limits.effects`, the highest scale the layer's effects keep their look at.
+ */
+export function layerRasterScale(
+ axisScale: number,
+ size: { width: number; height: number },
+ limits: { maxDimension: number; maxPixels: number; effects: number },
+): number {
+ const w = Math.max(1, size.width);
+ const h = Math.max(1, size.height);
+ const cap = Math.min(
+ MAX_RASTER_SCALE,
+ limits.maxDimension / Math.max(w, h),
+ Math.sqrt(limits.maxPixels / (w * h)),
+ limits.effects,
+ );
+ const wanted = Math.ceil(axisScale * 4 - 1e-6) / 4;
+ return Math.max(1, Math.min(wanted, Math.floor(cap * 4 + 1e-6) / 4));
+}
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 88200bde..08713c80 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -17,6 +17,7 @@ import {
type VirtualMediaData,
} from "@framefields/core";
import {
+ effectMaxPixelScale,
effectReach,
type NodeRenderProps,
resolveFrameNumber,
@@ -73,6 +74,7 @@ import {
sampleMorphWeights,
spansText,
srtLoader,
+ transformScale,
Vector3Math,
} from "@framefields/webgpu-renderers";
import { compileTimeline, seekTimeline } from "../shared/compiler.js";
@@ -81,6 +83,7 @@ import { shouldPaintContainerBackground } from "./container-bg.js";
import { compatibleMeshDraws } from "./mesh-instancing.js";
import {
buildLayerMatrix,
+ layerRasterScale,
resolveLayer2DPosition,
toDOMMatrix,
} from "./transform.js";
@@ -595,6 +598,36 @@ function effectsReach(effects: unknown[]): number | null {
return reach;
}
+/**
+ * The most pixels per layout px a leaf's effects keep their look at: the
+ * least any of them declares (`maxPixelScale`), 1 for one that doesn't.
+ * Relighting runs in the leaf itself, at any scale.
+ */
+function effectsMaxPixelScale(effects: unknown[]): number {
+ let limit = Number.POSITIVE_INFINITY;
+ for (const e of effects) {
+ const op = (
+ e && typeof (e as { toOperation?: unknown }).toOperation === "function"
+ ? (e as { toOperation: () => Record<string, unknown> }).toOperation()
+ : e
+ ) as Record<string, unknown> | null;
+ if (!op || typeof op !== "object" || op.op === "Relight3D") continue;
+ limit = Math.min(limit, effectMaxPixelScale(op));
+ }
+ return limit;
+}
+
+/**
+ * Media content that draws in its layer's own units, so it can be drawn
+ * under a raster scale: a source or a nested composition. Effect, crop and
+ * vision passes wrapped around a source draw at their container's size in
+ * their own pixel space instead.
+ */
+function drawsInLayerUnits(content: VirtualMediaData | undefined): boolean {
+ const op = content?.operation?.op;
+ return op === "source" || op === "Compositor";
+}
+
function quatFromEulerAngles(
rx: number,
ry: number,
@@ -752,6 +785,10 @@ async function applyLayerEffectsInRegion(
return { texture: out, view: out.createView() };
}
+/**
+ * Runs `effects` over `sourceTex` (`width`×`height` pixels, `pixelScale` of
+ * them per layout px) into a new texture of its size.
+ */
async function applyLayerEffects(
effects: unknown[],
sourceTex: GPUTexture,
@@ -767,6 +804,7 @@ async function applyLayerEffects(
fps: number,
isVideoMode: boolean,
layerId: string,
+ pixelScale = 1,
): Promise<{ texture: GPUTexture; view: GPUTextureView }> {
const remainingEffects = effects.filter((e: unknown) => {
if (!e || typeof e !== "object") return false;
@@ -844,6 +882,7 @@ async function applyLayerEffects(
...props,
containerWidth: width,
containerHeight: height,
+ pixelScale,
renderId: `${props.renderId}-${layerId}-fx`,
frame: shiftedFrame,
compositionFrame,
@@ -1791,6 +1830,26 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
return true;
};
+ // Pixels per layout px for a 2D layer's own texture (a leaf, a border)
+ // placed on the canvas by `matrix`: its scale there, within the GPU's
+ // texture side, a budget of four canvases of pixels, and `effects` (the
+ // most its effects keep their look at).
+ const rasterScaleOf = (
+ matrix: DOMMatrix,
+ width: number,
+ height: number,
+ effects = Number.POSITIVE_INFINITY,
+ ) =>
+ layerRasterScale(
+ transformScale(matrix),
+ { width, height },
+ {
+ maxDimension: ctx.device.limits.maxTextureDimension2D,
+ maxPixels: 4 * nativeWidth * nativeHeight,
+ effects,
+ },
+ );
+
const renderNodeTree = async (
vms: VirtualMediaData[],
initialTex: GPUTexture,
@@ -4128,6 +4187,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
lop.borderColor,
lop.strokeAlign ?? "inside",
[activeTex, targetTexture, ...excludes],
+ rasterScaleOf(layerMatrix, layerW, layerH),
)
: null;
if (paint || border) {
@@ -4241,6 +4301,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
lop.borderColor,
lop.strokeAlign ?? "inside",
[activeTex, targetTexture, ...excludes],
+ rasterScaleOf(layerMatrix, layerW, layerH),
)
: null;
if (border) {
@@ -4391,6 +4452,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
lop.borderColor,
lop.strokeAlign ?? "inside",
[activeGroupTex, ...groupExcludes],
+ rasterScaleOf(layerMatrix, layerW, layerH),
)
: null;
@@ -4649,8 +4711,71 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
layerW / 2,
layerH / 2,
);
- const texW = Math.ceil(layerW);
- const texH = Math.ceil(layerH);
+
+ // Temporal De-flickering & Optical Flow Warping
+ const leafDeflickerEffect = Array.isArray(lop.effects)
+ ? lop.effects.find(
+ (e: unknown) =>
+ (e as { op?: string })?.op === "TemporalDeflicker" ||
+ (e as { constructor?: { name?: string } })?.constructor?.name ===
+ "TemporalDeflicker",
+ )
+ : undefined;
+ const deflickerOpts =
+ target?.deflicker ?? lop.deflicker ?? leafDeflickerEffect;
+
+ // Screen-Space 3D Relighting
+ const leafRelightEffect = Array.isArray(lop.effects)
+ ? lop.effects.find(
+ (e: unknown) =>
+ (e as { op?: string })?.op === "Relight3D" ||
+ (e as { constructor?: { name?: string } })?.constructor?.name ===
+ "Relight3D",
+ )
+ : undefined;
+ const rawLeafRelight =
+ target?.relighting ??
+ lop.relighting ??
+ (typeof lop.relight === "object" ? lop.relight : undefined) ??
+ leafRelightEffect;
+ const relightOpts =
+ typeof rawLeafRelight === "object" && rawLeafRelight !== null
+ ? rawLeafRelight
+ : undefined;
+
+ // Directional velocity motion blur
+ const shutterAngle =
+ target?.motionBlurShutter ?? lop.motionBlurShutter ?? 0;
+
+ const hasEffects =
+ kind !== "media" &&
+ Array.isArray(lop.effects) &&
+ lop.effects.length > 0;
+
+ // A 2D leaf rasterizes at its scale on the canvas (`layerMatrix`), so
+ // text and edges an ancestor scales up (a camera push, a card at
+ // scale 2) are drawn at that size, not magnified from a layout-size
+ // raster. Content draws in layout units under `raster`; everything
+ // below that works in the texture's pixels scales with it. Layout
+ // scale stays for 3D leaves (their quad places them, not
+ // `layerMatrix`), deflickering (its history has one size), media
+ // wrapped in passes that draw in their own pixels, and effects that
+ // don't declare how far they scale.
+ const rasterScale =
+ isTrue3D ||
+ is3D ||
+ deflickerOpts ||
+ (kind === "media" && !drawsInLayerUnits(nodeVM.children?.[0]))
+ ? 1
+ : rasterScaleOf(
+ layerMatrix,
+ layerW,
+ layerH,
+ hasEffects ? effectsMaxPixelScale(lop.effects) : undefined,
+ );
+ const raster = new DOMMatrix([rasterScale, 0, 0, rasterScale, 0, 0]);
+ const texW = Math.ceil(layerW * rasterScale);
+ const texH = Math.ceil(layerH * rasterScale);
// Suspend any parent container scissors while rendering isolated offscreen localTex
const savedScissors = ctx.renderer.suspendScissors?.() ?? [];
@@ -4916,6 +5041,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const captureGlyphs = isTrue3D && kind === "text";
const rasterDrawsBefore = ctx.renderer.rasterDrawCount;
if (captureGlyphs) ctx.renderer.slugPipeline.beginCapture();
+ ctx.renderer.pushTransform(raster);
try {
await drawChild(
content,
@@ -4982,6 +5108,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
texH,
);
} finally {
+ ctx.renderer.popTransform();
if (captureGlyphs) {
glyphBatches = ctx.renderer.slugPipeline.endCapture();
}
@@ -5076,6 +5203,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const trimEnd = target?.trimEnd ?? lop.trimEnd ?? 1;
const trimOffset = target?.trimOffset ?? lop.trimOffset ?? 0;
+ ctx.renderer.pushTransform(raster);
ctx.renderer.drawShape(
shapePass,
shapeConfig,
@@ -5093,51 +5221,13 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
}
: undefined,
);
+ ctx.renderer.popTransform();
shapePass.end();
}
- // Temporal De-flickering & Optical Flow Warping
- const leafDeflickerEffect = Array.isArray(lop.effects)
- ? lop.effects.find(
- (e: unknown) =>
- (e as { op?: string })?.op === "TemporalDeflicker" ||
- (e as { constructor?: { name?: string } })?.constructor?.name ===
- "TemporalDeflicker",
- )
- : undefined;
- const deflickerOpts =
- target?.deflicker ?? lop.deflicker ?? leafDeflickerEffect;
-
- // Screen-Space 3D Relighting
- const leafRelightEffect = Array.isArray(lop.effects)
- ? lop.effects.find(
- (e: unknown) =>
- (e as { op?: string })?.op === "Relight3D" ||
- (e as { constructor?: { name?: string } })?.constructor?.name ===
- "Relight3D",
- )
- : undefined;
- const rawLeafRelight =
- target?.relighting ??
- lop.relighting ??
- (typeof lop.relight === "object" ? lop.relight : undefined) ??
- leafRelightEffect;
- const relightOpts =
- typeof rawLeafRelight === "object" && rawLeafRelight !== null
- ? rawLeafRelight
- : undefined;
-
- // Directional velocity motion blur
- const shutterAngle =
- target?.motionBlurShutter ?? lop.motionBlurShutter ?? 0;
-
// Effects work on the layer's pixels: glyphs held back for the 3D
// pass are drawn into its texture after all.
- const hasEffects =
- kind !== "media" &&
- Array.isArray(lop.effects) &&
- lop.effects.length > 0;
if (
glyphBatches &&
glyphBatches.length > 0 &&
@@ -5189,12 +5279,14 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
texH,
"load",
);
+ ctx.renderer.pushTransform(raster);
ctx.renderer.drawRect(
maskPass,
{ x: 0, y: 0, width: layerW, height: layerH },
{ r: 1, g: 1, b: 1, a: 1 },
br,
);
+ ctx.renderer.popTransform();
maskPass.end();
finalTex = ctx.renderer.composite(
@@ -5229,10 +5321,14 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
ctx.renderer.format ?? "rgba8unorm",
sampleCount3d,
);
+ // Lights and the surface are placed in layout px; the texture
+ // spans texW / rasterScale of them.
+ const extentW = texW / rasterScale;
+ const extentH = texH / rasterScale;
const activeLights = synthesizeRelightLights(
relightOpts as Record<string, unknown>,
sceneLights,
- { x: sampledX, y: sampledY, width: texW, height: texH },
+ { x: sampledX, y: sampledY, width: extentW, height: extentH },
compositionFrame,
fps ?? 24,
);
@@ -5255,8 +5351,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
normalTex,
lightsBuffer,
{
- viewportWidth: texW,
- viewportHeight: texH,
+ viewportWidth: extentW,
+ viewportHeight: extentH,
layerX: sampledX,
layerY: sampledY,
roughness: resolveFrameNumber(
@@ -5309,6 +5405,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
}
// Directional velocity motion blur (last: the shutter integrates the final look)
+ // The padding is in layout px; the texture holds rasterScale pixels each.
let blurPadX = 0;
let blurPadY = 0;
if (shutterAngle > 0 && fps && shiftedFrame !== undefined) {
@@ -5326,11 +5423,13 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
// to streak past their own bounds instead of smearing edge pixels.
if (!isTrue3D && !(is3D && quad3D)) {
const reach = shutterAngle / 360;
- blurPadX = Math.ceil(Math.abs(vx) * reach);
- blurPadY = Math.ceil(Math.abs(vy) * reach);
+ const padX = Math.ceil(Math.abs(vx) * rasterScale * reach);
+ const padY = Math.ceil(Math.abs(vy) * rasterScale * reach);
+ blurPadX = padX / rasterScale;
+ blurPadY = padY / rasterScale;
const paddedTex = ctx.renderer.getTemporaryTexture(
- texW + blurPadX * 2,
- texH + blurPadY * 2,
+ texW + padX * 2,
+ texH + padY * 2,
[finalTex, activeTex, targetTexture, ...excludes],
);
const padPass = ctx.renderer.beginFrame(
@@ -5344,20 +5443,21 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
ctx.renderer.drawTexture(
padPass,
finalTex,
- { x: blurPadX, y: blurPadY, width: texW, height: texH },
+ { x: padX, y: padY, width: texW, height: texH },
{ opacity: 1.0 },
);
padPass.end();
finalTex = paddedTex;
}
// ~1 tap per 2 px of streak so fast moves smear instead of ghosting.
- const streakPx = Math.hypot(vx, vy) * (shutterAngle / 360) * 2;
+ const streakPx =
+ Math.hypot(vx, vy) * rasterScale * (shutterAngle / 360) * 2;
const samples = Math.min(128, Math.max(16, Math.ceil(streakPx / 2)));
finalTex = ctx.renderer.applyMotionBlur(
encoder,
finalTex,
- vx,
- vy,
+ vx * rasterScale,
+ vy * rasterScale,
shutterAngle,
samples,
[activeTex, targetTexture, ...excludes],
@@ -5385,6 +5485,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
fps ?? 24,
isVideoMode,
lop.id ?? `leaf_${i}`,
+ rasterScale,
);
finalTex = postEffects.texture;
}
@@ -5408,6 +5509,7 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
lop.borderColor,
lop.strokeAlign ?? "inside",
borderExcludes,
+ rasterScale,
)
: null;
@@ -5492,7 +5594,10 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
],
width: layerW,
height: layerH,
- textureExtent: [layerW / texW, layerH / texH],
+ textureExtent: [
+ (layerW * rasterScale) / texW,
+ (layerH * rasterScale) / texH,
+ ],
rotation: [
target?.rotateX ?? lop.rotateX ?? 0,
target?.rotateY ?? lop.rotateY ?? 0,
@@ -5795,6 +5900,10 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
/** Pixels of room around a border texture for its anti-aliased edge. */
const BORDER_AA_MARGIN = 2;
+/**
+ * A `w`×`h` box's border as a texture, `rasterScale` pixels per layout px,
+ * and the rect it covers in layout px (around the box, at its origin).
+ */
function createBorderTexture(
ctx: RenderContextValue,
encoder: GPUCommandEncoder,
@@ -5805,6 +5914,7 @@ function createBorderTexture(
borderColor: string | Color,
strokeAlign: string,
excludeTextures: GPUTexture[],
+ rasterScale = 1,
): {
borderTex: GPUTexture;
ox: number;
@@ -5860,8 +5970,9 @@ function createBorderTexture(
// half a pixel outside it, and a rounded border touching the texture's
// edge would lose that fringe (flat spots, plain to see once scaled up).
const m = BORDER_AA_MARGIN;
- const borderTexW = Math.ceil(ow + 2 * m);
- const borderTexH = Math.ceil(oh + 2 * m);
+ const borderTexW = Math.ceil((ow + 2 * m) * rasterScale);
+ const borderTexH = Math.ceil((oh + 2 * m) * rasterScale);
+ const raster = new DOMMatrix([rasterScale, 0, 0, rasterScale, 0, 0]);
const outerTex = ctx.renderer.getTemporaryTexture(
borderTexW,
@@ -5888,12 +5999,14 @@ function createBorderTexture(
borderTexH,
"load",
);
+ ctx.renderer.pushTransform(raster);
ctx.renderer.drawRect(
outerDrawPass,
{ x: m, y: m, width: ow, height: oh },
borderColor,
outerRadius,
);
+ ctx.renderer.popTransform();
outerDrawPass.end();
const innerW = ow - 2 * borderWidth;
@@ -5924,12 +6037,14 @@ function createBorderTexture(
borderTexH,
"load",
);
+ ctx.renderer.pushTransform(raster);
ctx.renderer.drawRect(
innerDrawPass,
{ x: m + borderWidth, y: m + borderWidth, width: innerW, height: innerH },
{ r: 1, g: 1, b: 1, a: 1 },
innerRadius,
);
+ ctx.renderer.popTransform();
innerDrawPass.end();
const borderTex = ctx.renderer.composite(
@@ -5943,8 +6058,8 @@ function createBorderTexture(
borderTex,
ox: ox - m,
oy: oy - m,
- ow: borderTexW,
- oh: borderTexH,
+ ow: borderTexW / rasterScale,
+ oh: borderTexH / rasterScale,
};
}
@@ -5952,7 +6067,7 @@ function createBorderTexture(
borderTex: outerTex,
ox: ox - m,
oy: oy - m,
- ow: borderTexW,
- oh: borderTexH,
+ ow: borderTexW / rasterScale,
+ oh: borderTexH / rasterScale,
};
}
diff --git a/nodes/node-layer-style/src/renderers/reach.test.ts b/nodes/node-layer-style/src/renderers/reach.test.ts
index 3eb95560..d88313a3 100644
--- a/nodes/node-layer-style/src/renderers/reach.test.ts
+++ b/nodes/node-layer-style/src/renderers/reach.test.ts
@@ -1,6 +1,14 @@
-import { effectReach, registerWebGPURenderer } from "@framefields/node-sdk";
+import {
+ effectMaxPixelScale,
+ effectReach,
+ registerWebGPURenderer,
+} from "@framefields/node-sdk";
import { describe, expect, it } from "vitest";
-import { layerStyleReach, WebGPURenderer } from "./webgpu-renderer.js";
+import {
+ layerStyleMaxPixelScale,
+ layerStyleReach,
+ WebGPURenderer,
+} from "./webgpu-renderer.js";
const signal = <T>(value: T) => ({ _value: value, _subscribers: {} });
@@ -58,3 +66,81 @@ describe("effectReach", () => {
expect(effectReach({ op: "NoReach" })).toBeNull();
});
});
+
+describe("LayerStyle maxPixelScale", () => {
+ it("is unlimited when no style samples a kernel", () => {
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ colorOverlay: { enabled: true, color: "#ff0000" },
+ bevelEmboss: { enabled: true, size: 40 },
+ dropShadow: { enabled: false, size: 200 },
+ }),
+ ).toBe(Number.POSITIVE_INFINITY);
+ });
+
+ it("stops where a scaled kernel would pass the shader's cap", () => {
+ // Outer kernels stop at 24 px, inner ones at 16.
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ dropShadow: { enabled: true, distance: 40, size: 8 },
+ }),
+ ).toBe(3);
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ dropShadow: signal({ enabled: true, size: 4 }),
+ innerShadow: { enabled: true, size: 8 },
+ }),
+ ).toBe(2);
+ // A centred stroke reaches half its size each way.
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ stroke: { enabled: true, size: 12, position: "center" },
+ }),
+ ).toBe(4);
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ stroke: { enabled: true, size: 12, position: "outside" },
+ }),
+ ).toBe(2);
+ });
+
+ it("measures a style that leaves its size out at the renderer's default", () => {
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ outerGlow: { enabled: true },
+ }),
+ ).toBe(24 / 15);
+ });
+
+ it("is 1 when a size is driven by a connected signal", () => {
+ expect(
+ layerStyleMaxPixelScale({
+ op: "LayerStyle",
+ innerGlow: { enabled: true, size: 2 },
+ innerGlowSizeHandleId: "h1",
+ inputs: { h1: { connectionValid: true } },
+ }),
+ ).toBe(1);
+ });
+});
+
+describe("effectMaxPixelScale", () => {
+ it("asks the registered renderer, and is 1 without an answer", () => {
+ registerWebGPURenderer("LayerStyle", WebGPURenderer);
+ expect(
+ effectMaxPixelScale({
+ op: "LayerStyle",
+ dropShadow: { enabled: true, size: 6 },
+ }),
+ ).toBe(4);
+ expect(effectMaxPixelScale({ op: "SomeMirror" })).toBe(1);
+ registerWebGPURenderer("NoScale", async () => {});
+ expect(effectMaxPixelScale({ op: "NoScale" })).toBe(1);
+ });
+});
diff --git a/nodes/node-layer-style/src/renderers/webgpu-renderer.ts b/nodes/node-layer-style/src/renderers/webgpu-renderer.ts
index 6fc59c0f..af11a729 100644
--- a/nodes/node-layer-style/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-layer-style/src/renderers/webgpu-renderer.ts
@@ -1,5 +1,9 @@
/// <reference types="webgpu" />
-import type { EffectReach, WebGPUNodeRenderer } from "@framefields/node-sdk";
+import type {
+ EffectMaxPixelScale,
+ EffectReach,
+ WebGPUNodeRenderer,
+} from "@framefields/node-sdk";
import {
createFullscreenPipeline,
drawFullscreenPass,
@@ -7,6 +11,7 @@ import {
FULLSCREEN_QUAD_WGSL,
fragmentBindGroupLayout,
PREMULTIPLIED_BLEND,
+ pixelScale,
} from "@framefields/node-sdk/gpu";
import type { LayerStyleNodeConfig } from "../shared/config.js";
@@ -110,6 +115,8 @@ const STROKE_POS_MAP: Record<string, number> = {
/** Blur, glow and stroke kernels in the shader stop at this radius, px. */
const MAX_KERNEL = 24;
+/** The inner glow's and inner shadow's kernels stop sooner, px. */
+const MAX_INNER_KERNEL = 16;
const WGSL_LAYER_STYLE_SHADER = `
struct LayerStyleUniforms {
@@ -491,7 +498,7 @@ fn compositeLayer(dst: vec4<f32>, src: vec4<f32>, blendMode: u32) -> vec4<f32> {
var innerAccum = 0.0;
var innerWeight = 0.0;
let sigma = max(0.5, igSize * 0.4);
- let sampleRadius = min(i32(ceil(igSize)), 16);
+ let sampleRadius = min(i32(ceil(igSize)), ${MAX_INNER_KERNEL});
let stepVal = max(1, sampleRadius / 6);
for (var y = -sampleRadius; y <= sampleRadius; y += stepVal) {
@@ -529,7 +536,7 @@ fn compositeLayer(dst: vec4<f32>, src: vec4<f32>, blendMode: u32) -> vec4<f32> {
var isAccum = 0.0;
var isWeight = 0.0;
let sigma = max(0.5, isSize * 0.4);
- let sampleRadius = min(i32(ceil(isSize)), 16);
+ let sampleRadius = min(i32(ceil(isSize)), ${MAX_INNER_KERNEL});
let stepVal = max(1, sampleRadius / 6);
for (var y = -sampleRadius; y <= sampleRadius; y += stepVal) {
@@ -686,6 +693,9 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
const width = targetWidth;
const height = targetHeight;
+ // Sizes and distances are layout px; the target may hold more than one
+ // pixel per layout px.
+ const px = pixelScale(args);
const elapsedSeconds =
props.elapsedMs !== undefined
? props.elapsedMs / 1000
@@ -832,19 +842,16 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
(resolveField(op.dropShadowAngleHandleId, ds.angle ?? 120, 0, 360) *
Math.PI) /
180;
- const dsDist = resolveField(
- op.dropShadowDistanceHandleId,
- ds.distance ?? 10,
- 0,
- 500,
- );
+ const dsDist =
+ resolveField(op.dropShadowDistanceHandleId, ds.distance ?? 10, 0, 500) * px;
const dsSpread = resolveField(
op.dropShadowSpreadHandleId,
ds.spread ?? 0,
0,
100,
);
- const dsSize = resolveField(op.dropShadowSizeHandleId, ds.size ?? 10, 0, 250);
+ const dsSize =
+ resolveField(op.dropShadowSizeHandleId, ds.size ?? 10, 0, 250) * px;
const dsBlend = BLEND_MODE_MAP[ds.blendMode ?? "multiply"] ?? 1;
const isCol = hexToRgba(is.color ?? "#000000");
@@ -858,19 +865,16 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
(resolveField(op.innerShadowAngleHandleId, is.angle ?? 120, 0, 360) *
Math.PI) /
180;
- const isDist = resolveField(
- op.innerShadowDistanceHandleId,
- is.distance ?? 5,
- 0,
- 500,
- );
+ const isDist =
+ resolveField(op.innerShadowDistanceHandleId, is.distance ?? 5, 0, 500) * px;
const isChoke = resolveField(
op.innerShadowChokeHandleId,
is.choke ?? 0,
0,
100,
);
- const isSize = resolveField(op.innerShadowSizeHandleId, is.size ?? 5, 0, 250);
+ const isSize =
+ resolveField(op.innerShadowSizeHandleId, is.size ?? 5, 0, 250) * px;
const isBlend = BLEND_MODE_MAP[is.blendMode ?? "multiply"] ?? 1;
const ogCol = hexToRgba(og.color ?? "#ffffff");
@@ -880,7 +884,8 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
0,
1,
);
- const ogSize = resolveField(op.outerGlowSizeHandleId, og.size ?? 15, 0, 250);
+ const ogSize =
+ resolveField(op.outerGlowSizeHandleId, og.size ?? 15, 0, 250) * px;
const ogSpread = resolveField(
op.outerGlowSpreadHandleId,
og.spread ?? 0,
@@ -896,7 +901,8 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
0,
1,
);
- const igSize = resolveField(op.innerGlowSizeHandleId, ig.size ?? 15, 0, 250);
+ const igSize =
+ resolveField(op.innerGlowSizeHandleId, ig.size ?? 15, 0, 250) * px;
const igSpread = resolveField(
op.innerGlowSpreadHandleId,
ig.spread ?? 0,
@@ -906,7 +912,7 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
const igBlend = BLEND_MODE_MAP[ig.blendMode ?? "screen"] ?? 2;
const stCol = hexToRgba(st.color ?? "#ffffff");
- const stSize = resolveField(op.strokeSizeHandleId, st.size ?? 2, 0, 100);
+ const stSize = resolveField(op.strokeSizeHandleId, st.size ?? 2, 0, 100) * px;
const stPos = STROKE_POS_MAP[st.position ?? "outside"] ?? 0;
const stOpacity = resolveField(
op.strokeOpacityHandleId,
@@ -927,13 +933,10 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
1000,
);
const beDir = be.direction === "Down" ? -1.0 : 1.0;
- const beSize = resolveField(op.bevelEmbossSizeHandleId, be.size ?? 5, 0, 250);
- const beSoften = resolveField(
- op.bevelEmbossSoftenHandleId,
- be.soften ?? 0,
- 0,
- 50,
- );
+ const beSize =
+ resolveField(op.bevelEmbossSizeHandleId, be.size ?? 5, 0, 250) * px;
+ const beSoften =
+ resolveField(op.bevelEmbossSoftenHandleId, be.soften ?? 0, 0, 50) * px;
const beAngle =
(resolveField(op.bevelEmbossAngleHandleId, be.angle ?? 120, 0, 360) *
Math.PI) /
@@ -1100,6 +1103,27 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
drawTextureToTarget(args, outTex, op.opacity ?? 1.0);
};
+type StyleOperation = Record<string, unknown> & {
+ inputs?: Record<string, { connectionValid?: boolean } | undefined>;
+};
+
+interface StyleSettings {
+ enabled?: boolean;
+ distance?: number;
+ size?: number;
+ position?: string;
+}
+
+/** Whether `handle` names an input with a live connection driving a field. */
+const drivenBy = (op: StyleOperation, handle: unknown) =>
+ typeof handle === "string" && op.inputs?.[handle]?.connectionValid === true;
+
+/** One style's settings; a style may be a signal holding its value. */
+const styleOf = (v: unknown) =>
+ (v && typeof v === "object" && "_value" in v
+ ? (v as { _value: unknown })._value
+ : v) as StyleSettings | undefined;
+
/**
* How far a LayerStyle draws past its layer: the drop shadow's offset plus
* its blur, the outer glow, an outside or centred stroke. Unknown (null)
@@ -1108,34 +1132,18 @@ export const WebGPURenderer: WebGPUNodeRenderer = async (args) => {
* compositor running the style over the layer's region will clip it.
*/
export const layerStyleReach: EffectReach = (operation) => {
- const op = operation as Record<string, unknown> & {
- inputs?: Record<string, { connectionValid?: boolean } | undefined>;
- };
- const driven = (handle: unknown) =>
- typeof handle === "string" && op.inputs?.[handle]?.connectionValid === true;
+ const op = operation as StyleOperation;
if (
- driven(op.dropShadowDistanceHandleId) ||
- driven(op.dropShadowSizeHandleId) ||
- driven(op.outerGlowSizeHandleId) ||
- driven(op.strokeSizeHandleId)
+ drivenBy(op, op.dropShadowDistanceHandleId) ||
+ drivenBy(op, op.dropShadowSizeHandleId) ||
+ drivenBy(op, op.outerGlowSizeHandleId) ||
+ drivenBy(op, op.strokeSizeHandleId)
)
return null;
- // A style may be a signal holding its value.
- const style = (v: unknown) =>
- (v && typeof v === "object" && "_value" in v
- ? (v as { _value: unknown })._value
- : v) as
- | {
- enabled?: boolean;
- distance?: number;
- size?: number;
- position?: string;
- }
- | undefined;
const kernel = (size?: number) => Math.min(Math.ceil(size ?? 0), MAX_KERNEL);
- const ds = style(op.dropShadow);
- const og = style(op.outerGlow);
- const st = style(op.stroke);
+ const ds = styleOf(op.dropShadow);
+ const og = styleOf(op.outerGlow);
+ const st = styleOf(op.stroke);
let r = 0;
if (ds?.enabled) r = Math.max(r, (ds.distance ?? 0) + kernel(ds.size));
if (og?.enabled) r = Math.max(r, kernel(og.size));
@@ -1143,4 +1151,41 @@ export const layerStyleReach: EffectReach = (operation) => {
return Math.ceil(r) + 2;
};
+/**
+ * How many pixels per layout px a LayerStyle keeps its look at: its blur,
+ * glow and stroke kernels stop at MAX_KERNEL target pixels (the inner glow's
+ * and inner shadow's at MAX_INNER_KERNEL), so a size scaled past that would
+ * be cut short. 1 when a size is driven by a signal, known only at render
+ * time. Sizes left out are the renderer's defaults.
+ */
+export const layerStyleMaxPixelScale: EffectMaxPixelScale = (operation) => {
+ const op = operation as StyleOperation;
+ if (
+ drivenBy(op, op.dropShadowSizeHandleId) ||
+ drivenBy(op, op.innerShadowSizeHandleId) ||
+ drivenBy(op, op.outerGlowSizeHandleId) ||
+ drivenBy(op, op.innerGlowSizeHandleId) ||
+ drivenBy(op, op.strokeSizeHandleId)
+ )
+ return 1;
+ const st = styleOf(op.stroke);
+ // A centred stroke samples half its size each way.
+ const strokeReach = st?.position === "center" ? 2 * MAX_KERNEL : MAX_KERNEL;
+ const kernels: [StyleSettings | undefined, number, number][] = [
+ [styleOf(op.dropShadow), 10, MAX_KERNEL],
+ [styleOf(op.outerGlow), 15, MAX_KERNEL],
+ [styleOf(op.innerGlow), 15, MAX_INNER_KERNEL],
+ [styleOf(op.innerShadow), 5, MAX_INNER_KERNEL],
+ [st, 2, strokeReach],
+ ];
+ let limit = Number.POSITIVE_INFINITY;
+ for (const [style, fallback, cap] of kernels) {
+ if (!style?.enabled) continue;
+ const size = style.size ?? fallback;
+ if (size > 0) limit = Math.min(limit, cap / size);
+ }
+ return limit;
+};
+
WebGPURenderer.reach = layerStyleReach;
+WebGPURenderer.maxPixelScale = layerStyleMaxPixelScale;
diff --git a/packages/framefields/src/leaf-raster-scale.render.test.ts b/packages/framefields/src/leaf-raster-scale.render.test.ts
new file mode 100644
index 00000000..82ddf8c9
--- /dev/null
+++ b/packages/framefields/src/leaf-raster-scale.render.test.ts
@@ -0,0 +1,212 @@
+/**
+ * A 2D leaf (text, a shape, media) rasterizes at its scale on the canvas: one
+ * an ancestor scales up (a camera push, a card at scale 4) is as sharp as the
+ * same thing drawn at that size, not a magnified layout-size raster. At scale
+ * 1 and below it renders as it always has.
+ */
+import { Canvas, loadImage } from "skia-canvas";
+import { beforeAll, describe, expect, it } from "vitest";
+import { LayerStyle } from "./effects/index.js";
+import { Composition, FontManager, Layer } from "./index.js";
+
+beforeAll(async () => {
+ // No optical sizes: set at 10 px and scaled 4×, it is the same glyphs as at 40.
+ await FontManager.register("assets/fonts/JetBrainsMono.ttf");
+});
+
+type Node = ReturnType<typeof Layer.box>;
+
+/** Red channel of a frame holding `children`, by pixel. */
+async function render(width: number, height: number, children: Node[]) {
+ const comp = new Composition({
+ width,
+ height,
+ fps: 30,
+ durationFrames: 1,
+ backgroundColor: "#000000",
+ });
+ comp.add(Layer.box({ width, height, children }));
+ const img = await loadImage(await comp.renderFrame({ frame: 0 }));
+ 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).data;
+ return (x: number, y: number) => data[(y * img.width + x) * 4] as number;
+}
+
+/** `child` inside a box at (x, y) scaled `scale` from its top-left corner. */
+const scaledBy = (scale: number, x: number, y: number, child: Node) =>
+ Layer.box({
+ position: "absolute",
+ x,
+ y,
+ width: 100,
+ height: 40,
+ anchorX: 0,
+ anchorY: 0,
+ scale,
+ children: [child],
+ });
+
+/** Mean and largest difference between two w×h regions. */
+function compare(
+ at: (x: number, y: number) => number,
+ a: [number, number],
+ b: [number, number],
+ w: number,
+ h: number,
+) {
+ let sum = 0;
+ let max = 0;
+ for (let y = 0; y < h; y++)
+ for (let x = 0; x < w; x++) {
+ const d = Math.abs(at(a[0] + x, a[1] + y) - at(b[0] + x, b[1] + y));
+ sum += d;
+ max = Math.max(max, d);
+ }
+ return { mean: sum / (w * h), max };
+}
+
+const row = (
+ at: (x: number, y: number) => number,
+ y: number,
+ x0: number,
+ x1: number,
+) => Array.from({ length: x1 - x0 + 1 }, (_, i) => at(x0 + i, y));
+
+describe("leaf raster scale", () => {
+ it("an 8 px circle scaled 4× is the round 32 px circle, not a magnified blur", async () => {
+ const circle = (size: number) =>
+ Layer.shape("circle", {
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: size,
+ height: size,
+ fillColor: "#ffffff",
+ });
+ const at = await render(200, 80, [
+ scaledBy(4, 20, 20, circle(8)),
+ Layer.box({
+ position: "absolute",
+ x: 100,
+ y: 20,
+ width: 32,
+ height: 32,
+ children: [circle(32)],
+ }),
+ ]);
+ const diff = compare(at, [16, 16], [96, 16], 40, 40);
+ expect(diff.mean).toBeLessThan(0.5);
+ expect(diff.max).toBeLessThanOrEqual(8);
+ // Inside the bounding square, outside the circle: dark, not a corner.
+ expect(at(23, 23)).toBe(0);
+ expect(at(36, 36)).toBe(255);
+ });
+
+ it("10 px text scaled 4× is set like 40 px text", async () => {
+ const text = (fontSize: number) =>
+ Layer.text("Wave 42", {
+ position: "absolute",
+ x: 0,
+ y: 0,
+ fontFamily: "JetBrains Mono",
+ fontSize,
+ fill: "#ffffff",
+ });
+ const at = await render(240, 160, [
+ scaledBy(4, 10, 10, text(10)),
+ Layer.box({
+ position: "absolute",
+ x: 10,
+ y: 90,
+ width: 220,
+ height: 60,
+ children: [text(40)],
+ }),
+ ]);
+ const diff = compare(at, [0, 0], [0, 80], 240, 70);
+ expect(diff.mean).toBeLessThan(0.5);
+ expect(diff.max).toBeLessThanOrEqual(16);
+ // There is text to compare: solid strokes, not a soft smear.
+ const ink = row(at, 40, 10, 230).filter((v) => v > 230).length;
+ expect(ink).toBeGreaterThan(10);
+ });
+
+ it("a layer style scales with its layer: a 2× shadow is the shadow at twice the size", async () => {
+ const shadowed = (size: number, k: number) =>
+ Layer.shape("circle", {
+ position: "absolute",
+ x: 0,
+ y: 0,
+ width: size,
+ height: size,
+ fillColor: "#ffffff",
+ }).withEffect(
+ new LayerStyle({
+ dropShadow: {
+ enabled: true,
+ color: "#ff0000",
+ opacity: 1,
+ angle: 90,
+ distance: 3 * k,
+ size: 4 * k,
+ },
+ } as ConstructorParameters<typeof LayerStyle>[0]),
+ );
+ const at = await render(200, 100, [
+ scaledBy(2, 10, 10, shadowed(30, 1)),
+ Layer.box({
+ position: "absolute",
+ x: 110,
+ y: 10,
+ width: 60,
+ height: 60,
+ children: [shadowed(60, 2)],
+ }),
+ ]);
+ const diff = compare(at, [10, 10], [110, 10], 70, 70);
+ expect(diff.mean).toBeLessThan(0.5);
+ expect(diff.max).toBeLessThanOrEqual(8);
+ // The shadow shows past the circle's lower edge, inside the layer.
+ expect(at(20, 66)).toBeGreaterThan(100);
+ });
+
+ it("at scale 1 and below a leaf keeps its layout-size raster", async () => {
+ const at = await render(200, 100, [
+ Layer.shape("circle", {
+ position: "absolute",
+ x: 20,
+ y: 20,
+ width: 32,
+ height: 32,
+ fillColor: "#ffffff",
+ }),
+ Layer.box({
+ position: "absolute",
+ x: 100,
+ y: 20,
+ width: 64,
+ height: 64,
+ anchorX: 0,
+ anchorY: 0,
+ scale: 0.5,
+ children: [
+ Layer.shape("circle", {
+ width: 64,
+ height: 64,
+ fillColor: "#ffffff",
+ }),
+ ],
+ }),
+ ]);
+ // Edge coverage near the top of each circle, as rendered before leaves
+ // rasterized at their scale (a minified 64 px raster on the right).
+ const near = (actual: number[], expected: number[]) => {
+ for (const [i, v] of actual.entries())
+ expect(Math.abs(v - (expected[i] as number))).toBeLessThanOrEqual(2);
+ };
+ near(row(at, 22, 24, 30), [0, 18, 184, 255, 255, 255, 255]);
+ near(row(at, 22, 104, 110), [0, 0, 67, 214, 255, 255, 255]);
+ });
+});
diff --git a/packages/node-sdk/renderer/gpu.ts b/packages/node-sdk/renderer/gpu.ts
index 5a4143a8..4d2b8338 100644
--- a/packages/node-sdk/renderer/gpu.ts
+++ b/packages/node-sdk/renderer/gpu.ts
@@ -241,6 +241,15 @@ export function beginTargetPass(
return pass;
}
+/**
+ * Target pixels per layout pixel (`props.pixelScale`, 1 when unset). A
+ * renderer multiplies its pixel-unit parameters by it and declares
+ * `maxPixelScale`.
+ */
+export function pixelScale(args: WebGPUNodeRendererArgs): number {
+ return args.props.pixelScale ?? 1;
+}
+
/** Draws `texture` over the whole target at `opacity` (the node's output). */
export function drawTextureToTarget(
args: WebGPUNodeRendererArgs,
diff --git a/packages/node-sdk/renderer/index.ts b/packages/node-sdk/renderer/index.ts
index 2cfdaf40..021efd0d 100644
--- a/packages/node-sdk/renderer/index.ts
+++ b/packages/node-sdk/renderer/index.ts
@@ -25,6 +25,12 @@ export interface NodeRenderProps<
trimEndOverride?: number;
containerWidth: number;
containerHeight: number;
+ /**
+ * Target pixels per layout pixel, when a compositor runs an effect on a
+ * layer rasterized above layout size so it stays sharp scaled up; unset
+ * means 1. Only renderers that declare `maxPixelScale` get more than 1.
+ */
+ pixelScale?: number;
opacity?: number;
frame?: number;
compositionFrame?: number;
@@ -57,14 +63,31 @@ export interface NodeRenderProps<
*/
export type EffectReach = (operation: Record<string, unknown>) => number | null;
+/**
+ * How many target pixels per layout pixel (`props.pixelScale`) an effect can
+ * run at and still look as it does at layout size, for one of its operations:
+ * it reads its pixel-unit parameters (a blur radius, a shadow's distance) in
+ * layout px and multiplies them by `pixelScale`, up to its own kernel limits.
+ * `Infinity` when nothing in it is measured in pixels.
+ */
+export type EffectMaxPixelScale = (
+ operation: Record<string, unknown>,
+) => number;
+
/**
* A node's GPU renderer. An effect renderer may carry `reach`: a compositor
* then runs it over the layer's own region plus that margin instead of the
- * whole target. Without it the effect always gets the whole target.
+ * whole target. Without it the effect always gets the whole target. It may
+ * also carry `maxPixelScale`: a compositor may then rasterize a layer it
+ * styles above layout size (a layer scaled up stays sharp). Without it such a
+ * layer keeps its layout size.
*/
export type WebGPUNodeRenderer<
TOperation extends MediaOperation = MediaOperation,
-> = WebGPUNodeRenderFn<TOperation> & { reach?: EffectReach };
+> = WebGPUNodeRenderFn<TOperation> & {
+ reach?: EffectReach;
+ maxPixelScale?: EffectMaxPixelScale;
+};
type WebGPUNodeRenderFn<TOperation extends MediaOperation> = (args: {
ctx: RenderContextValue;
@@ -362,6 +385,18 @@ export function effectReach(operation: Record<string, unknown>): number | null {
return webgpuRegistry.get(op)?.reach?.(operation) ?? null;
}
+/**
+ * How far above layout resolution an operation's effect may run, from its
+ * registered renderer; 1 when it doesn't say.
+ */
+export function effectMaxPixelScale(
+ operation: Record<string, unknown>,
+): number {
+ const op = operation.op;
+ if (typeof op !== "string") return 1;
+ return webgpuRegistry.get(op)?.maxPixelScale?.(operation) ?? 1;
+}
+
export type { WebGPUNodeRendererArgs } from "./gpu.js";
export interface TextureSourceOp {
diff --git a/packages/webgpu-renderers/src/nodes/svg.test.ts b/packages/webgpu-renderers/src/nodes/svg.test.ts
index 392cc4a1..eecd60ab 100644
--- a/packages/webgpu-renderers/src/nodes/svg.test.ts
+++ b/packages/webgpu-renderers/src/nodes/svg.test.ts
@@ -1,3 +1,4 @@
+import { renderAsync } from "@resvg/resvg-js";
import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import {
createMockDevice,
@@ -31,6 +32,7 @@ describe("SVG Node", () => {
let mockDevice: any;
let mockPass: any;
let mockCtx: any;
+ let transform: DOMMatrix;
beforeEach(() => {
vi.clearAllMocks();
@@ -38,11 +40,13 @@ describe("SVG Node", () => {
(svgLoader as any).cache.clear();
mockDevice = createMockDevice();
mockPass = createMockRenderPassEncoder();
+ transform = new DOMMatrix();
mockCtx = {
device: mockDevice,
renderer: {
drawTexture: vi.fn(),
+ getCurrentTransform: () => transform,
},
};
@@ -162,5 +166,24 @@ describe("SVG Node", () => {
expect(mockDevice.queue.copyExternalImageToTexture).toHaveBeenCalled();
expect(mockCtx.renderer.drawTexture).toHaveBeenCalled();
});
+
+ it("rasterizes at the size the transform draws it on the target", async () => {
+ transform = new DOMMatrix().scale(2.5);
+ await drawSvgNode(mockCtx, mockPass, {
+ src: "scaled.svg",
+ dstRect: { x: 0, y: 0, width: 100, height: 40 },
+ isHeadless: true,
+ });
+
+ expect(renderAsync).toHaveBeenCalledWith("<svg></svg>", {
+ fitTo: { mode: "width", value: 250 },
+ });
+ expect(mockCtx.renderer.drawTexture).toHaveBeenCalledWith(
+ mockPass,
+ expect.anything(),
+ { x: 0, y: 0, width: 100, height: 40 },
+ expect.anything(),
+ );
+ });
});
});
diff --git a/packages/webgpu-renderers/src/nodes/svg.ts b/packages/webgpu-renderers/src/nodes/svg.ts
index feafda65..8242b2d6 100644
--- a/packages/webgpu-renderers/src/nodes/svg.ts
+++ b/packages/webgpu-renderers/src/nodes/svg.ts
@@ -1,4 +1,5 @@
import type { RenderContextValue } from "../render-context.js";
+import { transformScale } from "../renderer2d/transform-stack.js";
import { textureCache } from "../texture-cache.js";
import { createImageTexture } from "./image-texture.js";
import type { SVGNodeProps } from "./types.js";
@@ -103,8 +104,12 @@ export async function drawSvgNode(
pass: GPURenderPassEncoder,
props: SVGNodeProps,
): Promise<void> {
- const resolvedWidth = Math.max(1, Math.ceil(props.dstRect.width));
- const resolvedHeight = Math.max(1, Math.ceil(props.dstRect.height));
+ // Rasterize at the size the drawn rect covers on the target, so a scaled-up
+ // SVG resamples nothing.
+ const m = ctx.renderer.getCurrentTransform();
+ const k = transformScale(props.matrix ? m.multiply(props.matrix) : m);
+ const resolvedWidth = Math.max(1, Math.ceil(props.dstRect.width * k));
+ const resolvedHeight = Math.max(1, Math.ceil(props.dstRect.height * k));
const cacheKey = `${props.src}-${resolvedWidth}-${resolvedHeight}`;
let tex = textureCache.acquire(cacheKey);
diff --git a/packages/webgpu-renderers/src/renderer2d/index.ts b/packages/webgpu-renderers/src/renderer2d/index.ts
index 944c9b9a..cf353a40 100644
--- a/packages/webgpu-renderers/src/renderer2d/index.ts
+++ b/packages/webgpu-renderers/src/renderer2d/index.ts
@@ -16,11 +16,12 @@ import {
ShapeFillPipeline,
} from "./shape-fill-pipeline.js";
import { SolidPipeline } from "./solid-pipeline.js";
-import { TransformStack } from "./transform-stack.js";
+import { TransformStack, transformScale } from "./transform-stack.js";
export * from "./path-geometry.js";
export type { PathDrawOpts } from "./path-pipeline.js";
export * from "./shape-fill-pipeline.js";
+export { transformScale } from "./transform-stack.js";
export interface Rect {
x: number;
@@ -343,7 +344,8 @@ export class Renderer2D {
if (tris.length > 0) {
this.drawShapeFill(pass, tris, fill, bounds, opts);
// AA the triangulated edge with a hairline in the fill colour — solid fills
- // only, since a gradient has no single edge colour.
+ // only, since a gradient has no single edge colour. A hairline is one
+ // target pixel wide, whatever the transform scales local units by.
if (
(!stroke || !stroke.width || stroke.width <= 0) &&
(fill.type ?? "solid") === "solid" &&
@@ -351,7 +353,11 @@ export class Renderer2D {
) {
const svgPath = buildShapeSvgPath(config);
if (svgPath) {
- this.drawPath(pass, svgPath, fill.color, 1.0, {
+ const m = this.transformStack.getCurrent();
+ const hairline =
+ 1 /
+ transformScale(opts?.transform ? m.multiply(opts.transform) : m);
+ this.drawPath(pass, svgPath, fill.color, hairline, {
...opts,
strokeLineCap: "round",
});
diff --git a/packages/webgpu-renderers/src/renderer2d/transform-stack.test.ts b/packages/webgpu-renderers/src/renderer2d/transform-stack.test.ts
index 57b11ab9..60cbf936 100644
--- a/packages/webgpu-renderers/src/renderer2d/transform-stack.test.ts
+++ b/packages/webgpu-renderers/src/renderer2d/transform-stack.test.ts
@@ -1,6 +1,6 @@
import { beforeAll, beforeEach, describe, expect, it } from "vitest";
import { ensureDOMGlobals } from "./test-helpers.js";
-import { TransformStack } from "./transform-stack.js";
+import { TransformStack, transformScale } from "./transform-stack.js";
describe("TransformStack", () => {
beforeAll(() => {
@@ -115,3 +115,21 @@ describe("TransformStack", () => {
expect(current.e).toBe(0);
});
});
+
+describe("transformScale", () => {
+ beforeAll(() => {
+ ensureDOMGlobals();
+ });
+
+ it("is 1 for the identity and for a translation", () => {
+ expect(transformScale(new DOMMatrix())).toBe(1);
+ expect(transformScale(new DOMMatrix().translate(40, -7))).toBe(1);
+ });
+
+ it("is the larger axis scale, whatever the rotation", () => {
+ expect(transformScale(new DOMMatrix().scale(3, 1.5))).toBe(3);
+ expect(
+ transformScale(new DOMMatrix().rotate(37).scale(1.5, 2.5)),
+ ).toBeCloseTo(2.5, 12);
+ });
+});
diff --git a/packages/webgpu-renderers/src/renderer2d/transform-stack.ts b/packages/webgpu-renderers/src/renderer2d/transform-stack.ts
index 6099d83e..bf3e0cc9 100644
--- a/packages/webgpu-renderers/src/renderer2d/transform-stack.ts
+++ b/packages/webgpu-renderers/src/renderer2d/transform-stack.ts
@@ -1,3 +1,17 @@
+/**
+ * Target pixels per local unit along the axis `m` stretches most: what a
+ * raster drawn under `m` needs per unit to stay sharp, and what one target
+ * pixel is in local units (its inverse).
+ */
+export function transformScale(m: {
+ a: number;
+ b: number;
+ c: number;
+ d: number;
+}): number {
+ return Math.max(Math.hypot(m.a, m.b), Math.hypot(m.c, m.d));
+}
+
export class TransformStack {
private stack: DOMMatrix[] = [new DOMMatrix()];
diff --git a/packages/webgpu-renderers/src/shaders/slug.ts b/packages/webgpu-renderers/src/shaders/slug.ts
index 1188ad48..cc0b83d5 100644
--- a/packages/webgpu-renderers/src/shaders/slug.ts
+++ b/packages/webgpu-renderers/src/shaders/slug.ts
@@ -137,6 +137,8 @@ fn sampleSlugCoverage(sampleUV: vec2<f32>, g: SlugGlyph, pixelsPerEm: vec2<f32>)
// pixel footprint in glyph uv, |d/dx| + |d/dy| (fwidth): the caller takes it in
// uniform control flow. On a turned or foreshortened glyph it is wider than one
// pixel along an axis, so that axis gets the soft ramp a box filter gives.
+// A blur of blurAmount px averages coverage over a grid reaching 0.3 of it
+// each way, blurTaps taps per side past the centre.
fn shadeSlugGlyph(
uv: vec2<f32>,
fw: vec2<f32>,
@@ -145,6 +147,7 @@ fn shadeSlugGlyph(
color: vec4<f32>,
opacity: f32,
blurAmount: f32,
+ blurTaps: f32,
chromaticShift: f32,
dissolveProgress: f32,
) -> vec4<f32> {
@@ -177,14 +180,15 @@ fn shadeSlugGlyph(
var slugAlpha = 0.0;
if (blurAmount > 0.01) {
- let step = fw * blurAmount * 0.3;
- for (var y_offset = -1.0; y_offset <= 1.0; y_offset = y_offset + 1.0) {
- for (var x_offset = -1.0; x_offset <= 1.0; x_offset = x_offset + 1.0) {
+ let step = fw * blurAmount * 0.3 / blurTaps;
+ for (var y_offset = -blurTaps; y_offset <= blurTaps; y_offset = y_offset + 1.0) {
+ for (var x_offset = -blurTaps; x_offset <= blurTaps; x_offset = x_offset + 1.0) {
let offset = vec2<f32>(x_offset, y_offset) * step;
slugAlpha = slugAlpha + sampleSlugCoverage(uv + offset, g, pixelsPerEm);
}
}
- slugAlpha = slugAlpha / 9.0;
+ let side = 2.0 * blurTaps + 1.0;
+ slugAlpha = slugAlpha / (side * side);
} else {
slugAlpha = sampleSlugCoverage(uv, g, pixelsPerEm);
}
@@ -221,6 +225,7 @@ struct VSOut {
@location(7) @interpolate(flat) chromaticShift : f32,
@location(8) @interpolate(flat) dissolveProgress : f32,
@location(9) @interpolate(flat) vfxParam : f32,
+ @location(10) @interpolate(flat) blurTaps : f32,
};
var<private> pos : array<vec2<f32>, 6> = array<vec2<f32>, 6>(
@@ -254,7 +259,11 @@ var<private> pos : array<vec2<f32>, 6> = array<vec2<f32>, 6>(
let transform2 = mat2x2<f32>(u.transformCol0.xy, u.transformCol1.xy);
let pixelsPerUnit = sqrt(max(abs(determinant(transform2)), 1e-8));
let halfSize = max(abs(aScaleBias.xy * scale_mult), vec2<f32>(1e-4));
- let grow = vec2<f32>(1.0) + (1.0 / pixelsPerUnit) / halfSize;
+ // A blurred glyph keeps a unit around it however many pixels a unit
+ // spans: its blur spills that far at one pixel per unit.
+ let blurred = aExtraParams.x > 0.01;
+ let dilation = select(1.0, max(1.0, pixelsPerUnit), blurred) / pixelsPerUnit;
+ let grow = vec2<f32>(1.0) + dilation / halfSize;
let uv = vec2<f32>(
quad_pos.x * grow.x * 0.5 + 0.5,
1.0 - (quad_pos.y * grow.y * 0.5 + 0.5),
@@ -288,7 +297,11 @@ var<private> pos : array<vec2<f32>, 6> = array<vec2<f32>, 6>(
out.bandMax = vec2<u32>(aBandMaxTexCoords.xy);
out.bandsTexCoords = vec2<u32>(aBandMaxTexCoords.zw);
out.color = aColor;
- out.blurAmount = aExtraParams.x;
+ // Blur is in local units, like every other length here; the fragment
+ // stage spreads its taps in pixels, as far apart as at one pixel per
+ // unit (more of them as a unit spans more pixels, up to 4).
+ out.blurAmount = aExtraParams.x * pixelsPerUnit;
+ out.blurTaps = clamp(ceil(pixelsPerUnit - 1e-3), 1.0, 4.0);
out.chromaticShift = aExtraParams.y;
out.dissolveProgress = aExtraParams.z;
out.vfxParam = aExtraParams.w;
@@ -307,6 +320,7 @@ var<private> pos : array<vec2<f32>, 6> = array<vec2<f32>, 6>(
in.color,
u.params.x,
in.blurAmount,
+ in.blurTaps,
in.chromaticShift,
in.dissolveProgress,
);
diff --git a/packages/webgpu-renderers/src/shaders/slug3d.ts b/packages/webgpu-renderers/src/shaders/slug3d.ts
index 7a50b80c..0a5f5993 100644
--- a/packages/webgpu-renderers/src/shaders/slug3d.ts
+++ b/packages/webgpu-renderers/src/shaders/slug3d.ts
@@ -144,6 +144,7 @@ fn shadeText(in : VSOut, fw : vec2<f32>) -> TextFragment {
in.color,
model.params.x,
in.fx.x,
+ 1.0,
in.fx.y,
in.fx.z,
);
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 819e3187..79b0c5ce 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -556,3 +556,4 @@ Layer.vfx({ effectType: "Aurora", width: W, height: H, colorStart: "#2bff88", co
9. **Lint before rendering:** `comp.lint()` lists colors/gradients that would draw transparent, low-contrast text, off-canvas layers, shadow settings that do nothing and `roughness`/`metallic` without an environment. `renderVideo({ qa: true })` includes these findings.
10. **Lottie vs. Image Layers:** Use `Layer.lottie("file.json" | "file.lottie", { width, height, fit })` for Lottie vector animations. Never pass `.json` or `.lottie` to `Layer.image()`, which only decodes raster formats and throws/warns if given a vector animation.
11. **AI-generated media are assets, not build steps:** Images, clips, music or voice made with `ai` (from `framefields`) are generated once by a separate script into `assets/generated/` and loaded like any other file. Never call `ai` from `buildFilm()` or a scene function: it would spend money and change the film on every render, preview and test. The `framefields` skill (section 6) covers the key, the script and the model catalog.
+12. **Zooming into flat layers stays sharp:** text, shapes, images and SVGs rasterize at their scale on the canvas (up to 4×), so a camera push or a parent at `scale: 2` keeps glyphs and edges crisp. A leaf keeps its layout-size raster, and softens when magnified, if it is 3D or deflickered, is media with `effects`/`crop`, or carries an effect other than `LayerStyle` or a Gaussian/box `Blur`.