shaders 3.2.474 → 4.0.0

package/dist/core/std/motion.d.ts

@@ -1,40 +1,148 @@
 import { Expr } from '../gpu/contract';
 import { Scalar } from './values';
 
-/** Position within a repeating cycle, 0..1 (`fract(t / period)`). */
+/**
+ * How far through a repeating cycle the clock is, 0..1.
+ *
+ * `period` is the cycle length in seconds. The value ramps from 0 to 1 and snaps back.
+ *
+ * @example
+ * ```ts
+ * const sweep = motion.phase(animatedTime(params), params.uniforms.period)
+ * ```
+ * @see cycle, oscillate
+ */
 export declare function phase(t: Expr, period: Expr | number): Expr;
 /**
- * A repeating cycle: `progress` (0..1 within the cycle) and `index` (which cycle this
- * is) — the "every N seconds" word. Feed `index` to {@link cycleSeed} for something
- * random-but-stable per pass (a meteor's angle, a glitch's offset).
+ * A repeating cycle as two numbers: `progress` (0..1 through the current cycle) and
+ * `index` (which cycle this is).
+ *
+ * `period` is the cycle length in seconds. The "every N seconds" word: fade something in
+ * with `progress`, and feed `index` to `cycleSeed` when each pass should look different.
+ *
+ * @example
+ * ```ts
+ * const {progress, index} = motion.cycle(animatedTime(params), 2) // a new pass every 2 s
+ * ```
+ * @see cycleSeed, phase, pulseTrain
  */
 export declare function cycle(t: Expr, period: Expr | number): {
     progress: Expr;
     index: Expr;
 };
-/** A random-but-stable 0..1 value per cycle index (change `salt` for independent draws). */
+/**
+ * A random but stable number, 0..1, for each cycle index.
+ *
+ * The same index always gives the same value, so a meteor keeps its angle for the whole
+ * pass and picks a new one next time. Change `salt` for a second, independent draw.
+ *
+ * @example
+ * ```ts
+ * const hue = motion.cycleSeed(index)
+ * const size = motion.cycleSeed(index, 1)
+ * ```
+ * @see cycle
+ */
 export declare function cycleSeed(index: Expr, salt?: number): Expr;
 /**
- * An on/off rhythm: 1 for the first `duty` fraction of each cycle, 0 for the rest.
- * `soften` (cycle-fraction units) eases both edges; 0 is a hard blink.
+ * An on/off rhythm: 1 for the first part of each cycle, 0 for the rest.
+ *
+ * `period` is seconds per cycle and `duty` is the on fraction, 0..1. `soften` eases both
+ * edges over that fraction of the cycle. Leave it at 0 for a hard blink.
+ *
+ * @example
+ * ```ts
+ * const blink = motion.pulseTrain(animatedTime(params), {period: 1.5, duty: 0.3, soften: 0.05})
+ * ```
+ * @see pulsing, cycle, oscillate
  */
 export declare function pulseTrain(t: Expr, opts: {
     period: Expr | number;
     duty: Expr | number;
     soften?: number;
 }): Expr;
-/** A sine sweep between `min` and `max` at `rate` cycles per second. */
+/**
+ * A smooth back-and-forth between `min` and `max`.
+ *
+ * `rate` is cycles per second, default 1. `min` and `max` default to 0 and 1. `offset`
+ * shifts the starting point, in radians, so two oscillations can run out of step.
+ *
+ * @example
+ * ```ts
+ * const breathe = motion.oscillate(animatedTime(params), {rate: 0.5, min: 0.6, max: 1})
+ * ```
+ * @see oscillating, pulseTrain, phase
+ */
 export declare function oscillate(t: Expr, opts: {
     rate?: number;
     min?: Expr | number;
     max?: Expr | number;
     offset?: number;
 }): Expr;
+/**
+ * Short, bright flashes at a steady rate: dark most of the time, peaking briefly to 1.
+ *
+ * `rate` is how fast it runs (radians per second of the clock, so about 1 is one flash every
+ * six seconds). `offset` shifts when the flashes land, in radians; give each element its own
+ * (a hash times 2π) so they don't flash together. `sharpness` sets how brief each flash is:
+ * 2, 4, 8 or 16, where larger is briefer.
+ *
+ * @example
+ * ```ts
+ * const blink = motion.flashes(animatedTime(params), {rate: 1.4, offset: mul(seed, 6.283), sharpness: 8})
+ * ```
+ * @see pulseTrain, oscillate
+ */
+export declare function flashes(t: Expr, opts: {
+    rate: Expr | number;
+    offset?: Expr | number;
+    sharpness: 2 | 4 | 8 | 16;
+}): Expr;
+/**
+ * A 0..1 value that starts slow and speeds up.
+ *
+ * @example
+ * ```ts
+ * const grow = motion.easeIn(progress)
+ * ```
+ * @see easeOut, easeInOut
+ */
 export declare const easeIn: (x: Expr) => Expr;
+/**
+ * A 0..1 value that starts fast and slows to a stop.
+ *
+ * @example
+ * ```ts
+ * const settle = motion.easeOut(progress)
+ * ```
+ * @see easeIn, easeInOut
+ */
 export declare const easeOut: (x: Expr) => Expr;
+/**
+ * A 0..1 value that starts slow, speeds up, and slows again at the end.
+ *
+ * @example
+ * ```ts
+ * const glide = motion.easeInOut(progress)
+ * ```
+ * @see easeIn, easeOut
+ */
 export declare const easeInOut: (x: Expr) => Expr;
 type SignalClock = 'global' | 'node';
-/** {@link oscillate} as a slot signal. */
+/**
+ * A knob that sweeps between `min` and `max` on its own, for any slot that takes a prop.
+ *
+ * Same options as `oscillate`. By default it follows the page clock. Pass `clock: 'node'`
+ * to follow the layer's own speed prop instead, after declaring `animatedTime` on the
+ * definition.
+ *
+ * @example
+ * ```ts
+ * map: warps.twirl({center: p('center'), intensity: motion.oscillating({rate: 0.25, min: 0.4, max: 1.6, clock: 'node'})})
+ * ```
+ * @tip Inside `map:` it always follows the layer's clock, so declare `animatedTime: {speed: 'speed'}` there.
+ * @see oscillate, pulsing
+ */
 export declare function oscillating(opts: {
     rate?: number;
     min?: Expr | number;
@@ -42,7 +150,19 @@ export declare function oscillating(opts: {
     offset?: number;
     clock?: SignalClock;
 }): Scalar;
-/** {@link pulseTrain} as a slot signal. */
+/**
+ * A knob that switches on and off in a rhythm, for any slot that takes a prop.
+ *
+ * `period` is seconds per cycle, `duty` the on fraction, `soften` the edge ease, as in
+ * `pulseTrain`. Follows the page clock unless `clock: 'node'` is set.
+ *
+ * @example
+ * ```ts
+ * effect: effects.color.saturate(motion.pulsing({period: 2, duty: 0.5, soften: 0.1})) // color, then gray, then color
+ * ```
+ * @tip Inside `map:` it always follows the layer's clock, so declare `animatedTime: {speed: 'speed'}` there.
+ * @see pulseTrain, oscillating
+ */
 export declare function pulsing(opts: {
     period: number;
     duty: number;

package/dist/core/std/motion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/std/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AAGzC,OAAO,EAAC,MAAM,EAAwB,MAAM,UAAU,CAAA;AAItD,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAC,CAGnF;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAI,GAAG,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE;IAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAO7G;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAKzH;AAID,eAAO,MAAM,MAAM,MAAO,IAAI,KAAG,IAAiB,CAAA;AAClD,eAAO,MAAM,OAAO,MAAO,IAAI,KAAG,IAAyC,CAAA;AAC3E,eAAO,MAAM,SAAS,MAAO,IAAI,KAAG,IAA2B,CAAA;AAI/D,KAAK,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;AAQpC,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAC,GAAG,MAAM,CAEzI;AAED,2CAA2C;AAC3C,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAC,GAAG,MAAM,CAE1G"}
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/std/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AAGzC,OAAO,EAAC,MAAM,EAAwB,MAAM,UAAU,CAAA;AAItD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAC,CAGnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAI,GAAG,IAAI,CAErD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE;IAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAO7G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAKzH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE;IAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA;CAAC,GAAG,IAAI,CAKrH;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,MAAO,IAAI,KAAG,IAAiB,CAAA;AAClD;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,MAAO,IAAI,KAAG,IAAyC,CAAA;AAC3E;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,MAAO,IAAI,KAAG,IAA2B,CAAA;AAI/D,KAAK,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;AAQpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAC,GAAG,MAAM,CAEzI;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAC,GAAG,MAAM,CAE1G"}

package/dist/core/std/paint/compose.d.ts

@@ -1,21 +1,34 @@
 import { Expr, GpuFragmentParams } from '../../gpu/contract';
 
+/**
+ * One entry in `layers`: a color, or a color with options.
+ *
+ * `blend` is `'add'` (the default, sums light) or `'screen'` (brightens without blowing out).
+ * `opacity` scales the layer. `behind` is a 0–1 factor the layer is seen through, such as the
+ * transmittance of fog in front of it.
+ */
 export type Layer = Expr | {
     paint: Expr;
-    /** 'add' (default) sums light; 'screen' folds it in with 1−(1−a)(1−b). */
+    /** `'add'` (default) sums light; `'screen'` folds it in with 1−(1−a)(1−b). */
     blend?: 'add' | 'screen';
     /** Scales the layer's contribution. */
     opacity?: Expr | number;
-    /** A transmittance the layer is seen through (content behind a medium). */
+    /** A 0–1 factor the layer is seen through (content behind a medium). */
     behind?: Expr;
 };
 /**
- * Weighted layering: build N variations of the same thing from a plain-data layer list and
- * accumulate them — `weightedSum = Σ value·weight` and `totalWeight = Σ weight`, both in
- * list order. The caller owns the blend (usually a guarded weighted mean:
- * `weightedSum / (totalWeight + ε)`), because the guard and the remap are look decisions.
- * Cheap depth by stacking: aurora curtains, cloud banks, echo/ghost trails. Compile-time
- * layer counts are just `list.slice(0, n)` — disabled layers aren't emitted.
+ * Builds N variations of one thing from a data list and sums them with weights.
+ *
+ * Give it a list of plain data and a function that turns one entry into `{value, weight}`.
+ * You get `weightedSum` and `totalWeight` back and choose the blend yourself, usually
+ * `weightedSum / (totalWeight + 0.001)`. Slice the list to change how many layers are built.
+ *
+ * @example
+ * ```ts
+ * const {weightedSum, totalWeight} = layered(CURTAINS.slice(0, count), ({offset, weight}) => ({value: curtain(offset), weight: math.mul(alpha, weight)}))
+ * ```
+ * @tip Cheap depth: aurora curtains, cloud banks, echo trails are all a few layers of one recipe.
+ * @see layers
  */
 export declare function layered<T>(layerData: readonly T[], build: (layer: T, index: number) => {
     value: Expr;
@@ -24,19 +37,47 @@ export declare function layered<T>(layerData: readonly T[], build: (layer: T, in
     weightedSum: Expr;
     totalWeight: Expr;
 };
-/** Composite a stack of paint contributions, first entry at the back. */
+/**
+ * Stacks colors into one, first entry at the back.
+ *
+ * Each entry is a color, or `{paint, blend, opacity, behind}` (see `Layer`). Entries add
+ * together unless one asks for `'screen'`. Needs at least one entry.
+ *
+ * @example
+ * ```ts
+ * const rgb = layers([
+ *   {paint: sky, opacity: 0.6},
+ *   {paint: stars, behind: fog.transmittance},
+ *   {paint: glow, blend: 'screen'},
+ * ])
+ * ```
+ * @see layered, emissiveAlpha
+ */
 export declare function layers(entries: Layer[]): Expr;
 /**
- * `emissiveAlpha` — light as straight-alpha rgba: alpha is the peak channel and the colour is
- * the light divided by it, so the layer composites over black exactly as the additive light it
- * is, and over anything else as a translucent tint. The output step of any emissive paint drawn
- * over transparency (glows, spills, flares) — never for opaque bodies.
+ * Turns an rgb light value into a color with alpha, so glows composite over transparency.
+ *
+ * Alpha is the brightest channel and the color is scaled up to match, so over black the layer
+ * looks exactly like the light it is, and over anything else like a translucent tint. Use it
+ * as the last step of a glow, spill or flare. Not for opaque bodies.
+ *
+ * @example
+ * ```ts
+ * paint: (params) => compose.emissiveAlpha(math.mul(params.uniforms.color.member('rgb'), coverage))
+ * ```
+ * @see layers, dithered
  */
 export declare function emissiveAlpha(rgb: Expr, hint?: string): Expr;
 /**
- * `dithered` — the always-on ±0.002 output dither on a final rgba (hides banding on long soft
- * ramps). Apply to the COLOR, never to a ramp coordinate. Reads the composed UV and the
- * definition's clock.
+ * Adds a tiny amount of noise to a final color so long soft gradients show no banding.
+ *
+ * Apply it to the finished rgba, never to a value that still feeds a palette.
+ *
+ * @example
+ * ```ts
+ * paint: (params) => dithered(standardPalette(field, params), params)
+ * ```
+ * @see emissiveAlpha
  */
 export declare function dithered(color: Expr, params: GpuFragmentParams): Expr;
 //# sourceMappingURL=compose.d.ts.map

package/dist/core/std/paint/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/std/paint/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAO/D,MAAM,MAAM,KAAK,GACX,IAAI,GACJ;IACE,KAAK,EAAE,IAAI,CAAA;IACX,0EAA0E;IAC1E,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IACxB,uCAAuC;IACvC,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,IAAI,CAAA;CAChB,CAAA;AAEL;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACrB,SAAS,EAAE,SAAS,CAAC,EAAE,EACvB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK;IAAC,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,GAChE;IAAC,WAAW,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,IAAI,CAAA;CAAC,CAWxC;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,CAe7C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,SAAa,GAAG,IAAI,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAGrE"}
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../src/std/paint/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAC,IAAI,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAO/D;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GACX,IAAI,GACJ;IACE,KAAK,EAAE,IAAI,CAAA;IACX,8EAA8E;IAC9E,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IACxB,uCAAuC;IACvC,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,IAAI,CAAA;CAChB,CAAA;AAEL;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACrB,SAAS,EAAE,SAAS,CAAC,EAAE,EACvB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK;IAAC,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAC,GAChE;IAAC,WAAW,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,IAAI,CAAA;CAAC,CAcxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,IAAI,CAe7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,SAAa,GAAG,IAAI,CAIhE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAIrE"}