@effect-motion/renderer 0.5.0

package/dist/Renderer.js

@@ -0,0 +1,176 @@
+import { Renderer as Gpu, RenderTarget, Scene as ThreeScene, } from "@effect-motion/three";
+import { Effect, Scope } from "effect";
+import { dual } from "effect/Function";
+import { builtinRegistry } from "./Builtins.js";
+import * as Sync from "./Sync.js";
+/**
+ * Draw every nested sub-composition into its own render target.
+ *
+ * @remarks
+ * Internal, called by both render paths before their main pass. Depth-first,
+ * so a comp nested inside another is drawn before its parent samples it, and
+ * the previously bound target is always restored — including when a render
+ * fails.
+ */
+export const renderCompTargets = Effect.fnUntraced(function* (renderer, sync, pixelRatio) {
+    for (const comp of sync.comps.values()) {
+        yield* renderCompTargets(renderer, comp.sync, pixelRatio);
+        const pw = Math.max(1, Math.round(comp.width * pixelRatio));
+        const ph = Math.max(1, Math.round(comp.height * pixelRatio));
+        if (comp.rt === null ||
+            RenderTarget.width(comp.rt) !== pw ||
+            RenderTarget.height(comp.rt) !== ph) {
+            // comp targets live as long as their comp, not the frame — the
+            // Sync owns them and disposes through disposeComp
+            if (comp.rt !== null) {
+                RenderTarget.dispose(comp.rt);
+            }
+            comp.rt = RenderTarget.makeUnsafe(pw, ph);
+            comp.material.map = RenderTarget.texture(comp.rt);
+            comp.material.needsUpdate = true;
+        }
+        const previous = Gpu.getRenderTarget(renderer);
+        Gpu.setRenderTarget(renderer, comp.rt);
+        // ensuring: the previous target comes back even when the render
+        // fails — the sync version silently skipped the restore on a throw
+        yield* Gpu.render(renderer, comp.sync.scene, comp.sync.camera).pipe(Effect.ensuring(Effect.sync(() => Gpu.setRenderTarget(renderer, previous))));
+    }
+});
+/**
+ * `dual`'s predicate gets the whole `arguments` object — dispatch on
+ * args[0]. Renderer is a plain interface (not branded), so this is a
+ * structural check on the two fields every Renderer carries.
+ */
+const firstArgIsRenderer = (args) => {
+    const first = args[0];
+    return (typeof first === "object" &&
+        first !== null &&
+        "sync" in first &&
+        "gpu" in first);
+};
+/**
+ * Resize the drawing buffer.
+ *
+ * @remarks
+ * `width` and `height` are logical (CSS) pixels; `pixelRatio` scales to
+ * device pixels, so pass `window.devicePixelRatio` for a sharp result on a
+ * high-DPI display. Call on canvas resize.
+ */
+export const setViewport = dual(firstArgIsRenderer, (renderer, width, height, pixelRatio) => {
+    Gpu.setPixelRatio(renderer.gpu, pixelRatio);
+    Gpu.setSize(renderer.gpu, width, height);
+    return renderer;
+});
+/**
+ * Bring the retained three scene in step with a frame.
+ *
+ * @remarks
+ * This is the diff: objects new to this frame are built, ones whose data or
+ * world position changed are updated, and ones that left are disposed.
+ * Unchanged objects are skipped entirely, which is what makes a mostly-still
+ * scene cheap to hold on screen.
+ *
+ * Scene-graph problems — an instance referenced twice, an unknown id, a Hud
+ * nested inside world content, an entity with no registered renderer —
+ * arrive as a typed {@link RenderException} naming the offender rather than
+ * as a thrown exception.
+ */
+export const syncFrame = (renderer, frame) => Sync.syncFrame(renderer.sync, frame);
+/**
+ * Load the fonts and images a frame needs, before syncing it.
+ *
+ * @remarks
+ * Resources are resolved from the CALLER's context, so the loaders a scene
+ * declared must be provided around this call. Work is done once per resource
+ * per renderer: already-loaded fonts and images are skipped.
+ *
+ * The built-in default font is auto-provided, so plain text needs no setup.
+ * A font or image the frame references with no loader in context is a defect
+ * naming the id and the `Font.layer` / `Image.layer` call that would fix it.
+ */
+export const resolveResources = (renderer, frame) => Sync.resolveResources(renderer.sync, frame).pipe(Effect.provideService(Scope.Scope, renderer.scope));
+/**
+ * Draw the current retained scene to the canvas.
+ *
+ * @remarks
+ * Call after {@link syncFrame}. Before drawing, this waits for the async
+ * work that sync registered — glyph layouts and image decodes — so a frame
+ * never presents half-built text or a missing texture. A failed layout or
+ * decode surfaces as a typed error naming the resource.
+ *
+ * Nested sub-compositions are drawn to their own render targets first, then
+ * the world, then any HUD content composited on top through an identity
+ * camera so it ignores camera movement.
+ *
+ * Depth of field is not applied: every frame renders sharp, regardless of a
+ * camera's `aperture`.
+ */
+export const render = (renderer) => Sync.whenReady(renderer.sync).pipe(Effect.flatMap(() => renderCompTargets(renderer.gpu, renderer.sync, Gpu.getPixelRatio(renderer.gpu))), Effect.flatMap(() => 
+// ponytail: no depth of field — every frame renders sharp, and
+// Sync still derives the camera's DoF state for a future rebuild.
+Gpu.render(renderer.gpu, renderer.sync.scene, renderer.sync.camera)), Effect.flatMap(() => {
+    // HUD overlay: identity camera, above everything, DoF-exempt
+    if (ThreeScene.isEmpty(renderer.sync.hudScene)) {
+        return Effect.void;
+    }
+    return Effect.sync(() => {
+        Gpu.setAutoClear(renderer.gpu, false);
+        Gpu.clearDepth(renderer.gpu);
+    }).pipe(Effect.flatMap(() => Gpu.render(renderer.gpu, renderer.sync.hudScene, renderer.sync.hudCamera)), 
+    // autoClear must come back on even when the hud render fails
+    Effect.ensuring(Effect.sync(() => {
+        Gpu.setAutoClear(renderer.gpu, true);
+    })));
+}));
+/**
+ * Compile shader pipelines ahead of showing anything.
+ *
+ * @remarks
+ * Call once after the first {@link syncFrame} and before revealing the
+ * canvas. WebGPU compiles a pipeline the first time it is used, which would
+ * otherwise land as a visible hitch on frame one; doing it here moves that
+ * cost into startup.
+ */
+export const prewarm = (renderer) => Gpu.compile(renderer.gpu, renderer.sync.scene, renderer.sync.camera);
+/**
+ * Acquire a renderer for a canvas.
+ *
+ * @remarks
+ * Scoped: the GPU device and every retained object are disposed when the
+ * scope closes, so a player that mounts and unmounts leaks nothing.
+ *
+ * Pass `renderers` to draw entity kinds the built-ins do not cover, or to
+ * override how a built-in kind is drawn — the map is merged over the
+ * built-in manifest by entity tag.
+ *
+ * @param options - Canvas, dimensions, pixel ratio, and any custom entity
+ *   renderers.
+ * @returns A renderer, valid for the current scope.
+ *
+ * @example
+ * ```typescript
+ * const renderer = yield* Renderer.make({ canvas, width: 500, height: 300 });
+ * yield* Renderer.resolveResources(renderer, frame);
+ * yield* Renderer.syncFrame(renderer, frame);
+ * yield* Renderer.render(renderer);
+ * ```
+ */
+export const make = Effect.fn("Renderer.make")(function* (options) {
+    const registry = {
+        ...builtinRegistry,
+        ...options.renderers,
+    };
+    const sync = Sync.make(registry);
+    const gpu = yield* Gpu.make({
+        ...(options.canvas !== undefined ? { canvas: options.canvas } : {}),
+        antialias: true,
+        width: options.width,
+        height: options.height,
+        ...(options.pixelRatio !== undefined
+            ? { pixelRatio: options.pixelRatio }
+            : {}),
+    });
+    yield* Effect.addFinalizer(() => Sync.dispose(sync));
+    const scope = yield* Effect.scope;
+    return { sync, gpu, scope };
+});

package/dist/Sync.d.ts

@@ -0,0 +1,181 @@
+import { RenderTarget, ThreeRaw as THREE, Scene as ThreeScene } from "@effect-motion/three";
+import { Effect } from "effect";
+import { type EffectMotionError } from "effect-motion";
+import type { Frame } from "effect-motion/Scene";
+import type { EntityRenderer, RenderContext, Retained, World } from "./EntityRenderer.js";
+import * as Images from "./Images.js";
+import { RenderException } from "./RenderException.js";
+import * as Text from "./Text.js";
+type AnyFrame = Frame<unknown>;
+/**
+ * A renderer as the REGISTRY holds it. Each concrete renderer accepts only
+ * its own entity's data, so a heterogeneous registry is contravariant and
+ * cannot be read at any single entity type. The walk has already matched the
+ * leaf's `_tag` to its registry key by the time it dispatches, so the pairing
+ * is correct by construction — `dispatch` below is where that fact is
+ * asserted, once, rather than at each call site.
+ */
+type AnyEntityRenderer = EntityRenderer<never>;
+interface RetainedEntry {
+    readonly renderer: AnyEntityRenderer;
+    readonly retained: Retained;
+    /** which tier owns the object: world scene or the screen-space HUD */
+    readonly hud: boolean;
+    lastData: unknown;
+    lastWorld: World;
+}
+/** Diagnostics for the last synced frame. */
+export interface SyncStats {
+    /** How many objects are currently retained. */
+    objects: number;
+    /** How long the last sync took, in milliseconds. */
+    lastSyncMs: number;
+}
+/**
+ * The depth-of-field request derived from a frame's camera.
+ *
+ * @remarks
+ * Currently computed but NOT consumed: depth-of-field rendering is not
+ * implemented, and both render paths draw every frame sharp. The values are
+ * kept in step with the camera so the feature can be rebuilt without
+ * re-deriving them.
+ */
+export interface DofState {
+    /** Whether the camera asked for DoF (`aperture` and `focusDistance` both > 0). */
+    on: boolean;
+    /** View-space distance to the intended sharp plane. */
+    focusDistance: number;
+    /** Blur radius in uv units, derived from the aperture; 0 is off. */
+    strengthUv: number;
+}
+/**
+ * A nested scene (from `Scene.play`) as the renderer holds it.
+ *
+ * @remarks
+ * A sub-composition is drawn to its OWN render target and the result is
+ * pasted onto a plane in the parent scene, like a precomp in After Effects.
+ * That is what lets a whole nested scene be moved, faded, or scaled as one
+ * object, and what makes its background and bounds mean something.
+ *
+ * The child renders through its own identity camera, so its content is
+ * flattened before compositing: depth inside a nested scene does not react
+ * to the outer camera.
+ *
+ * ponytail: world-camera parallax inside a precomp would need a frustum-clip
+ * design if a scene ever wants it.
+ */
+export interface CompState {
+    readonly sync: Sync;
+    /** billboarded holder at the group's world anchor (in a scene tier) */
+    readonly holder: THREE.Group;
+    /** carries the group's 2D affine about the bounds center */
+    readonly transformHolder: THREE.Group;
+    readonly plane: THREE.Mesh;
+    readonly material: THREE.MeshBasicNodeMaterial;
+    /** created/resized by the render path (GPU-side) */
+    rt: RenderTarget.RenderTarget | null;
+    width: number;
+    height: number;
+    hud: boolean;
+}
+/**
+ * The retained scene state: the world and HUD tiers, their cameras, the
+ * text and image actors, live sub-compositions, and the object diff map.
+ *
+ * @remarks
+ * Mostly data — the API is the sibling functions ({@link syncFrame},
+ * {@link whenReady}, {@link resolveResources}, {@link dispose}).
+ *
+ * Content lives in one of two tiers. The WORLD scene is drawn through the
+ * frame's camera, so it moves with it; the HUD scene is drawn through an
+ * identity camera, above everything, so it stays fixed to the glass.
+ */
+export interface Sync {
+    /** the world scene, branded — the render paths take the wrapper */
+    readonly scene: ThreeScene.Scene;
+    readonly camera: THREE.PerspectiveCamera;
+    /**
+     * The screen-space HUD tier: drawn through an identity camera, after and
+     * above world content, on a transparent background so the render paths
+     * can overlay it.
+     */
+    readonly hudScene: ThreeScene.Scene;
+    readonly hudCamera: THREE.PerspectiveCamera;
+    readonly stats: SyncStats;
+    /**
+     * Depth-of-field request derived from the frame's camera — currently
+     * derived but not drawn. See {@link DofState}.
+     */
+    readonly dof: DofState;
+    /** the renderer's SDF text actor (fonts, atlas, layout) */
+    readonly text: Text.Text;
+    /** decoded image textures, cached for this renderer's scope */
+    readonly images: Images.Images;
+    /** live sub-compositions, keyed by their group instance id */
+    readonly comps: Map<string, CompState>;
+    /** internal: entity renderers by entity name */
+    readonly registry: Record<string, AnyEntityRenderer>;
+    /** internal: retained objects by instance id */
+    readonly retained: Map<string, RetainedEntry>;
+    /** internal: reused background color instance */
+    readonly background: THREE.Color;
+    /** internal: current frame viewport */
+    width: number;
+    height: number;
+    /** internal: the context handed to entity renderers */
+    readonly ctx: RenderContext;
+    /** internal: async work (SDF layouts, decodes) the next render must
+     * wait for — drained by `whenReady` */
+    readonly pending: Array<Effect.Effect<unknown, EffectMotionError>>;
+}
+export declare const make: (registry: Record<string, AnyEntityRenderer>) => Sync;
+/**
+ * Wait for the async work a sync registered — glyph layouts and image
+ * decodes — including inside nested sub-compositions.
+ *
+ * @remarks
+ * Both render paths call this before drawing, which is what guarantees a
+ * frame never presents half-built text or a missing texture. A failed layout
+ * or decode surfaces as a typed error naming the resource, rather than
+ * silently rendering nothing.
+ */
+export declare const whenReady: (sync: Sync) => Effect.Effect<void, EffectMotionError>;
+/**
+ * Bring the retained scenes in step with a frame.
+ *
+ * @remarks
+ * Runs the four phases described in the module overview. Objects are built,
+ * updated, or disposed as the frame demands; unchanged ones are skipped by
+ * reference equality on their data and world position, so a still scene
+ * costs almost nothing to hold.
+ *
+ * Scene-graph violations arrive as a typed `RenderException` naming the
+ * offending instance — never as a thrown exception escaping into the
+ * caller's Effect.
+ */
+export declare const syncFrame: (sync: Sync, frame: AnyFrame) => Effect.Effect<void, RenderException>;
+/**
+ * Release every retained object, texture, and sub-composition.
+ *
+ * @remarks
+ * Called automatically when a renderer's scope closes; you rarely call it
+ * directly. Effectful because decoded image textures live behind Deferreds
+ * that may still be in flight.
+ */
+export declare const dispose: (sync: Sync) => Effect.Effect<void, never, never>;
+/**
+ * Load the fonts and images a frame references into the sync actor.
+ *
+ * @remarks
+ * Frames carry resource REFERENCES, never bytes, so the bytes are resolved
+ * here from the caller's context. Only resources not already loaded are
+ * fetched, so this is cheap to call every frame.
+ *
+ * The built-in default font is auto-provided beneath caller context, so
+ * plain text works with no setup — and providing your own loader under the
+ * same `"sans-serif"` id overrides it. Any other font or image with no
+ * loader in context is a defect naming the id and the `Font.layer` /
+ * `Image.layer` call that would fix it.
+ */
+export declare const resolveResources: (sync: Sync, frame: AnyFrame) => Effect.Effect<undefined, never, import("effect/Scope").Scope>;
+export {};