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.tsxindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 insertingdiff --git a/packages/reconciler/src/runtime.ts b/packages/reconciler/src/runtime.tsindex 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.mdindex 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 |## Pipelinediff --git a/reference/jsx/lifecycle.md b/reference/jsx/lifecycle.mdindex 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.mdindex 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 |