instantshader 0.5.0 → 0.6.1

package/README.md

@@ -3,7 +3,8 @@
 # instantshader
 
 Animated WebGL gradient shaders with zero dependencies. Mount a live, resizable
-gradient into any DOM element, or render a single frame to a detached canvas
+gradient into any DOM element, put dither, pixelate, halftone or ASCII effects
+over it or over your own image, or render a single frame to a detached canvas
 for export pipelines. Built by [InstantGradient](https://instantgradient.com/app).
 
 ## Install
@@ -51,21 +52,58 @@ import { mountGradient, bloom } from "instantshader";
 mountGradient(el, {
   shader: bloom,
   colors: ["#ffd9e8", "#ffb300", "#ff8fc0", "#3d7bff", "#0a2e14"],
-  // bloom has two independent motion modes — petals that breathe and lean,
+  // bloom has two independent motion modes: petals that breathe and lean,
   // and colours that travel outward through a still pattern. Mix freely.
   params: { sway: 0.5, colorflow: 0.4 },
 });
 ```
 
-Ranges, defaults and labels are all discoverable at runtime — `shader.params`
+Ranges, defaults and labels are all discoverable at runtime. `shader.params`
 is an array of `ParamDef`, and `shader.randomParams(rand)` produces a full,
 sensible param set for "randomize" flows. `shaders` and `getShader(id)` expose
 the whole registry (importing either pulls every shader).
 
+## Effects
+
+An effect redraws a picture: a shader's output, or an image, canvas or video
+frame you supply. Four are included: `pixelate`, `dither`, `halftone` and
+`ascii`.
+
+```ts
+import { mountStack, bloom, dither } from "instantshader";
+
+mountStack(el, {
+  source: { kind: "generator", shader: bloom },
+  colors: ["#140f30", "#9c2168", "#eb6a4e", "#fcd87c"],
+  effects: [{ effect: dither, params: { pattern: "blueNoise", colorMode: "palette", levels: 4 } }],
+  loopSeconds: 30,
+});
+```
+
+For an image, the source is `{ kind: "media", media: img }` with an optional
+`fit` of `"cover"` (default) or `"contain"`. `effects` is a list, bottom
+layer first. `mountStack` returns the `mountGradient` handle plus
+`setSource`, `setSourceParams`, `setEffects`, `setEffectParams(index, params)`,
+`refreshMedia()` and `getGridInfo()`. `renderStackFrame` renders one frame to
+a detached canvas and `createStackRenderer` is the seekable renderer for
+video export, both with the same options.
+
+Each effect's `params` array describes its controls the way `shader.params`
+does, with four kinds: float, enum (a string value from `options`), bool and
+colour (a `#rrggbb` string). A `when` field on a param says which other
+param's value makes it relevant, for building UI. `effects` and
+`getEffect(id)` expose the registry, and importing either pulls every effect.
+
+Effect sizes are in pixels at 1080p, and each effect computes one value per
+cell into a buffer that is the same at every output size, so a preview and a
+4K export contain identical cells. The [repository
+README](https://github.com/ugolbck/instantshader#effects) has images, every
+param with its range, and the details of how preview and export line up.
+
 ## Seamless loops
 
 Set `loopSeconds` and the animation repeats exactly, with no visible seam at
-the wrap — the frame at `t` and at `t + loopSeconds` are identical pixel for
+the wrap. The frame at `t` and at `t + loopSeconds` are identical pixel for
 pixel. Built for video export and for backgrounds that must not betray a
 restart.
 
@@ -100,7 +138,7 @@ Notes:
   light video file without slowing the animation down.
 - **`flow` ties its travel speed to the loop length.** It animates by
   translating in a straight line through a noise field that tiles, and it
-  covers exactly one tile per cycle — so a short loop flows fast and a long
+  covers exactly one tile per cycle, so a short loop flows fast and a long
   one flows slowly. The hand-tuned drift rate corresponds to a period around
   60–90s; below ~30s the currents move noticeably faster than the look was
   designed for. Compensate with `speed` rather than by shortening the loop.
@@ -111,7 +149,7 @@ Notes:
   slow oscillations (petal breathing ~20s, fan lean ~30s, petal flex ~42s)
   layered over a noise wander. Each oscillation holds still once the loop is
   shorter than about half its own period, so below ~10s the wander is the only
-  thing left moving. `colorflow` is unaffected — it always fits at least one
+  thing left moving. `colorflow` is unaffected. It always fits at least one
   full cycle into the loop, flowing faster on a short one.
 - `halo`, `dune` and `whorl` always complete at least one full cycle of their
   main motion per loop, so a short loop simply runs them faster.

package/dist/index.d.ts

@@ -12,6 +12,29 @@ type Renderer = {
 };
 declare function createRenderer(opts: RendererOptions): Renderer;
 //#endregion
+//#region src/stack.d.ts
+type StackRenderer = {
+  renderAt(timeMs: number): void;
+  setColors(colors: string[]): void;
+  /** Swaps the source. Recompiles only when the generator shader changed. */
+  setSource(source: Source): void;
+  /** Replaces the generator source's params. No-op for a media source. */
+  setSourceParams(params: Record<string, number>): void;
+  /** Re-uploads the media element's current pixels, e.g. after a video
+  * element advanced a frame. */
+  refreshMedia(): void;
+  /** Replaces the layer list. Layers whose EffectDef is unchanged at the same
+  * position keep their compiled programs. */
+  setEffects(layers: EffectLayer[]): void;
+  /** Merges params into one layer. */
+  setEffectParams(index: number, params: Record<string, ParamValue>): void;
+  setLoopSeconds(seconds: number | undefined): void;
+  resize(width: number, height: number): void;
+  getGridInfo(): GridInfo[];
+  dispose(): void;
+};
+declare function createStackRenderer(opts: StackOptions): StackRenderer;
+//#endregion
 //#region src/types.d.ts
 /**
 * Describes a single tunable knob exposed by a shader (e.g. "frequency",
@@ -116,6 +139,185 @@ type RendererOptions = {
   * See MountOptions.loopSeconds. */
   loopSeconds?: number;
 };
+/** A generator is what this library has always called a shader. */
+type GeneratorDef = ShaderDef;
+/** Effect params are wider than generator params: a dither needs a pattern
+* choice and two colors, which floats cannot express. */
+type ParamValue = number | boolean | string;
+type EffectParamBase = {
+  /** Param identifier. The GLSL uniform name is always "u_" + key. */
+  key: string;
+  label: string;
+  /** UI hint: show this control only while another param holds one of these
+  * values. The runtime ignores it. */
+  when?: {
+    key: string;
+    in: ParamValue[];
+  };
+};
+/** `type` is optional so that a generator's ParamDef is a valid FloatParamDef. */
+type FloatParamDef = EffectParamBase & {
+  type?: "float";
+  min: number;
+  max: number;
+  step: number;
+  default: number;
+};
+/** Values are strings so that reordering `options` never changes a saved
+* design. The uniform is a float holding the option's index. */
+type EnumParamDef = EffectParamBase & {
+  type: "enum";
+  options: {
+    value: string;
+    label: string;
+  }[];
+  default: string;
+};
+/** Uniform is a float, 0 or 1. */
+type BoolParamDef = EffectParamBase & {
+  type: "bool";
+  default: boolean;
+};
+/** "#rrggbb". Uniform is a vec3 of gamma-encoded sRGB in 0-1. */
+type ColorParamDef = EffectParamBase & {
+  type: "color";
+  default: string;
+};
+type EffectParamDef = FloatParamDef | EnumParamDef | BoolParamDef | ColorParamDef;
+/** What an EffectTexture's key() and build() get to look at. */
+type TextureEnv = {
+  /** The layer's fully resolved params. */
+  params: Record<string, ParamValue>;
+  /** Frame size in device pixels. */
+  width: number;
+  height: number;
+  /** Device pixels per reference pixel. */
+  outputScale: number;
+  /** From StackOptions.fontFamily, for effects that draw text. */
+  fontFamily: string;
+};
+type TextureData = {
+  /** Raw bytes are read as one channel when data.length === width * height,
+  * as RGBA when it is four times that. */
+  source: TexImageSource | {
+    data: Uint8Array;
+    width: number;
+    height: number;
+  };
+  filter: "nearest" | "linear";
+  /** "repeat" is only legal for power-of-two sizes in WebGL1. */
+  wrap: "clamp" | "repeat";
+  /** Extra uniforms describing the texture, e.g. an atlas's grid and glyph
+  * count. A number sets a float, an array a vec2/vec3/vec4. */
+  uniforms?: Record<string, number | number[]>;
+};
+/** An extra texture an effect needs, built by JS: a glyph atlas, a noise tile. */
+type EffectTexture = {
+  /** Sampler uniform name, e.g. "u_atlas". */
+  uniform: string;
+  /** Cache key. The runtime rebuilds the texture when this changes. */
+  key: (env: TextureEnv) => string;
+  build: (env: TextureEnv) => TextureData;
+};
+/**
+* A registered effect. Two shapes:
+*
+* - SOFT effect: only `fragment`. Runs once per output pixel and reads the
+*   layer below as `u_source`.
+* - GRID effect: has `grid`. `grid.fragment` is the CELL STAGE, run once per
+*   cell into a small cell buffer whose size depends on params and aspect
+*   ratio only. `fragment` is then the DRAW STAGE that paints that buffer
+*   onto the frame; omit it to get the default coverage upscale.
+*
+* The cell buffer is what makes a 900px preview and a 3840px export contain
+* the same cells. See SPEC-effects.md section 6.
+*/
+type EffectDef = {
+  id: string;
+  label: string;
+  params: EffectParamDef[];
+  fragment?: string;
+  grid?: {
+    /** Cell size in reference pixels, from the layer's resolved params.
+    * Rounded to whole reference pixels unless `lattice` is given. */
+    cell: (params: Record<string, ParamValue>) => [number, number];
+    /**
+    * Makes the grid a LATTICE: rotated by `angle` degrees about the frame
+    * centre, with an unrounded pitch. For effects whose draw stage paints
+    * soft antialiased shapes (halftone) rather than filling cells, so that
+    * nothing needs to land on whole pixels. coverage() is meaningless for a
+    * lattice; such an effect must supply its own draw `fragment`.
+    */
+    lattice?: (params: Record<string, ParamValue>) => {
+      angle: number;
+    };
+    fragment: string;
+  };
+  textures?: EffectTexture[];
+  /** Same contract as ShaderDef.randomParams. */
+  randomParams: (rand: () => number) => Record<string, ParamValue>;
+};
+/** The bottom of a stack. */
+type Source = {
+  kind: "generator";
+  shader: ShaderDef;
+  params?: Record<string, number>;
+} | {
+  kind: "media";
+  media: TexImageSource;
+  fit?: "cover" | "contain";
+};
+/** One effect in a stack. */
+type EffectLayer = {
+  effect: EffectDef;
+  /** Overrides; unset keys fall back to the param's default. */
+  params?: Record<string, ParamValue>;
+  /** Defaults to true. A disabled layer renders as if it were absent. */
+  enabled?: boolean;
+};
+type StackOptions = {
+  canvas: HTMLCanvasElement;
+  source: Source;
+  effects?: EffectLayer[];
+  /** Hex color stops of the palette ramp. Generators draw with it; effects
+  * in "palette" color mode map tone through it. */
+  colors: string[];
+  seed?: number;
+  /** See MountOptions.loopSeconds. Shared by the source and every layer. */
+  loopSeconds?: number;
+  /** Shown behind contain-fit media and under media alpha. Default black. */
+  background?: string;
+  /** CSS font-family for effects that draw text. The host must have loaded
+  * it (document.fonts.load) before creating the stack. */
+  fontFamily?: string;
+};
+/** Per grid layer: how the grid lands on the current frame. A host can use
+* pxPerCell to warn that a small preview cannot resolve a fine pattern. */
+type GridInfo = {
+  /** Index into the layer list. */
+  index: number;
+  cols: number;
+  rows: number;
+  pxPerCell: [number, number];
+};
+/** Options accepted by mountStack(): StackOptions without the canvas (the
+* mount owns one), plus playback speed. */
+type StackMountOptions = Omit<StackOptions, "canvas"> & {
+  /** Animation speed multiplier. Defaults to 1. */
+  speed?: number;
+};
+/** Live handle returned by mountStack(). */
+type StackHandle = Omit<MountHandle, "setParams"> & {
+  setSource(source: Source): void;
+  /** Merges params into a generator source. No-op for a media source. */
+  setSourceParams(params: Record<string, number>): void;
+  setEffects(layers: EffectLayer[]): void;
+  /** Merges params into one layer. */
+  setEffectParams(index: number, params: Record<string, ParamValue>): void;
+  /** Re-uploads the media element's current pixels. */
+  refreshMedia(): void;
+  getGridInfo(): GridInfo[];
+};
 //#endregion
 //#region src/shaders/flow.d.ts
 declare const flow: ShaderDef;
@@ -138,13 +340,29 @@ declare const dune: ShaderDef;
 //#region src/shaders/whorl.d.ts
 declare const whorl: ShaderDef;
 //#endregion
+//#region src/effects/pixelate.d.ts
+declare const pixelate: EffectDef;
+//#endregion
+//#region src/effects/dither.d.ts
+declare const dither: EffectDef;
+//#endregion
+//#region src/effects/halftone.d.ts
+declare const halftone: EffectDef;
+//#endregion
+//#region src/effects/ascii.d.ts
+declare const ascii: EffectDef;
+//#endregion
 //#region src/registry.d.ts
 declare const shaders: readonly ShaderDef[];
 declare function getShader(id: string): ShaderDef | undefined;
 //#endregion
+//#region src/effectRegistry.d.ts
+declare const effects: readonly EffectDef[];
+declare function getEffect(id: string): EffectDef | undefined;
+//#endregion
 //#region src/mount.d.ts
 /**
-* Mounts a live, animated gradient into `container` and returns a handle to
+* Mounts a live, animated stack (a source plus effect layers) into `container` and returns a handle to
 * control it. Owns a canvas (sized to the container via ResizeObserver, DPR
 * capped at 2 to bound fill-rate cost on high-density displays) and a RAF
 * loop that runs ONLY while playing — the same lifecycle used by the
@@ -159,19 +377,35 @@ declare function getShader(id: string): ShaderDef | undefined;
 * callers may mount many simultaneously-paused instances (e.g. a screenshot
 * grid) that must never carry a perpetual 60fps draw loop each.
 */
+declare function mountStack(container: HTMLElement, opts: StackMountOptions): StackHandle;
+/** mountStack() for the common case of one generator and no effects. */
 declare function mountGradient(container: HTMLElement, opts: MountOptions): MountHandle;
 //#endregion
 //#region src/frame.d.ts
 /**
-* Renders a single frame into a detached (not-in-DOM) canvas at an exact
-* pixel size, for export/thumbnail use cases that need a synchronous
-* snapshot rather than a live animation.
+* Renders a single frame of a stack (a source plus effect layers) into a
+* detached (not-in-DOM) canvas at an exact pixel size, for export/thumbnail
+* use cases that need a synchronous snapshot rather than a live animation.
 *
 * The returned canvas is NOT disposed automatically — its GL context must
 * stay alive after this function returns so callers can scrape pixels from
 * it (toDataURL/toBlob/getImageData/drawImage). Once the caller is done
 * with it, release the GL context by calling the returned `dispose()`.
 */
+declare function renderStackFrame(opts: {
+  source: Source;
+  effects?: EffectLayer[];
+  colors: string[];
+  seed?: number;
+  timeMs?: number;
+  /** See MountOptions.loopSeconds. */
+  loopSeconds?: number;
+  background?: string;
+  fontFamily?: string;
+  width: number;
+  height: number;
+}): RenderFrameResult;
+/** renderStackFrame() for the common case of one generator and no effects. */
 declare function renderGradientFrame(opts: {
   shader: ShaderDef;
   colors: string[];
@@ -187,6 +421,42 @@ declare function renderGradientFrame(opts: {
   height: number;
 }): RenderFrameResult;
 //#endregion
+//#region src/grid.d.ts
+type Grid = {
+  cols: number;
+  rows: number;
+  /** Cell size in reference pixels. */
+  cell: [number, number];
+  /** Frame size in reference pixels. */
+  ref: [number, number];
+  /** Output pixels per cell on each axis. Whole numbers mean an exact export. */
+  pxPerCell: [number, number];
+  /** Rotation of the grid about the frame centre, in radians. 0 unless the
+  * effect asked for a lattice. */
+  angle: number;
+  /** How far an unrotated grid extends past the frame, as a multiple of the
+  * frame (>= 1 on each axis). Partial cells at the edges make this exceed 1. */
+  extent: [number, number];
+};
+/**
+* The grid a cell size produces on a frame. Centred on the frame with a cell
+* boundary at the centre, so cols and rows are always even and a different
+* aspect ratio crops the grid evenly. Depends on the frame's aspect ratio
+* and the cell size only, never on its pixel dimensions.
+*
+* Two flavours:
+*
+* - default: cells are whole reference pixels and axis-aligned, so that
+*   1080p-class and 4K-class exports get whole output pixels per cell.
+* - `lattice`: for effects that draw soft, antialiased shapes (halftone).
+*   The grid may be rotated and its pitch need not be whole, since nothing
+*   snaps to pixels; it is sized to cover the rotated frame plus a margin of
+*   two cells, because a shape can spill into its neighbours' cells.
+*/
+declare function gridFor(width: number, height: number, cell: [number, number], lattice?: {
+  angle: number;
+}): Grid;
+//#endregion
 //#region src/palette.d.ts
 /**
 * Builds a 1024-texel RGBA ramp (Uint8Array, length 1024*4) by interpolating
@@ -203,4 +473,4 @@ declare function renderGradientFrame(opts: {
 */
 declare function buildPaletteRamp(colors: string[]): Uint8Array;
 //#endregion
-export { type MountHandle, type MountOptions, type ParamDef, type RenderFrameResult, type Renderer, type RendererOptions, type ShaderDef, beam, bloom, buildPaletteRamp, createRenderer, dune, flow, getShader, halo, mountGradient, renderGradientFrame, shaders, strata, whorl };
+export { type BoolParamDef, type ColorParamDef, type EffectDef, type EffectLayer, type EffectParamDef, type EffectTexture, type EnumParamDef, type FloatParamDef, type GeneratorDef, type Grid, type GridInfo, type MountHandle, type MountOptions, type ParamDef, type ParamValue, type RenderFrameResult, type Renderer, type RendererOptions, type ShaderDef, type Source, type StackHandle, type StackMountOptions, type StackOptions, type StackRenderer, type TextureData, type TextureEnv, ascii, beam, bloom, buildPaletteRamp, createRenderer, createStackRenderer, dither, dune, effects, flow, getEffect, getShader, gridFor, halftone, halo, mountGradient, mountStack, pixelate, renderGradientFrame, renderStackFrame, shaders, strata, whorl };