Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance Redraw example with resolution handling

konstantin-paulusc55b03d43439
diff --git a/examples/11-redraw.tsx b/examples/11-redraw.tsx
index 774ab26b..4800560c 100644
--- a/examples/11-redraw.tsx
+++ b/examples/11-redraw.tsx
@@ -37,10 +37,17 @@
* end={period}). Period, stroke width, palette speed, and the background are
* `@inspect` variables (see 09-inspect-variables.tsx): sidebar controls whose
* reads in the draw closure are reactive, so moving one re-records the frame.
+ *
+ * The bitmap adapts to the output through `useResolution` (see
+ * reference/jsx/lifecycle.md): the display's pixel ratio live, the export
+ * scale offline. The surface bitmap is oversized by the factor and the
+ * recording draws in composition pixels through canvas.scale(k) — redraw's
+ * own dpr pattern — so the stroke stays sharp at any export resolution
+ * instead of upscaling a composition-size bitmap.
*/
import { createEffect, createSignal, onCleanup, onMount } from "solid-js";
-import { useTicker } from "@diffusionstudio/jsx";
+import { useResolution, useTicker } from "@diffusionstudio/jsx";
import {
Color,
Paint,
@@ -113,11 +120,12 @@ const background = "#ffffff";
type Gpu = {
destroy: () => void;
- draw: (timeMs: number) => void;
+ draw: (timeMs: number, k: number) => void;
};
export default function RedrawHello() {
const { time, hold } = useTicker();
+ const resolution = useResolution();
const [gpu, setGpu] = createSignal<Gpu>();
let surfaceRef: SceneNode | undefined;
@@ -139,27 +147,42 @@ export default function RedrawHello() {
alphaMode: "premultiplied",
});
- // Declare the vocabulary and bind a long-lived canvas to the surface.
- // drawPath records one command per segment group per tile; the stroke
- // crosses itself, so give headroom over the default 32.
+ // Declare the vocabulary. drawPath records one command per segment
+ // group per tile; the stroke crosses itself, so give headroom over the
+ // default 32.
const lib = createLibrary(device, [PathGradient, HelloStroke], {
maxCommandsPerTile: 64,
});
- const canvas = lib.makeCanvas(context.getCurrentTexture());
- // The surface canvas is sized to the element's box in composition pixels.
+ // The composition-pixel box: the bitmap is oversized from it by the
+ // resolution factor, and the recording draws in composition pixels
+ // through canvas.scale(k) — the redraw docs' dpr pattern.
const { width, height } = el;
const pathGeo = fitPath(
helloPath,
capWidth(deflate({ width, height }, 30), 800),
);
+ // The canvas binds to the swapchain texture's size, so a bitmap resize
+ // (the export scale arriving, a pixel-ratio change) re-makes it.
+ let canvas = lib.makeCanvas(context.getCurrentTexture());
+ let bitmapK = 1;
+
setGpu({
destroy: () => {
lib.dispose();
device.destroy();
},
- draw: (timeMs) => {
+ draw: (timeMs, k) => {
+ if (k !== bitmapK) {
+ bitmapK = k;
+ el.width = Math.round(width * k);
+ el.height = Math.round(height * k);
+ canvas = lib.makeCanvas(context.getCurrentTexture());
+ }
+ // Draw in composition pixels; the scale maps them to the bitmap.
+ // render() resets the recorder, so it is re-applied every frame.
+ canvas.scale(k);
// The inspect reads live here, so moving a control re-records.
canvas.fill(new Paint().setColor(background));
const t = boomerang(timeMs, period * 1000);
@@ -171,7 +194,7 @@ export default function RedrawHello() {
canvas.drawPath(pathGeo.segment(0, progress), paint);
}
// The swapchain texture is new every frame, but its size and format
- // stay the same; hand the current one to render().
+ // stay the same between resizes; hand the current one to render().
canvas.render(context.getCurrentTexture());
},
});
@@ -183,8 +206,9 @@ export default function RedrawHello() {
createEffect(() => {
const g = gpu();
const t = time();
+ const k = resolution();
if (!g) return;
- g.draw(t * 1000);
+ g.draw(t * 1000, k);
});
onCleanup(() => gpu()?.destroy());
diff --git a/examples/README.md b/examples/README.md
index ff0fbde2..5eb0fb02 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -22,7 +22,7 @@ dapi open ~/Projects/basics
| [08-shader-paint.tsx](08-shader-paint.tsx) | `<shaderPaint>` post-processing a `<video>`: WGSL chromatic aberration + vignette, uniforms patchable live |
| [09-inspect-variables.tsx](09-inspect-variables.tsx) | `@inspect` variables: annotated top-level consts becoming sidebar controls, values written back into the source |
| [10-typegpu.tsx](10-typegpu.tsx) | TypeGPU on a `<surface>`: shaders written in TypeScript (`'use gpu'`), compiled through the project's own [babel config](../reference/jsx/module.md#compile-time-plugins-babel-config) |
-| [11-redraw.tsx](11-redraw.tsx) | [Redraw](https://redraw.dev) on a `<surface>`: the docs' Hello World write-on stroke, a vendored-tarball package driven by composition time; the surface spans one animation cycle and `@inspect` variables tune it |
+| [11-redraw.tsx](11-redraw.tsx) | [Redraw](https://redraw.dev) on a `<surface>`: the docs' Hello World write-on stroke, a vendored-tarball package driven by composition time; the surface spans one animation cycle, `@inspect` variables tune it, and `useResolution` keeps it sharp at any export size |
Requirements: `02-genai.tsx` consumes generation credits (results are cached per session);
`01-basics.tsx`, `06-three.tsx`, and `08-shader-paint.tsx` fetch remote media.
diff --git a/packages/jsx/src/hooks.ts b/packages/jsx/src/hooks.ts
index 6933e8ba..f63b98ad 100644
--- a/packages/jsx/src/hooks.ts
+++ b/packages/jsx/src/hooks.ts
@@ -46,3 +46,19 @@ function hostOnly(name: string): never {
export function useTicker(): Ticker {
return hostOnly("useTicker");
}
+
+/**
+ * Subscribes to the host's rasterization density: how many device pixels one
+ * composition pixel is drawn with, camera zoom excluded. `1` where nothing
+ * scales, the display's pixel ratio in the live editor, and the export's
+ * resolution factor while a scene encodes above (or below) its native size.
+ * What a `<surface>` reads to size its bitmap so hand-drawn pixels stay
+ * sharp at any output size.
+ *
+ * Reactive, not a constant: an offline mount starts at `1` and learns the
+ * real factor before the first frame is sampled, so read it inside the
+ * effect that sizes and draws rather than once at mount.
+ */
+export function useResolution(): Accessor<number> {
+ return hostOnly("useResolution");
+}
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index f514a0d0..8e2a15d3 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -43,7 +43,7 @@ export {
parseSource,
} from "./source";
export type { CompositionTag, PropValue } from "./source";
-export { useTicker } from "./hooks";
+export { useResolution, useTicker } from "./hooks";
export type { Ticker } from "./hooks";
export { INSPECT_TAG, INSPECT_TYPES, __inspect } from "./inspect";
export type { InspectDeclaration, InspectType, InspectValue } from "./inspect";
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 859353b1..053c41ce 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -386,6 +386,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
};
root.add(Host);
root.set(Host, this.stage);
+ this.resolutionSignal[1](world.get(RenderSurface)?.resolution ?? 1);
}
/**
@@ -1684,6 +1685,17 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
return this.ticker[0]();
}
+ // The rasterization density behind `useResolution`: device pixels per
+ // composition pixel, camera zoom excluded — the display's pixel ratio in
+ // the live editor, the export scale offline. Read into a signal alongside
+ // the ticker, so an encoder that learns its scale only after the mount
+ // still propagates it before the first frame is sampled.
+ private readonly resolutionSignal = createSignal(1);
+
+ public resolution(): number {
+ return this.resolutionSignal[0]();
+ }
+
/**
* The barrier behind `useTicker().hold`: a project's own async work, put
* where the frames in flight wait for it — the same list the decoders push
@@ -1729,6 +1741,7 @@ export class RuntimeDocument implements ProjectDocument<SceneNode> {
const time = computed?.localTimeInSeconds ?? 0;
const delta = this.lastTickTime === null ? 0 : time - this.lastTickTime;
this.lastTickTime = time;
+ this.resolutionSignal[1](this.world.get(RenderSurface)?.resolution ?? 1);
this.ticker[1]({
time,
frame: computed?.localTime ?? 0,
diff --git a/packages/reconciler/src/host.ts b/packages/reconciler/src/host.ts
index 87d210fd..8ee18d6a 100644
--- a/packages/reconciler/src/host.ts
+++ b/packages/reconciler/src/host.ts
@@ -41,5 +41,6 @@ export interface ProjectDocument<N = unknown> {
getNextSibling(node: N): N | undefined;
tick?(): ProjectTick;
hold?(work: Promise<unknown>): void;
+ resolution?(): number;
applyRef?(node: N, ref: (target: unknown) => void): void;
}
diff --git a/packages/reconciler/src/renderer.ts b/packages/reconciler/src/renderer.ts
index 3e6ae620..28a7cc13 100644
--- a/packages/reconciler/src/renderer.ts
+++ b/packages/reconciler/src/renderer.ts
@@ -5,7 +5,7 @@
import { createContext, createMemo, useContext } from "solid-js";
import { createRenderer } from "solid-js/universal";
-import type { JSX } from "solid-js";
+import type { Accessor, JSX } from "solid-js";
import type { Ticker } from "@diffusionstudio/jsx";
import type { ProjectDocument } from "./host";
@@ -113,6 +113,18 @@ export function useTicker(): Ticker {
};
}
+/**
+ * The live `useResolution` — the host's rasterization density as a memo,
+ * a constant 1 where the host reports none: a project reading it in a
+ * document that never scales is not an error, everything there is drawn
+ * pixel for pixel.
+ */
+export function useResolution(): Accessor<number> {
+ const document = doc();
+ const read = document.resolution?.bind(document);
+ return createMemo(() => read?.() ?? 1);
+}
+
/**
* Runs `fn` with `document` as the one the static runtime exports write into.
* Anything creating elements outside a project render — a host inserting
diff --git a/packages/reconciler/src/runtime.ts b/packages/reconciler/src/runtime.ts
index f8315148..e8366a1c 100644
--- a/packages/reconciler/src/runtime.ts
+++ b/packages/reconciler/src/runtime.ts
@@ -34,6 +34,7 @@ import {
setProp,
spread,
use,
+ useResolution,
useTicker,
} from './renderer';
@@ -52,6 +53,7 @@ export const JSX_RUNTIME = {
setProp,
mergeProps,
use,
+ useResolution,
useTicker,
__inspect,
};
diff --git a/reference/jsx/README.md b/reference/jsx/README.md
index 3bb590fc..fc4887dd 100644
--- a/reference/jsx/README.md
+++ b/reference/jsx/README.md
@@ -51,7 +51,7 @@ export default function Project() {
| [captions.md](./captions.md) | `<captions>` and style presets |
| [generate.md](./generate.md) | Declarative AI asset generation (`generate.*`) |
| [variables.md](./variables.md) | `@inspect` variables: annotated consts as live inspector controls (number, color, text, font, boolean, select) |
-| [lifecycle.md](./lifecycle.md) | Mount lifecycle: always live, persisted + re-executed, `useTicker` |
+| [lifecycle.md](./lifecycle.md) | Mount lifecycle: always live, persisted + re-executed, `useTicker`, `useResolution` |
| [errors.md](./errors.md) | Where each pipeline stage fails and with what effect |
## Pipeline
diff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.md
index 02154e09..0c59828b 100644
--- a/reference/jsx/lifecycle.md
+++ b/reference/jsx/lifecycle.md
@@ -50,6 +50,26 @@ The values respect play, pause, scrubbing, looping, and playback speed, which wa
`useTicker` is host-bound: it only works inside a mounted project, and throws with a message saying so anywhere else.
+## `useResolution`
+
+The host's rasterization density, as one reactive accessor: how many device pixels one composition pixel is drawn with, camera zoom excluded.
+
+```tsx
+import { useResolution } from "@diffusionstudio/jsx";
+
+const resolution = useResolution();
+```
+
+| Context | Value |
+| ------- | ----- |
+| Live editor | The display's pixel ratio (2 on a retina screen) |
+| Export | The `resolution` setting's scale — 2 when a 960×540 scene encodes at 1080p |
+| Capture | The capture's scale, the same way |
+
+Vector content (shapes, text, gradients) rasterizes through this scale automatically and never needs it. It exists for **bitmaps a project draws itself** — a [`<surface>`](./surface-paint.md) whose canvas would otherwise be stretched from composition size into a larger output. Multiply the bitmap size by `resolution()` and draw at that density, and the sampled pixels stay sharp at any output size (see [surface-paint.md](./surface-paint.md#adapting-to-the-output-resolution)).
+
+It is an accessor, not a constant: an export mounts the module before it configures its scale, so the value starts at `1` and moves to the real factor before the first frame is sampled. Read it inside the effect that sizes and draws — a read at mount sees the initial value and never the correction. Like `useTicker` it is host-bound and throws outside a mounted project.
+
## `hold`
An export or a capture does not photograph the live mount — it **mounts the module again**, in a world of its own, and starts sampling as soon as that render returns. So a project's own async work races the first frames: a mesh fetched in `onMount`, a WebGPU device, a `fetch` whose answer decides a layout. The picture on the canvas has been there for minutes; the one in the encoder is a few milliseconds old.
diff --git a/reference/jsx/surface-paint.md b/reference/jsx/surface-paint.md
index 936d736d..843d6ed6 100644
--- a/reference/jsx/surface-paint.md
+++ b/reference/jsx/surface-paint.md
@@ -29,7 +29,7 @@ import type { SceneNode } from "@diffusionstudio/jsx";
- The ref receives the element's **`SceneNode`**, as every ref does. `element` is the paint's backing canvas: on the geometry for a `<surface>` (whose surface is its intrinsic paint), on the paint sub-entity for a `<surfacePaint>`; null where the host has no DOM.
- **Both SolidJS ref forms work.** The variable form `let surfaceRef: SceneNode | undefined;` + `ref={surfaceRef}` assigns the node when the element is created — read it in `onMount` or an effect, which run after the (synchronous) mount. The callback form `ref={(surface) => …}` runs **once**, when the element is created, inside the mount's reactive owner — `createEffect`, `onCleanup`, and [`useTicker`](./lifecycle.md#useticker) all work inside it.
-- The canvas is allocated with the element and **sized to the holder's `width`/`height`** in composition pixels. A same-size set is a no-op, so a `renderer.setSize` of your own is not clobbered; resize the bitmap yourself for higher resolution, since it is stretched into the box every frame either way, and an animated box scales pixels rather than re-rasterizing.
+- The canvas is allocated with the element and **sized to the holder's `width`/`height`** in composition pixels. A same-size set is a no-op, so a `renderer.setSize` of your own is not clobbered; resize the bitmap yourself for higher resolution, since it is stretched into the box every frame either way, and an animated box scales pixels rather than re-rasterizing. To follow the display's pixel ratio and the export scale, size it by [`useResolution`](#adapting-to-the-output-resolution).
- Unlike [`<html>`](./html.md) no flagged browser API is needed, and the sampled pixels render in exports.
## Reactivity
@@ -84,6 +84,37 @@ onMount(() => {
- `renderer.setSize(w, h, false)` resizes the bitmap through three.js; the third argument skips CSS sizing, which is meaningless on a detached canvas.
- Browsers cap live WebGL contexts per page (typically ~16, oldest evicted). One renderer is fine; don't give each of many paints its own GL context — share one renderer and copy frames out via `ImageBitmap` if you need many.
+## Adapting to the output resolution
+
+The bitmap is sampled in composition pixels, but the frame around it may rasterize denser: the live canvas draws at the display's pixel ratio, and an export's `resolution` setting scales the whole scene — a 960×540 surface in a 1080p export is a 2× upscale of the bitmap, and looks like one. Vector elements never notice (they rasterize through the scale); a surface holds pixels, so it has to provide them.
+
+[`useResolution`](./lifecycle.md#useresolution) is that scale, as a reactive accessor. Oversize the bitmap by it and draw at the same density, and the sample lands pixel for pixel in the output:
+
+```tsx
+const { time } = useTicker();
+const resolution = useResolution();
+let surfaceRef: SceneNode | undefined;
+
+createEffect(() => {
+ const el = surfaceRef!.element!;
+ const k = resolution();
+ // A same-size set is a no-op; a real change also resets the context state.
+ el.width = 400 * k;
+ el.height = 400 * k;
+ const ctx = el.getContext("2d")!;
+ ctx.setTransform(k, 0, 0, k, 0, 0); // keep drawing in composition pixels
+ ctx.clearRect(0, 0, 400, 400);
+ ctx.beginPath();
+ ctx.arc(200, 200, 60 + 40 * Math.sin(time() * Math.PI), 0, Math.PI * 2);
+ ctx.fillStyle = "#44dd88";
+ ctx.fill();
+});
+
+<surface width={400} height={400} ref={surfaceRef} />
+```
+
+Read the accessor **inside the effect that sizes and draws**: an export mounts the module before it configures its scale, so the first value is `1` and the correction arrives reactively before the first frame is sampled — a read at mount would miss it. For an external renderer the resize goes through its own API instead (`renderer.setSize(w * k, h * k, false)` for three.js, and a camera or transform keeping scene units in composition pixels); a WebGPU surface re-acquires its swapchain-bound resources after resizing, since the canvas texture changes size. Live, this also means retina-sharp previews — the cost is a bitmap `k²` the area, so a surface that should stay cheap can ignore the accessor and keep composition-size pixels.
+
## Props
| Prop | Type | Default | Meaning |