@dopaminefx/core 0.1.0

package/dist/framework/panel-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel-runner.js","sourceRoot":"","sources":["../../src/framework/panel-runner.ts"],"names":[],"mappings":"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"}

package/dist/framework/pass-common.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared plumbing for the two generic effect runners (pass-runner + panel-runner).
+ *
+ * The pure-shader runner (a full-screen triangle) and the Canvas2D-panel runner
+ * (an uploaded panel texture, then the same triangle) differ only in WHAT they
+ * upload/sample and one standard uniform (`uOrigin` vs `uCenter`). Everything
+ * else — the `name → u<Name>` scalar auto-binding, the palette + life/time/style
+ * standard uniforms, the per-frame uniform application, the shadow-pass geometry
+ * uniforms, and a linear/edge-clamped texture allocator — is identical glue and
+ * lives here ONCE so the two runners can't drift.
+ *
+ * The functions are deliberately tiny imperative helpers over a resolved uniform
+ * map (`u`) so the call order in each runner stays explicit and the emitted GL
+ * uniform writes remain byte-identical to the bespoke renderers these replaced.
+ */
+import type { RGB } from "../engine/color.js";
+import type { CachedProgram, GLContext } from "../engine/context.js";
+/**
+ * Rewrite a light fragment for the BACKDROP-aware (premultiplied source-over)
+ * path: swap the opaque `fragColor = vec4(col, 1.0)` / `vec4(max(col,0.0),1.0)`
+ * emit for `fragColor = dopLightOut(col)` (alpha = brightness) and inject the
+ * `dopLightOut` helper. This is the same emit swap the Android build applies
+ * (`tools/dopamine/src/android-shader.mjs`), so the web backdrop path and the
+ * native overlays share one premultiplied-light convention.
+ *
+ * The replace is global on purpose: a hybrid's shader has a SHADOW branch with
+ * its own opaque emit, but the light pass runs with `uShadow == 0` so that
+ * branch is dead code here — rewriting it is harmless, and it guarantees the
+ * LIVE light-path emit (wherever it sits in the source) is the premultiplied
+ * one. The shadow CONTEXT keeps the original, untouched fragment.
+ */
+export declare function compositeLightFragment(fragment: string): string;
+/** A resolved uniform-location map (the output of `CachedProgram.uniforms`). */
+export type UniformMap = Record<string, WebGLUniformLocation | null>;
+/** `bloomRadius → uBloomRadius` — the auto-binding name convention. */
+export declare const cap: (s: string) => string;
+/**
+ * The numeric `render.params` that auto-bind to a uniform: each `name → u<Name>`
+ * unless an explicit `bindings` entry overrides the uniform name (or maps it to
+ * `null` to skip — for a param the shader ignores, e.g. a scatter seed). The
+ * tempo `durationMs` is never a shader uniform.
+ */
+export declare function computeScalarBinds(params: Record<string, unknown>, bindings: Record<string, string | null>): Array<[string, string]>;
+/**
+ * Resolve the program + uniform map for one pass and bind the program + the
+ * shared empty VAO. Returns both so the caller can finish binding.
+ */
+export declare function beginProgram(glc: GLContext, vertex: string, fragment: string, allUniforms: readonly string[]): {
+    prog: CachedProgram;
+    u: UniformMap;
+};
+/** Set a float uniform iff the shader actually declares it. */
+export declare function setF(gl: WebGL2RenderingContext, u: UniformMap, name: string, v: number): void;
+/** Apply a `{ name → float }` map, skipping uniforms the shader doesn't declare. */
+export declare function applyFloatMap(gl: WebGL2RenderingContext, u: UniformMap, map: Record<string, number> | undefined): void;
+/** Bind the three palette stops (uC0/uC1/uC2). */
+export declare function bindPalette(gl: WebGL2RenderingContext, u: UniformMap, pal: RGB[]): void;
+/** Bind the auto-bound scalar params (`name → uniform`). */
+export declare function bindScalars(gl: WebGL2RenderingContext, u: UniformMap, params: Record<string, unknown>, scalarBinds: ReadonlyArray<readonly [string, string]>): void;
+/**
+ * Apply the per-frame uniform map from an effect's `frame()` hook. The
+ * well-known key `amp` maps to `uAmp`; every other key is its own uniform name.
+ */
+export declare function bindFrameUniforms(gl: WebGL2RenderingContext, u: UniformMap, frameUniforms: Record<string, number>): void;
+/**
+ * Set the shadow-pass uniforms (offset/soft/strength) from {@link shadowGeometry}.
+ * Call only on the shadow pass; the caller already set `uShadow = 1`.
+ */
+export declare function bindShadowGeometry(gl: WebGL2RenderingContext, u: UniformMap, canvas: HTMLCanvasElement, heightFrac: number, amp: number, style: number): void;
+/** Allocate a linear/edge-clamped texture (pixels uploaded later by the caller). */
+export declare function allocTexture(glc: GLContext): WebGLTexture;
+/** The standard uniforms common to BOTH runners (excludes uOrigin/uCenter). */
+export declare const STANDARD_COMMON: readonly ["uResolution", "uTarget", "uLife", "uTimeS", "uLoopS", "uPhase", "uStyle", "uAmp", "uC0", "uC1", "uC2", "uShadow", "uShadowOffset", "uShadowSoft", "uShadowStrength"];
+/**
+ * The targeted element's box in DEVICE px, falling back to the full canvas
+ * when no element box was supplied (so untargeted fires are unchanged). The
+ * single formula behind the `uTarget` standard uniform AND the `render.pass`
+ * `targetMinDimPx` input — one fallback rule, never two.
+ */
+export declare function resolveTargetPx(c: HTMLCanvasElement, targetSize: {
+    width: number;
+    height: number;
+} | undefined, dpr: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Bind `uTarget` — the targeted element's size (device px) the centrepiece is
+ * sized to — falling back to the full canvas when no element box was supplied
+ * (so untargeted fires are unchanged). Shared by both runners; a no-op for
+ * shaders that don't declare it.
+ */
+export declare function bindTarget(gl: WebGL2RenderingContext, u: Record<string, WebGLUniformLocation | null>, c: HTMLCanvasElement, targetSize: {
+    width: number;
+    height: number;
+} | undefined, dpr: number): void;
+//# sourceMappingURL=pass-common.d.ts.map

package/dist/framework/pass-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-common.d.ts","sourceRoot":"","sources":["../../src/framework/pass-common.ts"],"names":[],"mappings":"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"}

package/dist/framework/pass-common.js

@@ -0,0 +1,178 @@
+/**
+ * Shared plumbing for the two generic effect runners (pass-runner + panel-runner).
+ *
+ * The pure-shader runner (a full-screen triangle) and the Canvas2D-panel runner
+ * (an uploaded panel texture, then the same triangle) differ only in WHAT they
+ * upload/sample and one standard uniform (`uOrigin` vs `uCenter`). Everything
+ * else — the `name → u<Name>` scalar auto-binding, the palette + life/time/style
+ * standard uniforms, the per-frame uniform application, the shadow-pass geometry
+ * uniforms, and a linear/edge-clamped texture allocator — is identical glue and
+ * lives here ONCE so the two runners can't drift.
+ *
+ * The functions are deliberately tiny imperative helpers over a resolved uniform
+ * map (`u`) so the call order in each runner stays explicit and the emitted GL
+ * uniform writes remain byte-identical to the bespoke renderers these replaced.
+ */
+import { shadowGeometry } from "../engine/shadow.js";
+import { GLSL_LIGHT_OUT } from "../engine/look/glsl.js";
+// Cache the (idempotent) source transform by input string so repeated fires of
+// the same effect don't re-run the regex; the GLContext program cache keys on
+// the transformed source, so a backdrop-mode fire links its own variant once.
+const compositeFragCache = new Map();
+/**
+ * Rewrite a light fragment for the BACKDROP-aware (premultiplied source-over)
+ * path: swap the opaque `fragColor = vec4(col, 1.0)` / `vec4(max(col,0.0),1.0)`
+ * emit for `fragColor = dopLightOut(col)` (alpha = brightness) and inject the
+ * `dopLightOut` helper. This is the same emit swap the Android build applies
+ * (`tools/dopamine/src/android-shader.mjs`), so the web backdrop path and the
+ * native overlays share one premultiplied-light convention.
+ *
+ * The replace is global on purpose: a hybrid's shader has a SHADOW branch with
+ * its own opaque emit, but the light pass runs with `uShadow == 0` so that
+ * branch is dead code here — rewriting it is harmless, and it guarantees the
+ * LIVE light-path emit (wherever it sits in the source) is the premultiplied
+ * one. The shadow CONTEXT keeps the original, untouched fragment.
+ */
+export function compositeLightFragment(fragment) {
+    const cached = compositeFragCache.get(fragment);
+    if (cached)
+        return cached;
+    let out = fragment
+        .replace(/fragColor\s*=\s*vec4\(\s*max\(\s*(\w+)\s*,\s*0\.0\s*\)\s*,\s*1\.0\s*\)\s*;/g, "fragColor = dopLightOut($1);")
+        .replace(/fragColor\s*=\s*vec4\(\s*(\w+)\s*,\s*1\.0\s*\)\s*;/g, "fragColor = dopLightOut($1);");
+    // Only inject the helper if we actually swapped an emit (an effect that
+    // already emits premultiplied light — e.g. a `vec4(col, brightness)` — is
+    // left exactly as-is and needs no helper).
+    if (out !== fragment)
+        out = out.replace(/\nvoid main\s*\(/, "\n" + GLSL_LIGHT_OUT + "\nvoid main(");
+    compositeFragCache.set(fragment, out);
+    return out;
+}
+/** `bloomRadius → uBloomRadius` — the auto-binding name convention. */
+export const cap = (s) => `u${s.charAt(0).toUpperCase()}${s.slice(1)}`;
+/**
+ * The numeric `render.params` that auto-bind to a uniform: each `name → u<Name>`
+ * unless an explicit `bindings` entry overrides the uniform name (or maps it to
+ * `null` to skip — for a param the shader ignores, e.g. a scatter seed). The
+ * tempo `durationMs` is never a shader uniform.
+ */
+export function computeScalarBinds(params, bindings) {
+    const out = [];
+    for (const [name, value] of Object.entries(params)) {
+        if (typeof value !== "number")
+            continue;
+        if (name === "durationMs")
+            continue; // tempo, not a shader uniform
+        const override = bindings[name];
+        if (override === null)
+            continue; // explicitly not a uniform
+        out.push([name, override ?? cap(name)]);
+    }
+    return out;
+}
+/**
+ * Resolve the program + uniform map for one pass and bind the program + the
+ * shared empty VAO. Returns both so the caller can finish binding.
+ */
+export function beginProgram(glc, vertex, fragment, allUniforms) {
+    const { gl } = glc;
+    const prog = glc.program(vertex, fragment);
+    const u = prog.uniforms(allUniforms);
+    gl.useProgram(prog.program);
+    gl.bindVertexArray(glc.vao);
+    return { prog, u };
+}
+/** Set a float uniform iff the shader actually declares it. */
+export function setF(gl, u, name, v) {
+    const loc = u[name];
+    if (loc)
+        gl.uniform1f(loc, v);
+}
+/** Apply a `{ name → float }` map, skipping uniforms the shader doesn't declare. */
+export function applyFloatMap(gl, u, map) {
+    if (!map)
+        return;
+    for (const [n, v] of Object.entries(map))
+        setF(gl, u, n, v);
+}
+/** Bind the three palette stops (uC0/uC1/uC2). */
+export function bindPalette(gl, u, pal) {
+    const [c0, c1, c2] = pal;
+    if (c0)
+        gl.uniform3f(u.uC0, c0.r, c0.g, c0.b);
+    if (c1)
+        gl.uniform3f(u.uC1, c1.r, c1.g, c1.b);
+    if (c2)
+        gl.uniform3f(u.uC2, c2.r, c2.g, c2.b);
+}
+/** Bind the auto-bound scalar params (`name → uniform`). */
+export function bindScalars(gl, u, params, scalarBinds) {
+    for (const [name, uniformName] of scalarBinds) {
+        const loc = u[uniformName];
+        if (loc)
+            gl.uniform1f(loc, params[name]);
+    }
+}
+/**
+ * Apply the per-frame uniform map from an effect's `frame()` hook. The
+ * well-known key `amp` maps to `uAmp`; every other key is its own uniform name.
+ */
+export function bindFrameUniforms(gl, u, frameUniforms) {
+    for (const [n, v] of Object.entries(frameUniforms)) {
+        const loc = u[n === "amp" ? "uAmp" : n];
+        if (loc)
+            gl.uniform1f(loc, v);
+    }
+}
+/**
+ * Set the shadow-pass uniforms (offset/soft/strength) from {@link shadowGeometry}.
+ * Call only on the shadow pass; the caller already set `uShadow = 1`.
+ */
+export function bindShadowGeometry(gl, u, canvas, heightFrac, amp, style) {
+    const minDim = Math.min(canvas.width, canvas.height);
+    const sg = shadowGeometry({ minDim, heightFrac, amp, style });
+    gl.uniform2f(u.uShadowOffset, sg.offsetX, sg.offsetY);
+    gl.uniform1f(u.uShadowSoft, sg.soft);
+    gl.uniform1f(u.uShadowStrength, sg.strength);
+}
+/** Allocate a linear/edge-clamped texture (pixels uploaded later by the caller). */
+export function allocTexture(glc) {
+    const { gl } = glc;
+    const tex = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return tex;
+}
+/** The standard uniforms common to BOTH runners (excludes uOrigin/uCenter). */
+export const STANDARD_COMMON = [
+    "uResolution", "uTarget", "uLife", "uTimeS", "uLoopS", "uPhase", "uStyle", "uAmp",
+    "uC0", "uC1", "uC2", "uShadow", "uShadowOffset", "uShadowSoft", "uShadowStrength",
+];
+/**
+ * The targeted element's box in DEVICE px, falling back to the full canvas
+ * when no element box was supplied (so untargeted fires are unchanged). The
+ * single formula behind the `uTarget` standard uniform AND the `render.pass`
+ * `targetMinDimPx` input — one fallback rule, never two.
+ */
+export function resolveTargetPx(c, targetSize, dpr) {
+    return {
+        width: targetSize ? targetSize.width * dpr : c.width,
+        height: targetSize ? targetSize.height * dpr : c.height,
+    };
+}
+/**
+ * Bind `uTarget` — the targeted element's size (device px) the centrepiece is
+ * sized to — falling back to the full canvas when no element box was supplied
+ * (so untargeted fires are unchanged). Shared by both runners; a no-op for
+ * shaders that don't declare it.
+ */
+export function bindTarget(gl, u, c, targetSize, dpr) {
+    if (!u.uTarget)
+        return;
+    const { width, height } = resolveTargetPx(c, targetSize, dpr);
+    gl.uniform2f(u.uTarget, width, height);
+}
+//# sourceMappingURL=pass-common.js.map

package/dist/framework/pass-common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-common.js","sourceRoot":"","sources":["../../src/framework/pass-common.ts"],"names":[],"mappings":"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"}

package/dist/framework/pass-runner.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Generic fullscreen-pass runner — the shared backbone for PURE-SHADER effects.
+ *
+ * A pure-shader effect (Solarbloom, Calligraphic Verdict, the Fail stamp) is a
+ * full-screen triangle that runs a fragment shader twice — once into the light
+ * (screen) context and, when present, once into the shadow (multiply) context.
+ * Before this runner, each effect hand-wired the SAME plumbing: link/bind the
+ * program + VAO, set the standard uniforms (resolution, origin, time, life,
+ * envelope amp, palette, style, the shadow-pass uniforms), upload + bind any aux
+ * textures (a baked SDF icon) into BOTH contexts, run the two passes, and free
+ * the per-fire GPU resources. That ~120 lines of identical glue is now here,
+ * once.
+ *
+ * What stays per-effect (the honest boundary): the GLSL itself, and a tiny
+ * `frame()` hook that computes the genuinely effect-specific TIME-VARYING values
+ * (which envelope, which confirm/draw/stamp progress, any shake) into named
+ * uniforms. Everything else — standard uniforms, scalar `render.params` →
+ * `u<Name>` auto-binding, aux-texture upload/bind, the light+shadow loop, the
+ * "animate on twos" stepping, dispose — is generic and data-driven from a small
+ * config object.
+ *
+ * The output is byte-identical to the bespoke renderers it replaces: it sets the
+ * same uniforms, in a superset that the shader samples by name, and uses the same
+ * `shadowGeometry` / envelope / progress math (supplied by the config).
+ */
+import type { DecodedSdf } from "../engine/sdf.js";
+import type { RGB } from "../engine/color.js";
+import type { EffectContext, EffectInstance } from "./effect.js";
+/** A resolved param bag (the loader's output + any composed fields). */
+export type PassParams = Record<string, unknown> & {
+    durationMs: number;
+    palette: [RGB, RGB, RGB] | RGB[];
+    style: number;
+};
+/** Per-frame timing context handed to a config's `frame()` hook. */
+export interface FrameInfo {
+    /** The "on twos"-snapped animation clock in ms (stepping already applied). */
+    animMs: number;
+    /** Normalized life 0..1 (animMs / durationMs, clamped). */
+    life: number;
+    /**
+     * The REAL un-stepped wall clock in ms (the raw `renderAt` argument, before
+     * the "on twos" snap). Mirrors the Swift/Android runners, which hand their
+     * `frame()` hooks the same un-stepped clock for stamp/shake-style timing.
+     */
+    elapsedMs: number;
+}
+/**
+ * An aux texture the shader samples. Two sources fit the same model:
+ *   - `kind:"sdf"`  — a baked single-channel R8 distance field (an icon outline),
+ *   - `kind:"canvas"` — an RGBA Canvas2D source (a rasterized glyph, a panel).
+ * The runner uploads it into BOTH the light and shadow contexts (canvas sources
+ * upload once, on first bind, then cache), binds it on each pass, and computes
+ * per-pass derived uniforms (px ranges that depend on the live canvas size).
+ */
+export type AuxTextureSpec = {
+    kind: "sdf";
+    /** Texture unit to bind on (e.g. 1 for TEXTURE1). */
+    unit: number;
+    /** The decoded SDF to upload as an R8 single-channel texture. */
+    sdf: DecodedSdf;
+    /** Sampler uniform name (bound to `unit`). */
+    sampler: string;
+    /** "On" flag uniform name (set to 1 when present). */
+    onUniform?: string;
+    /** Per-pass scalar uniforms (canvas-size-dependent). */
+    uniforms?(canvas: HTMLCanvasElement, params: PassParams): Record<string, number>;
+} | {
+    kind: "canvas";
+    unit: number;
+    /** The Canvas2D source uploaded as an RGBA texture. */
+    source: HTMLCanvasElement;
+    sampler: string;
+    onUniform?: string;
+    uniforms?(canvas: HTMLCanvasElement, params: PassParams): Record<string, number>;
+};
+/** Config for one pure-shader effect. The genuinely code-shaped bits live here. */
+export interface PassConfig {
+    /** Vertex + fragment GLSL (the per-effect look — code under this boundary). */
+    vertex: string;
+    fragment: string;
+    /** Every uniform name the shader reads (for location pre-resolution). */
+    uniforms: readonly string[];
+    /**
+     * Whether the shader reads `uOrigin` (anchored radial effects do; a gesture
+     * that composes across the whole surface does not). Default false.
+     */
+    usesOrigin?: boolean;
+    /**
+     * The seamless loop period in ms (`tempo.loop.periodMs`) for a CONTINUOUS
+     * effect. When set, the runner computes the standard periodic clock uniforms
+     * each frame from the snapped clock: `uLoopS` (seconds within the current
+     * loop) and `uPhase` (normalized [0, 1)) — so a looping shader needs no
+     * per-effect period plumbing. Absent for one-shot effects.
+     */
+    loopPeriodMs?: number;
+    /**
+     * Explicit `param name → uniform name` overrides for the auto scalar binding.
+     * By convention a numeric param `bloomRadius` binds to `uBloomRadius`; list an
+     * entry here only for exceptions (e.g. `inkSeed → uSeed`). Map to `null` to
+     * NOT bind a param to any uniform (e.g. a scatter seed the shader ignores).
+     */
+    bindings?: Record<string, string | null>;
+    /** Declared aux textures (baked SDF icons), uploaded to light + shadow. */
+    auxTextures?(params: PassParams, ctx: EffectContext): AuxTextureSpec[];
+    /**
+     * Extra per-pass scalar uniforms that depend on the live canvas/target size
+     * but are NOT tied to an aux texture (e.g. an icon box size the shader uses
+     * even in its SDF-less analytic fallback). Computed once per pass.
+     * `targetPx` is the targeted element box in device px with the full-canvas
+     * fallback already applied (the same box `uTarget` binds).
+     */
+    passUniforms?(canvas: HTMLCanvasElement, params: PassParams, targetPx: {
+        width: number;
+        height: number;
+    }, dpr: number): Record<string, number>;
+    /**
+     * The shadow occluder "height" as a fraction of min canvas dim — Solarbloom's
+     * bloom radius, Verdict's stroke scale, a constant for the Fail stamp.
+     */
+    shadowHeightFrac: number | ((params: PassParams) => number);
+    /**
+     * Compute the genuinely effect-specific TIME-VARYING uniforms for a frame
+     * (the envelope amp, confirm/draw/stamp progress, shake, …). Returns a map of
+     * uniform name → float. `amp` is returned under a well-known key so the runner
+     * can feed it into `shadowGeometry`.
+     */
+    frame(info: FrameInfo, params: PassParams): {
+        amp: number;
+    } & Record<string, number>;
+    /**
+     * OPTIONAL dynamic sprite panel. A full-screen pass effect whose look is mostly
+     * procedural (a bloom, a flash) but which also has a SPARSE element layer (motes,
+     * sparks) shouldn't loop those elements at every pixel — that's O(pixels ×
+     * elements). Instead it rasterizes them into an offscreen Canvas2D ONCE per frame
+     * here; the runner uploads that canvas into BOTH passes and binds it as `sampler`
+     * on `unit`, and the shader samples it. (This is the pass-runner analogue of the
+     * hybrid panel-runner, but it COMPOSES with the static aux textures above — e.g.
+     * solarbloom keeps its baked-SDF/glyph checkmark AND gains a mote panel.)
+     */
+    panel?: {
+        /** Texture unit to bind the panel on (distinct from any auxTextures unit). */
+        unit: number;
+        /** Sampler uniform name the shader reads the panel from. */
+        sampler: string;
+        /** Draw one frame of the sprite layer into the offscreen canvas. */
+        draw(panelCtx: CanvasRenderingContext2D, width: number, height: number, params: PassParams, info: FrameInfo & {
+            centerPx: {
+                x: number;
+                y: number;
+            };
+            dpr: number;
+        }): void;
+    };
+    /**
+     * OPTIONAL per-frame ARRAY uniforms (vec2/3/4 arrays). For effects that
+     * precompute geometry on the CPU each frame and feed it to the shader as a
+     * uniform array — e.g. lightning's bolt polyline, far cheaper than re-deriving
+     * it with `fbm` at every pixel. Computed ONCE per frame and bound (uniformNfv)
+     * in both passes. `geom` carries the live canvas size + the gl-coords strike
+     * origin (anchor). Each returned `name` must also appear in `uniforms`.
+     */
+    frameArrays?(info: FrameInfo, params: PassParams, geom: {
+        width: number;
+        height: number;
+        dpr: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+    }): ReadonlyArray<{
+        name: string;
+        size: 2 | 3 | 4;
+        data: Float32Array;
+    }>;
+}
+/**
+ * Build a drawable {@link EffectInstance} for a pure-shader effect from its
+ * config + resolved params + the runtime context. This is the `create()` an
+ * effect (or a registered program) hands to the conductor.
+ */
+export declare function createPassInstance(config: PassConfig, params: PassParams, ctx: EffectContext): EffectInstance;
+//# sourceMappingURL=pass-runner.d.ts.map

package/dist/framework/pass-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-runner.d.ts","sourceRoot":"","sources":["../../src/framework/pass-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBjE,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,GAAG,EAAE,UAAU,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClF,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClF,CAAC;AAEN,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,2EAA2E;IAC3E,WAAW,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,cAAc,EAAE,CAAC;IACvE;;;;;;OAMG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC3C,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC,CAAC;IAC5D;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrF;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE;QACN,8EAA8E;QAC9E,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,OAAO,EAAE,MAAM,CAAC;QAChB,oEAAoE;QACpE,IAAI,CACF,QAAQ,EAAE,wBAAwB,EAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,GAAG;YAAE,QAAQ,EAAE;gBAAE,CAAC,EAAE,MAAM,CAAC;gBAAC,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GACpE,IAAI,CAAC;KACT,CAAC;IACF;;;;;;;OAOG;IACH,WAAW,CAAC,CACV,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GACrF,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CACzE;AAsBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,aAAa,GACjB,cAAc,CAyKhB"}