@occluze/umber 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/README.md +78 -48
- package/dist/chunks/badge.js +2 -0
- package/dist/chunks/basis.js +2 -0
- package/dist/chunks/basis_transcoder.js +2 -0
- package/dist/chunks/basis_transcoder.wasm +0 -0
- package/dist/chunks/capture.js +2 -2
- package/dist/chunks/covers.js +2 -2
- package/dist/chunks/curves.js +2 -0
- package/dist/chunks/flip.js +2 -2
- package/dist/chunks/fx.js +2 -102
- package/dist/chunks/gl.js +2 -180
- package/dist/chunks/glsl.js +2 -239
- package/dist/chunks/inspect.js +2 -6
- package/dist/chunks/instances.js +2 -93
- package/dist/chunks/layers.js +2 -21
- package/dist/chunks/licence.js +2 -2
- package/dist/chunks/morph.js +2 -2
- package/dist/chunks/patch.js +2 -0
- package/dist/chunks/prepared.js +2 -0
- package/dist/chunks/profiler.js +2 -0
- package/dist/chunks/restore.js +2 -2
- package/dist/chunks/shapes.js +2 -2
- package/dist/chunks/sim.js +2 -22
- package/dist/chunks/text.js +2 -52
- package/dist/chunks/video.js +2 -2
- package/dist/chunks/views.js +2 -2
- package/dist/chunks/vocabulary.js +2 -0
- package/dist/chunks/warm.js +2 -2
- package/dist/frameworks/astro.mjs +2 -0
- package/dist/frameworks/react.mjs +2 -0
- package/dist/frameworks/svelte.mjs +2 -0
- package/dist/frameworks/vue.mjs +2 -0
- package/dist/modules/debug.js +2 -36
- package/dist/modules/debug.mjs +2 -36
- package/dist/modules/handoff.js +2 -2
- package/dist/modules/handoff.mjs +2 -2
- package/dist/modules/input.js +2 -2
- package/dist/modules/input.mjs +2 -2
- package/dist/modules/router-swap.js +2 -13
- package/dist/modules/router.js +2 -2
- package/dist/modules/router.mjs +2 -2
- package/dist/modules/scroll-more.js +2 -0
- package/dist/modules/scroll-touch.js +2 -0
- package/dist/modules/scroll.js +2 -2
- package/dist/modules/scroll.mjs +2 -2
- package/dist/modules/scrollfx.js +2 -0
- package/dist/modules/scrollfx.mjs +2 -0
- package/dist/modules/scrub.js +2 -8
- package/dist/modules/scrub.mjs +2 -8
- package/dist/modules/three.js +2 -0
- package/dist/modules/three.mjs +2 -0
- package/dist/node/assets.mjs +9 -0
- package/dist/node/astro.mjs +47 -0
- package/dist/node/cli.mjs +109 -0
- package/dist/node/shared-3Q24RNIF.mjs +602 -0
- package/dist/node/shared-4FIU6DYP.mjs +200 -0
- package/dist/node/vite.mjs +10 -0
- package/dist/umber.css +2 -2
- package/dist/umber.js +2 -2
- package/dist/umber.mjs +2 -2
- package/docs/AI-quick.md +116 -54
- package/docs/AI.md +1275 -805
- package/docs/npm.md +37 -26
- package/package.json +181 -12
- package/types/assets.d.ts +87 -0
- package/types/astro.d.ts +43 -0
- package/types/debug.d.ts +17 -16
- package/types/esm.d.ts +12 -12
- package/types/global.d.ts +17 -0
- package/types/handoff.d.ts +26 -25
- package/types/input.d.ts +63 -55
- package/types/loop.d.ts +75 -0
- package/types/module.d.ts +108 -0
- package/types/react.d.ts +15 -0
- package/types/router.d.ts +87 -45
- package/types/scroll.d.ts +96 -38
- package/types/scrollfx.d.ts +80 -0
- package/types/scrub.d.ts +33 -32
- package/types/svelte.d.ts +16 -0
- package/types/three.d.ts +226 -0
- package/types/umber.d.ts +633 -357
- package/types/vite.d.ts +33 -0
- package/types/vue.d.ts +14 -0
package/types/handoff.d.ts
CHANGED
|
@@ -1,28 +1,28 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Types for the handoff module (@occluze/umber/handoff).
|
|
3
|
+
*
|
|
4
|
+
* data-umber-id images that fly across full page loads (multi-page sites, no router), the
|
|
5
|
+
* canvas over cross-document View Transitions, a cover pass of your own shader, and the
|
|
6
|
+
* accessibility bits of a page change:
|
|
7
|
+
*
|
|
8
|
+
* import { Handoff } from "@occluze/umber/handoff";
|
|
9
|
+
* umber.use(Handoff, { cover: "ink" }); // or createUmber({ modules: [Handoff] })
|
|
10
|
+
* <script src=".../umber@x.y.z/modules/handoff.js"></script> (registers itself)
|
|
11
|
+
*
|
|
12
|
+
* umber.handoff.arrived the record this page was opened with, or null
|
|
13
|
+
* umber.handoff.cover("ink", { phase: "cover" }) a router's leave hook
|
|
14
|
+
* umber.handoff.cover("ink", { phase: "reveal" }) ... and its enter hook
|
|
15
|
+
* umber.handoff.announce(); umber.handoff.focus(); after a router's swap
|
|
16
|
+
*/
|
|
4
17
|
|
|
5
|
-
|
|
6
|
-
// canvas over cross-document View Transitions, a cover pass of your own shader, and the
|
|
7
|
-
// accessibility bits of a page change:
|
|
8
|
-
//
|
|
9
|
-
// import { Handoff } from "@occluze/umber/handoff";
|
|
10
|
-
// gl.use(Handoff, { cover: "ink" }); // or createGL({ modules: [Handoff] })
|
|
11
|
-
// <script src=".../umber@x.y.z/modules/handoff.js"></script> (registers itself)
|
|
12
|
-
//
|
|
13
|
-
// gl.handoff.arrived the record this page was opened with, or null
|
|
14
|
-
// gl.handoff.cover("ink", { phase: "cover" }) a router's leave hook
|
|
15
|
-
// gl.handoff.cover("ink", { phase: "reveal" }) ... and its enter hook
|
|
16
|
-
// gl.handoff.announce(); gl.handoff.focus(); after a router's swap
|
|
17
|
-
|
|
18
|
-
import type { GL, UmberModule } from "./umber.js";
|
|
18
|
+
import type { Umber, UmberModule } from "./umber.js";
|
|
19
19
|
|
|
20
20
|
export interface HandoffOptions {
|
|
21
21
|
/** ms a leave record stays good for the next page. @default 3000 */
|
|
22
22
|
maxAge?: number;
|
|
23
23
|
/** Lift the canvas over a cross-document View Transition (needs layer "over"). @default true */
|
|
24
24
|
vt?: boolean;
|
|
25
|
-
/** A
|
|
25
|
+
/** A umber.shader() name played (revealing, from the old page's click) on a page reached through a record. @default null */
|
|
26
26
|
cover?: string | null;
|
|
27
27
|
/** Seconds of that reveal. @default 0.8 */
|
|
28
28
|
coverDuration?: number;
|
|
@@ -75,7 +75,7 @@ export interface CoverOptions {
|
|
|
75
75
|
direction?: 1 | -1;
|
|
76
76
|
}
|
|
77
77
|
|
|
78
|
-
/**
|
|
78
|
+
/** umber.handoff, once the module is in. */
|
|
79
79
|
export interface HandoffApi {
|
|
80
80
|
/** The record this page was opened with (this URL, fresh, not a reload), or null. */
|
|
81
81
|
readonly arrived: HandoffRecord | null;
|
|
@@ -85,13 +85,13 @@ export interface HandoffApi {
|
|
|
85
85
|
readonly direction: 1 | -1;
|
|
86
86
|
/** The cross-document View Transition this page was revealed with (await its finished), or null. */
|
|
87
87
|
readonly viewTransition: { readonly finished: Promise<unknown> } | null;
|
|
88
|
-
/** The module's options, live: with the script build, set them right after
|
|
88
|
+
/** The module's options, live: with the script build, set them right after createUmber(). */
|
|
89
89
|
readonly options: Required<HandoffOptions>;
|
|
90
90
|
/**
|
|
91
91
|
* A full-screen pass of your own shader over the page. It sets uCover (0 shows the page,
|
|
92
92
|
* 1 covers it), uOrigin (0..1, y down) and uDirection (1 | -1) where the shader declares
|
|
93
93
|
* them. Resolves when it is done. Reduced motion: nothing plays.
|
|
94
|
-
* @example
|
|
94
|
+
* @example umber.shader("ink", { uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 }, fragment: "..." });
|
|
95
95
|
*/
|
|
96
96
|
cover(shader: string, options?: CoverOptions): Promise<void>;
|
|
97
97
|
/** Say text (default: document.title) in a polite live region. */
|
|
@@ -101,16 +101,17 @@ export interface HandoffApi {
|
|
|
101
101
|
}
|
|
102
102
|
|
|
103
103
|
declare module "./umber.js" {
|
|
104
|
-
interface
|
|
104
|
+
interface Umber {
|
|
105
105
|
/** The handoff module's API (types/handoff.d.ts). */
|
|
106
106
|
readonly handoff: HandoffApi;
|
|
107
107
|
}
|
|
108
108
|
}
|
|
109
109
|
|
|
110
|
-
/**
|
|
110
|
+
/** umber.use(Handoff), createUmber({ modules: [Handoff] }). headSnippet: the <script> to paste into <head>. */
|
|
111
111
|
export declare const Handoff: UmberModule & { readonly headSnippet: string };
|
|
112
112
|
|
|
113
|
-
/** The same without
|
|
114
|
-
export declare function handoff(engine:
|
|
113
|
+
/** The same without umber.use(): adds umber.handoff to `engine`. */
|
|
114
|
+
export declare function handoff(engine: Umber, options?: HandoffOptions): HandoffApi;
|
|
115
115
|
|
|
116
|
+
/** @alias The same module as the named export, for `import Handoff from`. */
|
|
116
117
|
export default Handoff;
|
package/types/input.d.ts
CHANGED
|
@@ -1,29 +1,29 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
//
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
import type {
|
|
25
|
-
|
|
26
|
-
/** What
|
|
1
|
+
/**
|
|
2
|
+
* Types for the input module (@occluze/umber/input).
|
|
3
|
+
*
|
|
4
|
+
* Inputs as Signals: the speed of any Signal, a drag, the pointer's trail, presses and
|
|
5
|
+
* steps; and live textures: a canvas, video or numbers, the pointer's touch trail,
|
|
6
|
+
* element rects, an image's colour. Load the module, then use them from gl:
|
|
7
|
+
*
|
|
8
|
+
* import { Input } from "@occluze/umber/input";
|
|
9
|
+
* umber.use(Input); // or createUmber({ modules: [Input] })
|
|
10
|
+
* <script src=".../umber@x.y.z/modules/input.js"></script> (registers itself)
|
|
11
|
+
*
|
|
12
|
+
* const d = umber.drag(".gallery", { axis: "x", bounds: { x: [-2400, 0] } });
|
|
13
|
+
* umber.effect("bend", { uniforms: { uDrag: d, uDragSpeed: d.velocity }, ... });
|
|
14
|
+
* const v = umber.velocityOf(umber.progress(".story")); // progress per second, 0 at rest
|
|
15
|
+
* const t = umber.trail(16); // t.points[i].value: [x, y]
|
|
16
|
+
* umber.effect("ripple", { uniforms: { uPress: umber.press }, ... }); // [x, y, time]
|
|
17
|
+
* const off = umber.step(80, (at) => stamp(at)); // every 80 px the pointer travels
|
|
18
|
+
* const mask = umber.texture(canvas); mask.update(); // uploaded only when you say it changed
|
|
19
|
+
* umber.effect("smear", { uniforms: { uTouch: umber.touch() }, ... }); // sample with screenUv()
|
|
20
|
+
*
|
|
21
|
+
* Each one asks for frames only while it still moves: at rest the loop sleeps.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
import type { Umber, Signal, UmberModule } from "./umber.js";
|
|
25
|
+
|
|
26
|
+
/** What umber.velocityOf() follows: anything with a numeric value (a number or [x, y...]). */
|
|
27
27
|
export interface Readable {
|
|
28
28
|
readonly value: number | ArrayLike<number>;
|
|
29
29
|
}
|
|
@@ -35,7 +35,7 @@ export interface VelocityOptions {
|
|
|
35
35
|
rest?: number;
|
|
36
36
|
}
|
|
37
37
|
|
|
38
|
-
/**
|
|
38
|
+
/** umber.velocityOf(signal): units per second, smoothed; exactly 0 once the signal rests. */
|
|
39
39
|
export interface VelocitySignal<T = number | number[]> {
|
|
40
40
|
readonly value: T;
|
|
41
41
|
readonly destroyed: boolean;
|
|
@@ -62,7 +62,7 @@ export interface DragOptions {
|
|
|
62
62
|
}
|
|
63
63
|
|
|
64
64
|
/**
|
|
65
|
-
*
|
|
65
|
+
* umber.drag(el): a drag as a Signal. Writes nothing to the DOM. Give the element
|
|
66
66
|
* touch-action: pan-y (axis "x"), pan-x (axis "y") or none in its CSS.
|
|
67
67
|
*/
|
|
68
68
|
export interface DragSignal {
|
|
@@ -85,8 +85,8 @@ export interface DragSignal {
|
|
|
85
85
|
on(event: DragEvent, fn: (d: DragSignal) => void): () => void;
|
|
86
86
|
off(event: DragEvent, fn: (d: DragSignal) => void): void;
|
|
87
87
|
/**
|
|
88
|
-
* Automatic when its
|
|
89
|
-
* el leaves the page. A selector's waits for its next match instead, and a newer
|
|
88
|
+
* Automatic when its umber.scope() reverts or the engine goes; for umber.drag(element), also when
|
|
89
|
+
* el leaves the page. A selector's waits for its next match instead, and a newer umber.drag()
|
|
90
90
|
* of the same selector replaces it.
|
|
91
91
|
*/
|
|
92
92
|
destroy(): void;
|
|
@@ -98,20 +98,20 @@ export interface TrailOptions {
|
|
|
98
98
|
follow?: number;
|
|
99
99
|
}
|
|
100
100
|
|
|
101
|
-
/**
|
|
101
|
+
/** umber.trail(count): points[0] is the pointer, each next one follows the one before. */
|
|
102
102
|
export interface Trail {
|
|
103
103
|
/** Each a vec2 Signal: uniforms: { uTail: trail.points[15] }. */
|
|
104
|
-
readonly points:
|
|
104
|
+
readonly points: readonly Readonly<Signal<[number, number]>>[];
|
|
105
105
|
readonly destroyed: boolean;
|
|
106
106
|
destroy(): void;
|
|
107
107
|
}
|
|
108
108
|
|
|
109
|
-
/**
|
|
109
|
+
/** umber.press: the last press anywhere on the page. A vec3 uniform as it is. */
|
|
110
110
|
export interface PressSignal {
|
|
111
111
|
/** [x, y, time]: viewport px, and seconds in uTime's clock (-10000 before the first press). */
|
|
112
112
|
readonly value: [number, number, number];
|
|
113
113
|
/** The last 4 presses, newest first, each [x, y, time] (vec3 Signals). */
|
|
114
|
-
readonly recent:
|
|
114
|
+
readonly recent: readonly Readonly<Signal<[number, number, number]>>[];
|
|
115
115
|
/** Presses so far. */
|
|
116
116
|
readonly count: number;
|
|
117
117
|
on(event: "press", fn: (p: PressSignal) => void): () => void;
|
|
@@ -157,19 +157,19 @@ export interface TouchOptions {
|
|
|
157
157
|
fade?: number;
|
|
158
158
|
}
|
|
159
159
|
|
|
160
|
-
/**
|
|
160
|
+
/** umber.touch(): a = ink (0..1), rg = the way the pointer moved (rg * 2.0 - 1.0). Sample it with screenUv(). */
|
|
161
161
|
export interface TouchTexture extends LiveTexture {
|
|
162
162
|
readonly canvas: HTMLCanvasElement | OffscreenCanvas;
|
|
163
163
|
}
|
|
164
164
|
|
|
165
|
-
/**
|
|
165
|
+
/** umber.rects(): N x 1 RGBA32F texels, each x, y, width, height in viewport px (like uRect). */
|
|
166
166
|
export interface RectsTexture extends LiveTexture {
|
|
167
167
|
readonly count: number;
|
|
168
168
|
/** The same numbers, 4 per element. */
|
|
169
169
|
readonly rects: Float32Array;
|
|
170
170
|
}
|
|
171
171
|
|
|
172
|
-
/**
|
|
172
|
+
/** umber.imageColor(el): a vec4 Signal of the image's average colour, sRGB 0..1 ([0, 0, 0, 0] until known). */
|
|
173
173
|
export interface ImageColor {
|
|
174
174
|
readonly value: [number, number, number, number];
|
|
175
175
|
/** The most common colour (its pixels' average). */
|
|
@@ -178,58 +178,66 @@ export interface ImageColor {
|
|
|
178
178
|
readonly ready: Promise<boolean>;
|
|
179
179
|
}
|
|
180
180
|
|
|
181
|
-
/** What
|
|
181
|
+
/** What umber.use(Input) adds to gl. */
|
|
182
182
|
export interface InputMethods {
|
|
183
183
|
/**
|
|
184
184
|
* A <canvas>, ImageBitmap, <video>, <img>, ImageData or { data, width, height } as a
|
|
185
185
|
* sampler2D uniform, uploaded only after update() (a <video>: each new frame it shows).
|
|
186
|
-
* @example const mask =
|
|
186
|
+
* @example const mask = umber.texture(canvas); umber.effect("reveal", { uniforms: { uMask: mask }, ... }); mask.update();
|
|
187
187
|
*/
|
|
188
188
|
texture(source: TextureInput, options?: TextureOptions): LiveTexture;
|
|
189
189
|
/**
|
|
190
190
|
* The pointer's fading trail, screen-sized: sample it with screenUv(). Sleeps when faded.
|
|
191
|
-
* @example
|
|
191
|
+
* @example umber.effect("smear", { uniforms: { uTouch: umber.touch() }, ... })
|
|
192
192
|
*/
|
|
193
193
|
touch(options?: TouchOptions): TouchTexture;
|
|
194
194
|
/**
|
|
195
195
|
* The rects of these elements as an N x 1 texture (texelFetch(uCards, ivec2(i, 0), 0)).
|
|
196
|
-
* @example const cards =
|
|
196
|
+
* @example const cards = umber.rects(".card");
|
|
197
197
|
*/
|
|
198
198
|
rects(target: string | ArrayLike<Element>): RectsTexture;
|
|
199
199
|
/**
|
|
200
|
-
* The average and dominant colour of el's image (data-
|
|
201
|
-
* @example plane.set("uBg",
|
|
200
|
+
* The average and dominant colour of el's image (data-umber-src or its <img>), once.
|
|
201
|
+
* @example plane.set("uBg", umber.imageColor(el))
|
|
202
202
|
*/
|
|
203
203
|
imageColor(el: string | Element): ImageColor;
|
|
204
204
|
/**
|
|
205
|
-
* The speed of any Signal (
|
|
205
|
+
* The speed of any Signal (umber.progress, umber.drag, a { get value() } over a slider's
|
|
206
206
|
* progress), sampled on every frame Umber runs. A value your code moves between frames
|
|
207
|
-
* wakes the loop with
|
|
208
|
-
* @example const v =
|
|
207
|
+
* wakes the loop with umber.wake().
|
|
208
|
+
* @example const v = umber.velocityOf(umber.progress(".story"), { smooth: 0.2 });
|
|
209
209
|
*/
|
|
210
|
-
velocityOf<T extends number | ArrayLike<number>>(
|
|
211
|
-
|
|
210
|
+
velocityOf<T extends number | ArrayLike<number>>(
|
|
211
|
+
signal: { readonly value: T },
|
|
212
|
+
options?: VelocityOptions,
|
|
213
|
+
): VelocitySignal<T extends number ? number : number[]>;
|
|
214
|
+
/** @example const d = umber.drag(".slider", { axis: "x", bounds: { x: [-1200, 0] } }); */
|
|
212
215
|
drag(el: string | Element, options?: DragOptions): DragSignal;
|
|
213
|
-
/** @example const t =
|
|
216
|
+
/** @example const t = umber.trail(8, { follow: 0.35 }); */
|
|
214
217
|
trail(count?: number, options?: TrailOptions): Trail;
|
|
215
218
|
/** Made (one passive pointerdown listener) the first time it is read. */
|
|
216
219
|
readonly press: PressSignal;
|
|
217
220
|
/**
|
|
218
221
|
* fn(at, n) each time the pointer travelled another `every` px. Returns off().
|
|
219
|
-
* @example const off =
|
|
222
|
+
* @example const off = umber.step(80, ([x, y]) => stamp(x, y));
|
|
220
223
|
*/
|
|
221
224
|
step(every: number, fn: (at: [number, number], n: number) => void): () => void;
|
|
222
225
|
}
|
|
223
226
|
|
|
224
|
-
//
|
|
227
|
+
// umber.velocityOf, umber.drag, umber.trail, umber.press, umber.step, umber.texture, umber.touch, umber.rects and umber.imageColor, once the module is in;
|
|
228
|
+
// a umber.scope() carries the methods (s.drag...), and what they make is the scope's.
|
|
225
229
|
declare module "./umber.js" {
|
|
226
|
-
|
|
230
|
+
// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges InputMethods into GL
|
|
231
|
+
interface Umber extends InputMethods {}
|
|
232
|
+
// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- module augmentation: merges the methods into Scope
|
|
233
|
+
interface Scope extends Omit<InputMethods, "press"> {}
|
|
227
234
|
}
|
|
228
235
|
|
|
229
|
-
/**
|
|
236
|
+
/** umber.use(Input), createUmber({ modules: [Input] }). */
|
|
230
237
|
export declare const Input: UmberModule;
|
|
231
238
|
|
|
232
|
-
/** The same without
|
|
233
|
-
export declare function input(engine:
|
|
239
|
+
/** The same without umber.use(): adds the methods to `engine`. */
|
|
240
|
+
export declare function input(engine: Umber): void;
|
|
234
241
|
|
|
242
|
+
/** @alias The same module as the named export, for `import Input from`. */
|
|
235
243
|
export default Input;
|
package/types/loop.d.ts
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Umber's clock as a site sees it (re-exported by umber.d.ts): umber.on("frame") options,
|
|
3
|
+
* umber.loop (pause, play, restart, fps, the profiler), and what createUmber({ patch }) takes.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import type { TickPhase } from "./umber.js";
|
|
7
|
+
|
|
8
|
+
/** GSAP as createUmber({ patch: { gsap } }) needs it: its ticker, woken again to ask for its frames through the patch. */
|
|
9
|
+
export interface GsapLike {
|
|
10
|
+
ticker: { wake(): void };
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** How a umber.on("frame") callback runs. */
|
|
14
|
+
export interface FrameOptions {
|
|
15
|
+
/** @default "update" */
|
|
16
|
+
phase?: TickPhase;
|
|
17
|
+
/** Lower runs first inside its phase. @default 0 */
|
|
18
|
+
order?: number;
|
|
19
|
+
/** false: only ride along on frames Umber runs anyway. @default true */
|
|
20
|
+
always?: boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Its own rate: at most this many runs a second (30), or a share of the frames the loop
|
|
23
|
+
* runs ("50%": every other one). dt is then the time since it last ran.
|
|
24
|
+
* @example umber.on("frame", collide, { fps: 30 })
|
|
25
|
+
*/
|
|
26
|
+
fps?: number | `${number}%`;
|
|
27
|
+
/** Its name in the profiler (umber.loop.profile()). */
|
|
28
|
+
label?: string;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** umber.loop: Umber's clock as a whole (with createUmber({ patch: true }), the page's loops too). */
|
|
32
|
+
export interface Loop {
|
|
33
|
+
/** Stop every frame callback (and the patched loops) until play(). Unlike umber.pause(), GL keeps its planes on screen as they are. */
|
|
34
|
+
pause(): void;
|
|
35
|
+
/** Go on where it stopped: frame.time does not jump. */
|
|
36
|
+
play(): void;
|
|
37
|
+
/** frame.time and frame.frame from 0 again, and play. */
|
|
38
|
+
restart(): void;
|
|
39
|
+
readonly playing: boolean;
|
|
40
|
+
/** The screen's frame rate, as last measured. */
|
|
41
|
+
readonly fps: number;
|
|
42
|
+
/**
|
|
43
|
+
* A panel showing what each frame callback (and patched loop) costs, against the frame's
|
|
44
|
+
* budget, with a play / pause button (chunks/profiler.js, fetched on the first call). Also
|
|
45
|
+
* ?umber-debug=profiler with the debug module.
|
|
46
|
+
* @example const profiler = await umber.loop.profile(); profiler.destroy();
|
|
47
|
+
* @example const p = await umber.loop.profile({ panel: false }); setTimeout(() => console.table(p.read()), 2000);
|
|
48
|
+
*/
|
|
49
|
+
profile(options?: ProfilerOptions): Promise<Profiler>;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export interface ProfilerOptions {
|
|
53
|
+
/** @default "top-right" */
|
|
54
|
+
corner?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
|
|
55
|
+
/** false: time the callbacks without showing a panel (read them with profiler.read()). @default true */
|
|
56
|
+
panel?: boolean;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** One frame callback (or patched page loop) as the profiler measured it. */
|
|
60
|
+
export interface ProfileLine {
|
|
61
|
+
label: string;
|
|
62
|
+
phase: TickPhase;
|
|
63
|
+
order: number;
|
|
64
|
+
/** "30 fps", "50%", "page" (one of the page's own loops, patched in), or "". */
|
|
65
|
+
rate: string;
|
|
66
|
+
/** ms per frame, averaged over about a second. */
|
|
67
|
+
ms: number;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** What umber.loop.profile() resolves with. */
|
|
71
|
+
export interface Profiler {
|
|
72
|
+
/** Every callback timed so far, in the order they run. */
|
|
73
|
+
read(): ProfileLine[];
|
|
74
|
+
destroy(): void;
|
|
75
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for an add-on's plane hooks (@occluze/umber/module).
|
|
3
|
+
*
|
|
4
|
+
* For writing your own add-on: what UmberModule.plane() gets for each plane whose element
|
|
5
|
+
* carries one of its attributes, and what it hands back (a frame source, GLSL, a handle at
|
|
6
|
+
* plane[name]). Types only: import them where the add-on is written.
|
|
7
|
+
*
|
|
8
|
+
* import type { PlaneModuleContext, PlaneModuleBinding } from "@occluze/umber/module";
|
|
9
|
+
*
|
|
10
|
+
* With script tags and TypeScript, copy it next to types/umber.d.ts.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import type { EffectDef, Float32s, Frame, Umber, ModuleLog, Plane } from "./umber.js";
|
|
14
|
+
|
|
15
|
+
declare module "./umber.js" {
|
|
16
|
+
interface UmberModule {
|
|
17
|
+
/** For every plane whose element has one of its attributes, before the plane's program is built. */
|
|
18
|
+
plane?(ctx: PlaneModuleContext): PlaneModuleBinding | null | undefined;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** What module.plane() gets. */
|
|
23
|
+
export interface PlaneModuleContext {
|
|
24
|
+
el: HTMLElement;
|
|
25
|
+
/** The plane (what umber.plane(el) returns). */
|
|
26
|
+
plane: Plane;
|
|
27
|
+
engine: Umber;
|
|
28
|
+
/** The element's <video> or <img>, if it has one. */
|
|
29
|
+
media: HTMLVideoElement | HTMLImageElement | null;
|
|
30
|
+
/** umber.use(module, options). */
|
|
31
|
+
options: Record<string, unknown>;
|
|
32
|
+
/** This plane's GPU frames (made on first read): a source uploads into it and picks what is drawn. */
|
|
33
|
+
readonly frames: FrameCache;
|
|
34
|
+
/** Device tier ("high" desktop, "mid" phones, "low" weak GPUs): for memory budgets. */
|
|
35
|
+
tier: "high" | "mid" | "low";
|
|
36
|
+
/** Largest texture side this device gets. */
|
|
37
|
+
maxTexture: number;
|
|
38
|
+
isTouch: boolean;
|
|
39
|
+
readonly reducedMotion: boolean;
|
|
40
|
+
/** What the engine reads scroll from. */
|
|
41
|
+
scrollKind: "window" | "element" | "lenis" | "object";
|
|
42
|
+
/** The engine's console: warnings and errors as the engine's own (shown once each), info with debug on. */
|
|
43
|
+
log: ModuleLog & { info(...args: unknown[]): void };
|
|
44
|
+
/** Draw every frame while on (smoothing towards a target). */
|
|
45
|
+
busy(on: boolean): void;
|
|
46
|
+
/** Draw at least one more frame. */
|
|
47
|
+
wake(): void;
|
|
48
|
+
/** Give this element back to the DOM for the visit (its <video> / poster shows). */
|
|
49
|
+
fail(message?: string): void;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** What module.plane() returns. Every member is optional. */
|
|
53
|
+
export interface PlaneModuleBinding {
|
|
54
|
+
/** The public handle, at plane[module.name] (umber.plane(el).scrub). */
|
|
55
|
+
api?: unknown;
|
|
56
|
+
/** GLSL drawn first on this plane, before its own effects (its uniforms are added to the plane). */
|
|
57
|
+
effect?: EffectDef;
|
|
58
|
+
/** true: the plane's pixels come from its FrameCache, never from its <img> / <video>. */
|
|
59
|
+
source?: boolean;
|
|
60
|
+
/** Came near the screen (true, also the first time: start loading) or went far (false: free memory). */
|
|
61
|
+
near?(on: boolean): void;
|
|
62
|
+
/** On screen or not. */
|
|
63
|
+
visible?(on: boolean): void;
|
|
64
|
+
/**
|
|
65
|
+
* Update phase, every frame while near or on screen. `rect`: the plane's viewport rect
|
|
66
|
+
* (x, y, w, h); `viewport`: the visible screen. Return true when the picture changed.
|
|
67
|
+
*/
|
|
68
|
+
update?(frame: Frame, rect: Float32s<4>, viewport: { width: number; height: number }): boolean | undefined;
|
|
69
|
+
/** The WebGL context was lost: every GPU frame is gone. */
|
|
70
|
+
lost?(): void;
|
|
71
|
+
/** The context is back (frames are empty: upload again). */
|
|
72
|
+
restored?(): void;
|
|
73
|
+
/** The plane is going (element left, umber.destroy). */
|
|
74
|
+
destroy?(): void;
|
|
75
|
+
/** Its <video> got a new src: false keeps the plane (the module wrote it), else it is built again. */
|
|
76
|
+
src?(): boolean;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Pixels a FrameCache accepts: a decoded VideoFrame, an ImageBitmap, a <video> or <img>, a canvas. */
|
|
80
|
+
export type FrameImage = TexImageSource | { displayWidth: number; displayHeight: number; close(): void };
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* A plane's GPU frame cache: numbered frames as textures, kept up to a memory budget around
|
|
84
|
+
* a playhead, two of them drawn mixed. Uploads happen in the render phase, a few per frame.
|
|
85
|
+
*/
|
|
86
|
+
export interface FrameCache {
|
|
87
|
+
/** Upload frame `index` in the next render. close: free `image` after that (VideoFrame, ImageBitmap). */
|
|
88
|
+
put(index: number, image: FrameImage, close?: boolean): void;
|
|
89
|
+
/** Uploaded or waiting to be. */
|
|
90
|
+
has(index: number): boolean;
|
|
91
|
+
/** Uploaded: drawable now. */
|
|
92
|
+
ready(index: number): boolean;
|
|
93
|
+
/** Draw frame a, mixed towards frame b by `mix` (0..1). */
|
|
94
|
+
show(a: number, b?: number, mix?: number): void;
|
|
95
|
+
/** The playhead: frames far from it are dropped first when the budget is full. */
|
|
96
|
+
focus(index: number): void;
|
|
97
|
+
/** Max bytes of frames kept on the GPU. */
|
|
98
|
+
budget: number;
|
|
99
|
+
readonly bytes: number;
|
|
100
|
+
/** Frames on the GPU. */
|
|
101
|
+
readonly size: number;
|
|
102
|
+
/** Uploaded frame numbers. */
|
|
103
|
+
keys(): number[];
|
|
104
|
+
/** How many frames of width x height fit in the budget. */
|
|
105
|
+
capacity(width: number, height: number): number;
|
|
106
|
+
/** Free every frame (keepShown: but the one on screen, for a plane that went far). */
|
|
107
|
+
clear(keepShown?: boolean): void;
|
|
108
|
+
}
|
package/types/react.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for @occluze/umber/react: useScroll(), Lenis's useLenis() for Umber's umber.scroll.
|
|
3
|
+
*
|
|
4
|
+
* import { useScroll } from "@occluze/umber/react";
|
|
5
|
+
* const scroll = useScroll((s) => setProgress(s.progress), []);
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type { ScrollApi } from "./scroll.js";
|
|
9
|
+
|
|
10
|
+
/** umber.scroll (null until mounted, or without the scroll module); `callback` hears its "scroll" while mounted. The engine: the one on the page, or `gl`. */
|
|
11
|
+
export declare function useScroll(
|
|
12
|
+
callback?: (scroll: ScrollApi) => void,
|
|
13
|
+
deps?: readonly unknown[],
|
|
14
|
+
gl?: { readonly scroll?: ScrollApi } | null,
|
|
15
|
+
): ScrollApi | null;
|