instantshader 0.4.1 → 0.6.0

package/README.md

@@ -1,3 +1,5 @@
+![InstantShader](https://raw.githubusercontent.com/ugolbck/instantshader/main/.github/assets/banner.jpg)
+
 # instantshader
 
 Animated WebGL gradient shaders with zero dependencies. Mount a live, resizable
@@ -33,6 +35,13 @@ tree-shake away.
 | `flow` | Isotropic swirling currents. A curl-noise field advects the sample point before it hits fbm, so colour masses travel in continuous, fluid-like eddies with defined luminous edges and generous calm negative space. | `scale`, `curl`, `drift`, `openness`, `grain` |
 | `beam` | One wide beam of soft light crossing a near-black frame. The palette walks the beam's length, thin brighter filaments crawl inside it, and most of the frame is dark negative space. | `scale`, `width`, `glow`, `angle`, `grain` |
 | `bloom` | A fan of huge, ultra-soft petals radiating from the frame's bottom edge. One analytic rose-curve field, so the palette reads as concentric scalloped bands from a hot core out to a dark background, with thin dark creases between the petals. | `scale`, `petals`, `pinch`, `bend`, `sway`, `colorflow`, `grain` |
+| `halo` | An eclipse: one dark disc with a razor-bright limb and a corona of streamers flowing outward, the palette wrapped around the ring. `x` / `y` place the disc; the default sinks it below the frame for a glowing horizon arc. | `radius`, `x`, `y`, `glow`, `crescent`, `flares`, `grain` |
+| `strata` | Stacked cut-paper sheets, one per palette step, each casting a soft shadow on the one below. `ridges` and `stretch` reshape the relief itself, from round islands to branching spines to long agate bands. | `scale`, `layers`, `warp`, `ridges`, `stretch`, `depth`, `blend`, `angle`, `grain` |
+| `dune` | Overlapping crests rolling across the frame, back to front. Each has one crisp top edge and airbrushes away below it; neighbouring crests slide against each other. | `layers`, `swell`, `waves`, `fade`, `soft`, `angle`, `grain` |
+| `whorl` | A logarithmic spiral of curved blades, each with one sharp leading edge and a soft fade behind it. `x` / `y` place the centre anywhere, including off-frame. | `blades`, `twist`, `depth`, `scale`, `wobble`, `x`, `y`, `grain` |
+
+Previews of every look, with full param ranges, are in the
+[repository README](https://github.com/ugolbck/instantshader#readme).
 
 Every shader takes the same mount options; `params` is where they differ:
 
@@ -53,6 +62,25 @@ 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
+
+Effects redraw an existing picture: a generator's output or your own image, canvas or video frame.
+
+```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,
+});
+```
+
+`pixelate`, `dither`, `halftone` and `ascii` ship today; `effects` and `getEffect(id)` list them, and each `EffectDef.params` describes its controls (float, enum, bool and color, with a `when` hint for conditional ones). Use `{ kind: "media", media }` as the source for an image. `createStackRenderer` is the seekable renderer for export and `renderStackFrame` the one-shot.
+
+Effect sizes are in pixels at 1080p and effects work on a per-cell buffer that is identical at every output size, so an export matches its preview cell for cell. The [main README](../../README.md#effects) has the details.
+
 ## Seamless loops
 
 Set `loopSeconds` and the animation repeats exactly, with no visible seam at
@@ -104,5 +132,7 @@ Notes:
   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
   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.
 - Any loop necessarily revisits the same state every N seconds; a long period
   is what buys the impression of never repeating.

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;
@@ -126,13 +328,41 @@ declare const beam: ShaderDef;
 //#region src/shaders/bloom.d.ts
 declare const bloom: ShaderDef;
 //#endregion
+//#region src/shaders/halo.d.ts
+declare const halo: ShaderDef;
+//#endregion
+//#region src/shaders/strata.d.ts
+declare const strata: ShaderDef;
+//#endregion
+//#region src/shaders/dune.d.ts
+declare const dune: ShaderDef;
+//#endregion
+//#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
@@ -147,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[];
@@ -175,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
@@ -191,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, flow, getShader, mountGradient, renderGradientFrame, shaders };
+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 };