odori 0.0.6 → 0.0.7

package/dist/effects.d.ts

@@ -0,0 +1,202 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Turn a live DOM subtree into an image, deterministically.
+ *
+ * Chromium can draw an SVG onto a canvas, and an SVG `foreignObject` can hold
+ * ordinary markup, which is the whole trick. The reason it needs care is that
+ * the foreignObject is a sealed document: nothing outside it reaches in, so a
+ * subtree that looks right on the page rasterizes unstyled unless every rule
+ * that applied to it is carried across as an inline declaration.
+ *
+ * There is a native alternative, `CanvasRenderingContext2D.drawElement`, which
+ * would make all of this unnecessary. It is not in the pinned render browser,
+ * measured rather than assumed, so this is the only path that produces the
+ * same pixels in Studio and in an export. `captureMethod()` reports which one
+ * is in use so Studio never has to guess.
+ */
+/** Which capture strategy this browser can actually offer. */
+type CaptureMethod = "native" | "foreign-object";
+declare const captureMethod: () => CaptureMethod;
+/** The subtree as standalone XHTML, carrying everything it needs to paint. */
+declare const serializeElement: (element: HTMLElement) => string;
+/**
+ * Rasterize a subtree at a fixed size.
+ *
+ * Fonts first: a face that has not loaded when the SVG is parsed falls back,
+ * and the fallback is what gets baked into the pixels. The decode is awaited
+ * rather than assumed, so a caller holding the frame releases it only when
+ * there is something to capture.
+ */
+declare const captureElement: (element: HTMLElement, options: {
+    width: number;
+    height: number;
+}) => Promise<HTMLImageElement>;
+
+/**
+ * A fragment shader, and everything around it that nobody should have to
+ * write twice.
+ *
+ * An effect is one fragment shader and its named uniforms. The context, the
+ * program, the full-screen triangle, the source texture, the framebuffers a
+ * multi-pass chain ping-pongs between, and the teardown are all owned here,
+ * because every video that reached for a shader was otherwise rebuilding the
+ * same two hundred lines and getting the determinism details wrong.
+ *
+ * Time is not one of the things a shader may ask the browser for. Every
+ * built-in uniform derives from the frame, so frame 90 is the same picture
+ * whether it was rendered on its own or after eighty-nine others.
+ */
+type UniformValue = number | readonly number[];
+type UniformSpec = {
+    /** How many floats: 1, 2, 3, or 4. Decides which uniform call is made. */
+    size: 1 | 2 | 3 | 4;
+    defaultValue: UniformValue;
+};
+declare const numberUniform: (defaultValue: number) => UniformSpec;
+declare const vec2Uniform: (defaultValue: readonly [number, number]) => UniformSpec;
+declare const vec3Uniform: (defaultValue: readonly [number, number, number]) => UniformSpec;
+declare const vec4Uniform: (defaultValue: readonly [number, number, number, number]) => UniformSpec;
+type ShaderEffectDefinition = {
+    name: string;
+    fragmentShader: string;
+    uniforms: Record<string, UniformSpec>;
+};
+/** One configured use of an effect, which is what a surface is handed. */
+type EffectInstance = {
+    definition: ShaderEffectDefinition;
+    values: Record<string, UniformValue>;
+};
+/** A factory: call it with overrides to get something to put in `effects`. */
+type EffectFactory = (values?: Record<string, UniformValue>) => EffectInstance;
+declare const defineShaderEffect: (definition: ShaderEffectDefinition) => EffectFactory;
+/** Prepended to every effect, so a shader author writes only the body. */
+declare const SHADER_PRELUDE = "#version 300 es\nprecision highp float;\nuniform sampler2D source;\nuniform vec2 resolution;\nuniform float frame;\nuniform float fps;\nuniform float seconds;\nuniform float progress;\nout vec4 odoriColour;\n// sample is a reserved word in GLSL ES 3.00, so the helper is tex.\nvec4 tex(vec2 uv) { return texture(source, uv); }\n";
+declare class ShaderCompileError extends Error {
+    readonly effect: string;
+    readonly log: string;
+    readonly source: string;
+    constructor(effect: string, log: string, source: string);
+}
+type PipelineClock = {
+    frame: number;
+    fps: number;
+    durationInFrames: number;
+};
+/**
+ * The compiled chain for one surface. Built once, painted every frame, and
+ * disposed when the surface unmounts.
+ */
+declare class EffectPipeline {
+    private readonly gl;
+    private readonly passes;
+    private readonly sourceTexture;
+    private targets;
+    private width;
+    private height;
+    constructor(canvas: HTMLCanvasElement, effects: readonly EffectInstance[]);
+    /** The renderer as Studio reports it, for the capability panel. */
+    get renderer(): string;
+    private resize;
+    private setUniforms;
+    /** Upload the captured picture and run every pass over it. */
+    paint(source: TexImageSource, effects: readonly EffectInstance[], clock: PipelineClock): void;
+    private disposeTargets;
+    dispose(): void;
+}
+
+type SurfaceClock = {
+    frame: number;
+    fps: number;
+    seconds: number;
+    /** 0 to 1 across the composition. */
+    progress: number;
+    durationInFrames: number;
+    width: number;
+    height: number;
+};
+type HtmlInCanvasPaint<Renderer> = (args: SurfaceClock & {
+    renderer: Renderer;
+    source: CanvasImageSource;
+    canvas: HTMLCanvasElement;
+}) => void;
+type HtmlInCanvasInit<Renderer> = (args: {
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+}) => Renderer;
+/**
+ * What Studio shows about a surface, so a difference between preview and
+ * export is diagnosable without opening devtools.
+ */
+type SurfaceCapabilities = {
+    capture: CaptureMethod;
+    backend: "canvas-2d" | "webgl2";
+    renderer?: string;
+    error?: string;
+};
+/**
+ * Capture a React subtree once per frame and hand the picture to a painter.
+ *
+ * The children are ordinary React, laid out by the browser, which is the whole
+ * point: typography and product UI stay in the language they are written in
+ * and only the compositing is different. They are rendered off screen rather
+ * than into the canvas, captured, and then drawn.
+ *
+ * Determinism is the contract. The frame is held from before the capture
+ * starts until after the paint has finished, so an export never screenshots a
+ * surface that is halfway through, and every value a painter is given comes
+ * from the frame rather than from a clock.
+ */
+declare const HtmlInCanvas: <Renderer>({ children, width, height, onInit, onPaint, onDispose, onCapabilities, }: {
+    children: ReactNode;
+    /** Defaults to the composition's own size. */
+    width?: number;
+    height?: number;
+    onInit?: HtmlInCanvasInit<Renderer>;
+    onPaint?: HtmlInCanvasPaint<Renderer>;
+    onDispose?: (renderer: Renderer) => void;
+    onCapabilities?: (capabilities: SurfaceCapabilities) => void;
+}) => react_jsx_runtime.JSX.Element;
+/**
+ * The same capture, with a chain of shaders over it.
+ *
+ * One surface runs every effect in a single pipeline. Nesting two surfaces
+ * would capture and upload the DOM twice for one picture, which is why the
+ * composition is a list here rather than something to wrap repeatedly.
+ */
+declare const EffectSurface: ({ children, effects, width, height, onCapabilities, }: {
+    children: ReactNode;
+    effects: readonly EffectInstance[];
+    width?: number;
+    height?: number;
+    onCapabilities?: (capabilities: SurfaceCapabilities) => void;
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * The effects Odori ships, written the way a project would write its own.
+ *
+ * Each is one fragment shader against `SHADER_PRELUDE`, so `tex(uv)` reads
+ * the captured picture and `resolution`, `frame`, `fps`, `seconds` and
+ * `progress` are already in scope. Nothing here reaches for a clock, and
+ * nothing carries state between frames, which is what lets a worker render
+ * frame 200 without having rendered frame 199.
+ */
+/** Pull the picture out through a lens, or push it in. */
+declare const barrelDistortion: EffectFactory;
+/** Separate the channels, the way a cheap lens does at its edges. */
+declare const rgbSplit: EffectFactory;
+/** Horizontal lines, restrained enough to read as a screen and not a costume. */
+declare const scanlines: EffectFactory;
+/** Quantise to blocks. Sizes in output pixels, so it reads the same at any scale. */
+declare const pixelate: EffectFactory;
+/**
+ * Grain. Seeded from the frame rather than from a random number, so the same
+ * frame has the same grain every time it is rendered.
+ */
+declare const filmGrain: EffectFactory;
+/** Magnify a circle of the picture, like a loupe held over it. */
+declare const magnify: EffectFactory;
+
+export { type CaptureMethod, type EffectFactory, type EffectInstance, EffectPipeline, EffectSurface, HtmlInCanvas, type HtmlInCanvasInit, type HtmlInCanvasPaint, SHADER_PRELUDE, ShaderCompileError, type ShaderEffectDefinition, type SurfaceCapabilities, type SurfaceClock, type UniformSpec, type UniformValue, barrelDistortion, captureElement, captureMethod, defineShaderEffect, filmGrain, magnify, numberUniform, pixelate, rgbSplit, scanlines, serializeElement, vec2Uniform, vec3Uniform, vec4Uniform };