@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/umber.d.ts
CHANGED
|
@@ -1,63 +1,74 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Umber's public types for site code.
|
|
3
|
+
*
|
|
4
|
+
* Editor autocomplete and type checks for site code (VS Code, Astro, Vite, TS or
|
|
5
|
+
* checkJs projects). Nothing here runs.
|
|
6
|
+
*
|
|
7
|
+
* <script src=".../umber@x.y.z/umber.js"> -> window.Umber: { version, createUmber, math, use }
|
|
8
|
+
* import { createUmber } from "@occluze/umber" (types/esm.d.ts)
|
|
9
|
+
*
|
|
10
|
+
* For the <script> tag: copy this file and global.d.ts (window.Umber and the global
|
|
11
|
+
* `Umber`) into your project (e.g. src/types/) and list both in tsconfig/jsconfig
|
|
12
|
+
* "include", or add /// <reference path="./types/global.d.ts" />. With the npm package
|
|
13
|
+
* installed: /// <reference types="@occluze/umber/global" />. An `import` from
|
|
14
|
+
* "@occluze/umber" gets no window.Umber: the npm build never sets it.
|
|
15
|
+
*
|
|
16
|
+
* Hand-written on purpose: one readable file, also the most compact exact API reference
|
|
17
|
+
* to paste into an AI assistant. Keep it in step with src/types.ts and src/core/create.ts
|
|
18
|
+
* (test/types/types.test.ts checks the members of Umber and of the engine).
|
|
19
|
+
*
|
|
20
|
+
* Attribute cheat sheet (the DOM is the API). An element says what it is, how it behaves,
|
|
21
|
+
* and what it's set to: data-umber="<kind> <behaviours>", then one attribute per setting.
|
|
22
|
+
*
|
|
23
|
+
* kinds, one: image | video | text | shader | layer | model | group (a GPU plane)
|
|
24
|
+
* container | wrapper (router), scroller (the element that scrolls)
|
|
25
|
+
* behaviours: above, pin, horizontal, inview (scrollfx), skip (router), nested (scroll)
|
|
26
|
+
* with a value, the long form only: data-umber-pin="80px", data-umber-inview="shown"
|
|
27
|
+
*
|
|
28
|
+
* data-umber="group" draws the GL planes inside it as one, through its
|
|
29
|
+
* own data-umber-effect (docs/ai/groups.md)
|
|
30
|
+
* data-umber-pass="grade grain" effects run over the whole GL frame (on <html> or <body>)
|
|
31
|
+
* or over one group; per effect -blend, -opacity, -scale
|
|
32
|
+
* data-umber-effect="ripple tint" effects (defined with umber.effect), applied in order
|
|
33
|
+
* data-umber-<effect>-<option>="1.2" an effect option (also --umber-<effect>-<option> in CSS)
|
|
34
|
+
* data-umber-<effect>-trigger auto (default) | scroll | load | manual | hover, for effects with `play`
|
|
35
|
+
* data-umber-<effect>-delay / -duration / -ease / -start the play's timing ("top 90%")
|
|
36
|
+
* data-umber-<effect>-repeat "reverse" | "true": plays again
|
|
37
|
+
* data-umber-shader="name" with data-umber="shader": the umber.shader() it draws
|
|
38
|
+
* data-umber-layer="name" with data-umber="layer": the umber.layer() it runs
|
|
39
|
+
* data-umber-src="url" another image than the <img> inside
|
|
40
|
+
* data-umber-fit="cover|contain|fill" object-fit for the texture
|
|
41
|
+
* data-umber-live measure every frame (sticky, fixed or transformed parents)
|
|
42
|
+
* data-umber-clip="false" draw it without its parents' clips (overflow, clip-path, masks)
|
|
43
|
+
* data-umber-wrap="x | y" on a track: its planes wrap around it (an endless gallery)
|
|
44
|
+
* data-umber-order="1" draw order
|
|
45
|
+
* data-umber-instances="64" drawn many times in one call: "64", "tiles 24x16",
|
|
46
|
+
* "chars" | "words" | "lines" (GL text), "echo 6", "ink 3000",
|
|
47
|
+
* "points 20000"
|
|
48
|
+
* data-umber-placeholder="UF…" a blurred preview until the image loads (chunks/warm.js;
|
|
49
|
+
* make it with umber.placeholder(src))
|
|
50
|
+
* data-umber-id="hero" the same id on two pages: the image flies across (morph),
|
|
51
|
+
* with any router (umber.transition() makes it tighter)
|
|
52
|
+
* data-umber-morph-duration="1" / -ease on the element you go to: the flight's timing
|
|
53
|
+
* (also --umber-morph-duration / --umber-morph-ease in CSS)
|
|
54
|
+
* data-umber-shader-<option> / data-umber-layer-<option> a umber.shader() / umber.layer() option
|
|
55
|
+
* data-umber="above" a DOM element that must sit on top of the canvas
|
|
56
|
+
* data-umber-disable (on <body>) GL off for this page
|
|
57
|
+
* data-umber-host where the canvas goes (else Umber makes one)
|
|
58
|
+
* data-umber-video-autopause="false" keep a muted loop video playing off screen
|
|
59
|
+
* data-umber-scrub (+ -start, -end, -track, -smooth, -source, -frames...) scroll-scrubbed
|
|
60
|
+
* video: needs the scrub module (types/scrub.d.ts)
|
|
61
|
+
* Modules (same version as umber.js): modules/scrub.js (types/scrub.d.ts) and
|
|
62
|
+
* modules/debug.js, the HUD, outlines and markers (types/debug.d.ts).
|
|
63
|
+
* umber.inspect(el) prints why an element is (not) drawn.
|
|
64
|
+
* Events also go to document (payload in event.detail): umber:ready (the engine), umber:lost,
|
|
65
|
+
* umber:restored, umber:destroy, umber:added (the roots that entered the page),
|
|
66
|
+
* umber:off ({ reason }) and umber:fallback ({ el, reason }).
|
|
67
|
+
* From JS: umber.add(el, { type, effects, options }) writes these attributes for you.
|
|
68
|
+
* Written by Umber: html.has-umber, data-umber-status="loading|ready|error", data-umber-media,
|
|
69
|
+
* data-umber-play, data-umber-morphing, data-umber-canvas on the canvas, and
|
|
70
|
+
* data-umber-view="loading|ready|off|error|lost" on umber.attach() / umber.view() elements.
|
|
71
|
+
*/
|
|
61
72
|
|
|
62
73
|
/**
|
|
63
74
|
* The next page, as a router hands it over: its HTML, a parsed Document, its container
|
|
@@ -70,27 +81,28 @@ export type NextPage =
|
|
|
70
81
|
| { html?: string }
|
|
71
82
|
| null
|
|
72
83
|
| undefined
|
|
73
|
-
| PromiseLike<string | ParentNode | { html?: string } | null | undefined
|
|
84
|
+
| PromiseLike<string | ParentNode | { html?: string } | null | undefined>;
|
|
74
85
|
|
|
75
86
|
/** A plain { value } anyone can animate (GSAP, Motion, your own code) or read. */
|
|
76
87
|
export interface Signal<T = number> {
|
|
77
88
|
value: T;
|
|
78
89
|
}
|
|
79
90
|
|
|
80
|
-
|
|
91
|
+
/** What Umber reads of a smooth-scroll instance (Lenis, or any with the same shape). Its scroll handler takes nothing: it reads the position itself. */
|
|
92
|
+
export interface SmoothScrollLike {
|
|
81
93
|
animatedScroll?: number;
|
|
82
94
|
scroll?: number;
|
|
83
95
|
velocity?: number;
|
|
84
96
|
isHorizontal?: boolean;
|
|
85
97
|
options?: { wrapper?: Window | Element; orientation?: string };
|
|
86
|
-
on(event: "scroll", fn: (
|
|
87
|
-
off?(event: "scroll", fn: (
|
|
98
|
+
on(event: "scroll", fn: () => void): unknown;
|
|
99
|
+
off?(event: "scroll", fn: () => void): unknown;
|
|
88
100
|
}
|
|
89
101
|
|
|
90
102
|
export interface ScrollObject {
|
|
91
103
|
x?: number | (() => number);
|
|
92
104
|
y?: number | (() => number);
|
|
93
|
-
/** px per frame
|
|
105
|
+
/** px per frame. Omit it to let Umber work it out from the position. */
|
|
94
106
|
velocity?: number | (() => number);
|
|
95
107
|
}
|
|
96
108
|
|
|
@@ -104,47 +116,61 @@ export interface Env {
|
|
|
104
116
|
readonly designer: boolean;
|
|
105
117
|
}
|
|
106
118
|
|
|
107
|
-
export interface
|
|
119
|
+
export interface UmberOptions {
|
|
120
|
+
/** Your account's public key, from your occluze dashboard. Also data-umber-key on the umber.js tag. */
|
|
121
|
+
key?: string;
|
|
108
122
|
/**
|
|
109
123
|
* Where Umber reads scroll from, read-only: it never creates, drives or configures it.
|
|
110
124
|
* The default also follows <body> when it is the page's scroller (html { overflow: hidden }).
|
|
111
125
|
* @default window
|
|
112
|
-
* @example
|
|
113
|
-
* @example
|
|
114
|
-
* @example
|
|
126
|
+
* @example createUmber({ scroll: lenis }) // your Lenis instance
|
|
127
|
+
* @example createUmber({ scroll: document.querySelector(".scroller") })
|
|
128
|
+
* @example createUmber({ scroll: { y: () => myScroll.y } }) // anything else
|
|
115
129
|
*/
|
|
116
|
-
scroll?: Window | Element |
|
|
130
|
+
scroll?: Window | Element | SmoothScrollLike | ScrollObject | null;
|
|
117
131
|
/**
|
|
118
132
|
* "auto": Umber runs its own requestAnimationFrame loop, which sleeps when nothing moves.
|
|
119
|
-
* false: nothing runs until you call
|
|
133
|
+
* false: nothing runs until you call umber.render(time) from your own loop.
|
|
120
134
|
* @default "auto"
|
|
121
|
-
* @example
|
|
135
|
+
* @example createUmber({ loop: false }); gsap.ticker.add((t) => umber.render(t * 1000));
|
|
122
136
|
*/
|
|
123
137
|
loop?: "auto" | false;
|
|
138
|
+
/**
|
|
139
|
+
* One clock for the whole page: the page's own requestAnimationFrame loops (GSAP's ticker,
|
|
140
|
+
* Lenis, three.js, Motion, minified code) run inside Umber's frame, one requestAnimationFrame
|
|
141
|
+
* per frame: Lenis first, then the page's loops, then Umber reads and draws. A Lenis that
|
|
142
|
+
* runs its own loop (autoRaf) and window.gsap are driven through their own APIs. The loop
|
|
143
|
+
* still sleeps when nothing asks for frames. Without code: data-umber-patch on umber.js's
|
|
144
|
+
* script tag (patched as the script runs, so loops started before createUmber() are caught).
|
|
145
|
+
* @default false
|
|
146
|
+
* @example createUmber({ scroll: lenis, patch: true })
|
|
147
|
+
* @example createUmber({ patch: { gsap } }) // a bundled GSAP, not on window
|
|
148
|
+
*/
|
|
149
|
+
patch?: boolean | { gsap?: GsapLike };
|
|
124
150
|
/**
|
|
125
151
|
* Which devices draw DOM planes in GL (the rest keep the plain DOM, and nothing downloads).
|
|
126
152
|
* "desktop" = hover + fine pointer + at least 768 px wide. Anything else is "desktop", with a warning.
|
|
127
153
|
* @default "all"
|
|
128
|
-
* @example
|
|
129
|
-
* @example
|
|
154
|
+
* @example createUmber({ devices: "desktop" })
|
|
155
|
+
* @example createUmber({ devices: (env) => !env.isTouch })
|
|
130
156
|
*/
|
|
131
157
|
devices?: "all" | "desktop" | false | ((env: Env) => boolean);
|
|
132
158
|
/**
|
|
133
|
-
* Effects only where this CSS media query matches, read when the page loads. Without code: data-
|
|
134
|
-
* @example
|
|
135
|
-
* @example
|
|
159
|
+
* Effects only where this CSS media query matches, read when the page loads. Without code: data-umber-media on <body>.
|
|
160
|
+
* @example createUmber({ media: "(min-width: 900px)" }) // off in narrower windows
|
|
161
|
+
* @example createUmber({ media: "(min-width: 600px)" }) // off on phones
|
|
136
162
|
*/
|
|
137
163
|
media?: string;
|
|
138
164
|
/**
|
|
139
165
|
* Device pixel ratio: a max, [min, max], or a max per device tier.
|
|
140
166
|
* @default { high: 2, mid: 1.5, low: 1 }
|
|
141
|
-
* @example
|
|
167
|
+
* @example createUmber({ dpr: [1, 1.5] })
|
|
142
168
|
*/
|
|
143
169
|
dpr?: number | [number, number] | { high?: number; mid?: number; low?: number };
|
|
144
170
|
/**
|
|
145
171
|
* Max canvas pixels (width × height × dpr²); the DPR drops to stay under it.
|
|
146
172
|
* @default 12e6
|
|
147
|
-
* @example
|
|
173
|
+
* @example createUmber({ pixelBudget: 8e6 })
|
|
148
174
|
*/
|
|
149
175
|
pixelBudget?: number;
|
|
150
176
|
/**
|
|
@@ -164,6 +190,12 @@ export interface GLOptions {
|
|
|
164
190
|
* @default true
|
|
165
191
|
*/
|
|
166
192
|
respectSaveData?: boolean;
|
|
193
|
+
/**
|
|
194
|
+
* Run where WebGL draws on the processor (SwiftShader, llvmpipe, Microsoft Basic Render: no usable GPU), where every
|
|
195
|
+
* frame costs the page its smoothness. Also `data-umber-software` on `<html>` or `<body>`. Off, `umber.reason` is "software".
|
|
196
|
+
* @default false
|
|
197
|
+
*/
|
|
198
|
+
software?: boolean;
|
|
167
199
|
/**
|
|
168
200
|
* Run inside the Webflow Designer / Editor too (normally the DOM shows there).
|
|
169
201
|
* @default false
|
|
@@ -171,8 +203,8 @@ export interface GLOptions {
|
|
|
171
203
|
designer?: boolean;
|
|
172
204
|
/**
|
|
173
205
|
* The element the canvas goes in: an element or a selector.
|
|
174
|
-
* @default [data-
|
|
175
|
-
* @example
|
|
206
|
+
* @default [data-umber-host], or a fixed full-screen host Umber makes as the first child of <body> (next to it when <body> has a zoom)
|
|
207
|
+
* @example createUmber({ host: ".gl-host" })
|
|
176
208
|
*/
|
|
177
209
|
host?: string | HTMLElement;
|
|
178
210
|
/**
|
|
@@ -187,41 +219,41 @@ export interface GLOptions {
|
|
|
187
219
|
zIndex?: number;
|
|
188
220
|
/**
|
|
189
221
|
* A selector <html> matches while your router changes the page: meanwhile Umber acts as
|
|
190
|
-
* inside
|
|
222
|
+
* inside umber.transition() (plays held, planes measured every frame, data-umber-id images
|
|
191
223
|
* noted), with no hook to write. Off by default (a flag a site forgets to clear would
|
|
192
224
|
* keep Umber measuring); it ends by itself after 8 s and starts again only once <html>
|
|
193
225
|
* stopped matching in between.
|
|
194
|
-
* @example
|
|
195
|
-
* @example
|
|
196
|
-
* @example
|
|
226
|
+
* @example createUmber({ busy: "html.is-changing" }) // Swup
|
|
227
|
+
* @example createUmber({ busy: 'html[aria-busy="true"]' }) // Turbo
|
|
228
|
+
* @example createUmber({ busy: "html[data-astro-transition]" }) // Astro's client router
|
|
197
229
|
*/
|
|
198
230
|
busy?: string;
|
|
199
231
|
/**
|
|
200
232
|
* The folder the engine's chunks (chunks/gl.js, chunks/shapes.js, chunks/text.js, chunks/layers.js, chunks/morph.js, chunks/video.js, chunks/views.js) load from.
|
|
201
233
|
* @default the folder umber.js came from (npm: this version's CDN folder, or window.UmberConfig.base)
|
|
202
|
-
* @example
|
|
234
|
+
* @example createUmber({ base: "/vendor/umber/" })
|
|
203
235
|
*/
|
|
204
236
|
base?: string;
|
|
205
237
|
/**
|
|
206
238
|
* true: debug notes in the console (also ?umber-debug in the URL). An object also sets
|
|
207
239
|
* what the debug module shows, once it is loaded (modules/debug.js).
|
|
208
240
|
* @default false
|
|
209
|
-
* @example
|
|
210
|
-
* @example
|
|
241
|
+
* @example createUmber({ debug: true })
|
|
242
|
+
* @example createUmber({ modules: [Debug], debug: { outlines: true, markers: true } })
|
|
211
243
|
*/
|
|
212
244
|
debug?: boolean | DebugOptions;
|
|
213
245
|
/**
|
|
214
246
|
* false silences warnings. Errors (a shader that does not compile, a callback that threw)
|
|
215
247
|
* always show.
|
|
216
|
-
* @default true
|
|
248
|
+
* @default true on localhost and with debug on, false on a live site
|
|
217
249
|
*/
|
|
218
250
|
warnings?: boolean;
|
|
219
251
|
/**
|
|
220
|
-
* Optional modules from the start, as
|
|
221
|
-
* @example
|
|
222
|
-
* @example
|
|
252
|
+
* Optional modules from the start, as umber.use() would take them.
|
|
253
|
+
* @example createUmber({ modules: [Scrub] }) // import { Scrub } from "@occluze/umber/scrub"
|
|
254
|
+
* @example createUmber({ modules: [[Scrub, { cacheMB: 64 }]] })
|
|
223
255
|
*/
|
|
224
|
-
modules?:
|
|
256
|
+
modules?: (UmberModule | [UmberModule, Record<string, unknown>])[];
|
|
225
257
|
}
|
|
226
258
|
|
|
227
259
|
/** What the debug module (modules/debug.js) shows. */
|
|
@@ -240,9 +272,11 @@ export interface DebugOptions {
|
|
|
240
272
|
* @default false
|
|
241
273
|
*/
|
|
242
274
|
cost?: boolean;
|
|
275
|
+
/** The frame callbacks' costs against the frame's budget (umber.loop.profile(), chunks/profiler.js). ?umber-debug=profiler. @default false */
|
|
276
|
+
profiler?: boolean;
|
|
243
277
|
}
|
|
244
278
|
|
|
245
|
-
/**
|
|
279
|
+
/** umber.inspect(el): one plane, and every reason it is not drawn on the visible screen right now. */
|
|
246
280
|
export interface InspectReport {
|
|
247
281
|
el: Element;
|
|
248
282
|
kind: "image" | "video" | "shader" | "layer" | "text" | "group" | null;
|
|
@@ -257,7 +291,7 @@ export interface InspectReport {
|
|
|
257
291
|
source?: string;
|
|
258
292
|
/** The device tier ("high" | "mid" | "low"), plus the scrub tier on scrubbed video. */
|
|
259
293
|
tier?: string;
|
|
260
|
-
effects?:
|
|
294
|
+
effects?: { name: string; options: Record<string, unknown> }[];
|
|
261
295
|
/** used: the compiled shader reads it (null while it compiles). */
|
|
262
296
|
uniforms?: Record<string, { value: unknown; used: boolean | null }>;
|
|
263
297
|
program?: { key: string; ready: boolean } | null;
|
|
@@ -270,10 +304,15 @@ export interface InspectReport {
|
|
|
270
304
|
* Every parent (or the element itself) that cuts it, and how GL draws the cut: "scissor"
|
|
271
305
|
* (straight: free), "shader" (rounded, shaped or turned: per pixel), "corners" (a rounded
|
|
272
306
|
* parent hugging the image), "pruned" (cuts nothing), "ignored" (that parent turns past
|
|
273
|
-
* the viewer right now). A data-
|
|
307
|
+
* the viewer right now). A data-umber-occlude panel over it is `by: "occlude"`; "uncut": it
|
|
274
308
|
* overlaps, but no shader slot was free, so GL draws over it there this frame.
|
|
275
309
|
*/
|
|
276
|
-
clips?:
|
|
310
|
+
clips?: {
|
|
311
|
+
el: Element;
|
|
312
|
+
by: "overflow" | "clip-path" | "clip" | "occlude";
|
|
313
|
+
shape: string;
|
|
314
|
+
how: "scissor" | "shader" | "corners" | "pruned" | "ignored" | "uncut";
|
|
315
|
+
}[];
|
|
277
316
|
/** Where GL draws it (null when it has no plane). */
|
|
278
317
|
geometry?: {
|
|
279
318
|
/** "none": flat (translate / scale at most); "2d": rotated, skewed or mirrored; "3d": tilted (perspective). */
|
|
@@ -281,32 +320,55 @@ export interface InspectReport {
|
|
|
281
320
|
/** uSize: its size on screen (for a turned element: its layout proportions at its on-screen scale). */
|
|
282
321
|
size: [number, number];
|
|
283
322
|
/** The drawn quad, viewport px: top-left, top-right, bottom-right, bottom-left of the element's own box. */
|
|
284
|
-
corners:
|
|
323
|
+
corners: [number, number][];
|
|
285
324
|
/**
|
|
286
325
|
* What measures it every frame right now, or null: "CSS transition on <div.card>, 0.32 s
|
|
287
326
|
* left", "infinite CSS animation on <div.track>", "scroll-driven CSS animation on ...",
|
|
288
|
-
* "data-
|
|
327
|
+
* "data-umber-live", "a sticky or fixed parent", "live mode (a page change, umber.live())".
|
|
289
328
|
*/
|
|
290
329
|
live: string | null;
|
|
291
330
|
} | null;
|
|
292
331
|
}
|
|
293
332
|
|
|
333
|
+
/** What a setup callback may return: run when what it set up goes. */
|
|
334
|
+
export type Cleanup = () => void;
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* A setup callback: it returns nothing, or `R`, a cleanup (an async setup: a promise of
|
|
338
|
+
* one). Two signatures, so a setup with no return statement is one too.
|
|
339
|
+
*/
|
|
340
|
+
export type Setup<C, R = Cleanup> = ((ctx: C) => void) | ((ctx: C) => R);
|
|
341
|
+
|
|
342
|
+
/** The console an add-on prints through, behind the engine's switch (createUmber({ warnings })). */
|
|
343
|
+
export interface ModuleLog {
|
|
344
|
+
warn(...args: unknown[]): void;
|
|
345
|
+
error(...args: unknown[]): void;
|
|
346
|
+
}
|
|
347
|
+
|
|
294
348
|
/**
|
|
295
349
|
* An optional Umber module (modules/scrub.js, @occluze/umber/scrub). Elements with
|
|
296
|
-
* data-
|
|
297
|
-
* Writing your own is possible
|
|
350
|
+
* data-umber-<name> are handed to it; its handle is at plane[name] (umber.plane(el)?.scrub).
|
|
351
|
+
* Writing your own is possible; the plane hooks for that are in types/module.d.ts.
|
|
298
352
|
*/
|
|
299
353
|
export interface UmberModule {
|
|
300
354
|
name: string;
|
|
301
355
|
version?: string;
|
|
302
|
-
/** Attributes it owns, without "data-
|
|
356
|
+
/** Attributes it owns, without "data-umber-". @default [name] */
|
|
303
357
|
attributes?: string[];
|
|
304
|
-
/**
|
|
305
|
-
|
|
306
|
-
|
|
358
|
+
/**
|
|
359
|
+
* `keep(off)` records an undo in the umber.scope() running when it is called, and returns it. `root()`: that scope's container, else document.
|
|
360
|
+
* `log`: the console behind the engine's switch (quiet on a live site, createUmber({ warnings })); print through it.
|
|
361
|
+
*/
|
|
362
|
+
install?(
|
|
363
|
+
engine: Umber,
|
|
364
|
+
options: Record<string, unknown>,
|
|
365
|
+
keep: <T>(made: T) => T,
|
|
366
|
+
root: () => ParentNode,
|
|
367
|
+
log: ModuleLog,
|
|
368
|
+
): void;
|
|
307
369
|
}
|
|
308
370
|
|
|
309
|
-
export type
|
|
371
|
+
export type UmberReason =
|
|
310
372
|
| "disabled"
|
|
311
373
|
| "no-webgl2"
|
|
312
374
|
| "device"
|
|
@@ -314,10 +376,12 @@ export type GLReason =
|
|
|
314
376
|
| "forced-colors"
|
|
315
377
|
| "reduced-motion"
|
|
316
378
|
| "save-data"
|
|
379
|
+
| "software"
|
|
317
380
|
| "context"
|
|
318
381
|
| "load-failed"
|
|
319
382
|
| "load-timeout"
|
|
320
383
|
| "unlicensed"
|
|
384
|
+
| "licence-unreachable"
|
|
321
385
|
| "context-lost"
|
|
322
386
|
| "error"
|
|
323
387
|
| "server"
|
|
@@ -325,6 +389,9 @@ export type GLReason =
|
|
|
325
389
|
|
|
326
390
|
export type TickPhase = "measure" | "update" | "render";
|
|
327
391
|
|
|
392
|
+
export type { FrameOptions, GsapLike, Loop, ProfileLine, Profiler, ProfilerOptions } from "./loop.js";
|
|
393
|
+
import type { FrameOptions, GsapLike, Loop } from "./loop.js";
|
|
394
|
+
|
|
328
395
|
export interface Frame {
|
|
329
396
|
/** Seconds since the engine started, lag-smoothed. */
|
|
330
397
|
time: number;
|
|
@@ -337,6 +404,12 @@ export interface Frame {
|
|
|
337
404
|
woke: boolean;
|
|
338
405
|
/** px; velocity in px per second. */
|
|
339
406
|
scroll: { x: number; y: number; velocity: number };
|
|
407
|
+
/**
|
|
408
|
+
* ms left before this frame takes longer than the screen's frame time: heavy work can
|
|
409
|
+
* skip a frame, or stop and go on in the next one. Live: call it again after some work.
|
|
410
|
+
* @example umber.on("frame", (f) => { while (jobs.length && f.budget() > 2) jobs.shift()!(); });
|
|
411
|
+
*/
|
|
412
|
+
budget(): number;
|
|
340
413
|
}
|
|
341
414
|
|
|
342
415
|
/**
|
|
@@ -375,7 +448,7 @@ export type PlaneEvent = "ready" | "enter" | "leave" | "resize" | "error" | "des
|
|
|
375
448
|
* One line, word or character of a GL text (plane.text). `t`, `x`, `y`, `z` are four
|
|
376
449
|
* plain numbers per unit (0 at first) that any library can tween; their meaning is the
|
|
377
450
|
* effect's. They are kept by index when the text rewraps.
|
|
378
|
-
* @example gsap.to(
|
|
451
|
+
* @example gsap.to(umber.plane(h1).text.lines, { t: 1, stagger: 0.08 })
|
|
379
452
|
*/
|
|
380
453
|
export interface TextUnit {
|
|
381
454
|
/** 0-based, in reading order: the same numbers as glyph() in GLSL. */
|
|
@@ -407,10 +480,10 @@ export interface TextChar extends TextUnit {
|
|
|
407
480
|
}
|
|
408
481
|
|
|
409
482
|
/**
|
|
410
|
-
* plane.text on data-
|
|
483
|
+
* plane.text on data-umber="text" planes (undefined on others, and until chunks/text.js
|
|
411
484
|
* arrived): its lines, words and characters, empty until the first paint. Where the site
|
|
412
485
|
* split its own lines ([data-line] elements), those are the lines. The counts also reach
|
|
413
|
-
* CSS on the element: var(--
|
|
486
|
+
* CSS on the element: var(--umber-lines), var(--umber-words), var(--umber-chars).
|
|
414
487
|
*/
|
|
415
488
|
export interface PlaneText {
|
|
416
489
|
readonly lines: TextLine[];
|
|
@@ -419,7 +492,7 @@ export interface PlaneText {
|
|
|
419
492
|
/** +1 per paint that changed the units. */
|
|
420
493
|
readonly version: number;
|
|
421
494
|
/**
|
|
422
|
-
* One
|
|
495
|
+
* One umber.progress() per line or word (not characters): `start` / `end` written as for
|
|
423
496
|
* the element, measured from each unit's own edges ("top 80%": this line's top at 80 %
|
|
424
497
|
* of the screen). Make them again after a "text" event.
|
|
425
498
|
* @example plane.text.progress("lines", { start: "top 85%", end: "top 55%" }).forEach((p, i) => p.on("change", () => (lines[i].t = p.value)))
|
|
@@ -427,6 +500,18 @@ export interface PlaneText {
|
|
|
427
500
|
progress(level: "lines" | "words", options?: ProgressOptions): ProgressSignal[];
|
|
428
501
|
}
|
|
429
502
|
|
|
503
|
+
/** The indices below each fixed length Umber hands out arrays of. */
|
|
504
|
+
interface Below {
|
|
505
|
+
4: 0 | 1 | 2 | 3;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/**
|
|
509
|
+
* A Float32Array made with N entries, which it keeps: each index below N reads as a
|
|
510
|
+
* number, also under noUncheckedIndexedAccess (plane.rect[2] is a number, not
|
|
511
|
+
* number | undefined).
|
|
512
|
+
*/
|
|
513
|
+
export type Float32s<N extends keyof Below> = Float32Array & Record<Below[N], number>;
|
|
514
|
+
|
|
430
515
|
export interface Plane {
|
|
431
516
|
readonly id: number;
|
|
432
517
|
readonly el: HTMLElement;
|
|
@@ -434,23 +519,30 @@ export interface Plane {
|
|
|
434
519
|
/** "loading" | "ready" | "error" */
|
|
435
520
|
readonly status: string;
|
|
436
521
|
/** This frame's viewport rect as [x, y, width, height] (CSS px): rect[2] is the width. */
|
|
437
|
-
readonly rect:
|
|
438
|
-
/**
|
|
522
|
+
readonly rect: Float32s<4>;
|
|
523
|
+
/**
|
|
524
|
+
* [x, y] CSS px your code moves the element by this frame with the CSS `translate`
|
|
525
|
+
* property (set it in the measure phase, where the scrollfx module sets its parallax and
|
|
526
|
+
* lag): the plane is drawn that far over in the same frame, and measuring leaves it out, so
|
|
527
|
+
* it needs no measure per frame. null: none.
|
|
528
|
+
*/
|
|
529
|
+
offset: [number, number] | null;
|
|
530
|
+
/** On screen (the real viewport, like umber.track()); "enter" / "leave" fire as it changes. */
|
|
439
531
|
readonly inView: boolean;
|
|
440
532
|
/** 0 as the element's top enters at the bottom of the screen, 1 as its bottom leaves at the top. */
|
|
441
533
|
readonly progress: number;
|
|
442
|
-
readonly effects:
|
|
443
|
-
/** data-
|
|
534
|
+
readonly effects: { name: string; options: Record<string, unknown> }[];
|
|
535
|
+
/** data-umber="text": its lines, words and characters, as data and tweenable numbers. */
|
|
444
536
|
readonly text?: PlaneText;
|
|
445
|
-
/** data-
|
|
537
|
+
/** data-umber-instances (or an effect's `instances`): its count and per-instance data. Undefined without. */
|
|
446
538
|
readonly instances?: PlaneInstances;
|
|
447
539
|
/** Plain { value } objects: animate them with anything. */
|
|
448
|
-
readonly uniforms: Record<string, Signal<
|
|
540
|
+
readonly uniforms: Record<string, Signal<unknown>>;
|
|
449
541
|
/**
|
|
450
|
-
* Set a uniform. A Signal (
|
|
542
|
+
* Set a uniform. A Signal (umber.progress(el), umber.pointer, any { value }) links it: the
|
|
451
543
|
* uniform follows that Signal from then on. A CSS colour string ("#f30", "oklch(...)",
|
|
452
544
|
* "var(--brand)") becomes [r, g, b, a] in sRGB (var() read from the element now).
|
|
453
|
-
* @example plane.set("uStory",
|
|
545
|
+
* @example plane.set("uStory", umber.progress(el.closest("section")))
|
|
454
546
|
*/
|
|
455
547
|
set(name: string, value: unknown): Plane;
|
|
456
548
|
get(name: string): unknown;
|
|
@@ -470,49 +562,49 @@ export interface Plane {
|
|
|
470
562
|
on(event: PlaneEvent, fn: (plane: Plane) => void): () => void;
|
|
471
563
|
off(event: PlaneEvent, fn: (plane: Plane) => void): void;
|
|
472
564
|
wake(frames?: number): void;
|
|
473
|
-
/** The element shows as normal DOM again.
|
|
565
|
+
/** The element shows as normal DOM again. umber.scan(el) brings it back. */
|
|
474
566
|
destroy(): void;
|
|
475
567
|
revert(): void;
|
|
476
568
|
}
|
|
477
569
|
|
|
478
|
-
/**
|
|
570
|
+
/** umber.add(el, options): the attributes it writes, as options (the same contract). */
|
|
479
571
|
export interface AddOptions {
|
|
480
|
-
/** data-
|
|
572
|
+
/** data-umber. @default "image" (or "video" for a <video>) */
|
|
481
573
|
type?: "image" | "video" | "text" | "shader" | "layer" | "group";
|
|
482
|
-
/** data-
|
|
574
|
+
/** data-umber-effect: effect names, applied in order. @example effects: ["dissolve"] */
|
|
483
575
|
effects?: string[] | string;
|
|
484
|
-
/** data-
|
|
576
|
+
/** data-umber-<effect>-<option>, per effect. @example options: { dissolve: { scale: 6, trigger: "manual" } } */
|
|
485
577
|
options?: Record<string, Record<string, unknown>>;
|
|
486
|
-
/** data-
|
|
578
|
+
/** data-umber-shader (with type "shader"). */
|
|
487
579
|
shader?: string;
|
|
488
|
-
/** data-
|
|
580
|
+
/** data-umber-layer (with type "layer"). */
|
|
489
581
|
layer?: string;
|
|
490
|
-
/** data-
|
|
582
|
+
/** data-umber-src: another image than the <img> inside. */
|
|
491
583
|
src?: string;
|
|
492
|
-
/** data-
|
|
584
|
+
/** data-umber-fit. */
|
|
493
585
|
fit?: "cover" | "contain" | "fill";
|
|
494
|
-
/** data-
|
|
586
|
+
/** data-umber-order: draw order. */
|
|
495
587
|
order?: number;
|
|
496
|
-
/** data-
|
|
588
|
+
/** data-umber-live: measure every frame. */
|
|
497
589
|
live?: boolean;
|
|
498
590
|
/**
|
|
499
|
-
* data-
|
|
591
|
+
* data-umber-clip: false draws it without its parents' clips (overflow, clip-path, CSS masks).
|
|
500
592
|
* Its own clip-path still cuts it. @default true
|
|
501
593
|
*/
|
|
502
594
|
clip?: boolean;
|
|
503
|
-
/** data-
|
|
595
|
+
/** data-umber-instances: "64", "tiles 24x16", "chars", "echo 6", "ink 3000", "points 20000". */
|
|
504
596
|
instances?: string | number;
|
|
505
597
|
}
|
|
506
598
|
|
|
507
599
|
/**
|
|
508
|
-
* plane.instances on a plane drawn as instances (data-
|
|
600
|
+
* plane.instances on a plane drawn as instances (data-umber-instances, or an effect's
|
|
509
601
|
* `instances`): the per-instance numbers of the attributes its effects declare.
|
|
510
602
|
* @example const seeds = plane.instances.data("aSeed"); seeds[0] = 0.5; plane.instances.update("aSeed");
|
|
511
603
|
*/
|
|
512
604
|
export interface PlaneInstances {
|
|
513
605
|
/** How many are drawn (text: its characters, words or lines). */
|
|
514
606
|
readonly count: number;
|
|
515
|
-
readonly mode: "count" | "tiles" | "chars" | "words" | "lines" | "echo" | "ink";
|
|
607
|
+
readonly mode: "count" | "tiles" | "chars" | "words" | "lines" | "echo" | "ink" | "points";
|
|
516
608
|
/** An attribute's numbers (count x its size), to change in place; then update(name). null when no effect declares it. */
|
|
517
609
|
data(name: string): Float32Array | null;
|
|
518
610
|
/** Replace an attribute's numbers (count x its size); sent to the GPU on the next frame. */
|
|
@@ -521,13 +613,35 @@ export interface PlaneInstances {
|
|
|
521
613
|
update(name?: string): void;
|
|
522
614
|
}
|
|
523
615
|
|
|
524
|
-
|
|
616
|
+
/** A definition's options (umber.effect, umber.shader, umber.layer): each with its default. */
|
|
617
|
+
export type OptionDefaults = Record<string, unknown>;
|
|
618
|
+
|
|
619
|
+
/**
|
|
620
|
+
* One option as an element gives it (data-umber-<name>-<option> > --umber-<name>-<option> > the
|
|
621
|
+
* default), read as its default's type: a number, a boolean or a string; a list default
|
|
622
|
+
* reads an attribute as its words.
|
|
623
|
+
*/
|
|
624
|
+
export type OptionValue<T> = T extends number
|
|
625
|
+
? number
|
|
626
|
+
: T extends boolean
|
|
627
|
+
? boolean
|
|
628
|
+
: T extends string
|
|
629
|
+
? string
|
|
630
|
+
: T extends readonly unknown[]
|
|
631
|
+
? T | string[]
|
|
632
|
+
: T | string;
|
|
633
|
+
|
|
634
|
+
/** A definition's options as one element resolved them (ctx.options). */
|
|
635
|
+
export type ResolvedOptions<O extends OptionDefaults> = { [K in keyof O]: OptionValue<O[K]> };
|
|
636
|
+
|
|
637
|
+
/** `O`: the effect's (or shader's) option defaults, which type ctx.options. */
|
|
638
|
+
export interface EffectContext<O extends OptionDefaults = OptionDefaults> {
|
|
525
639
|
name: string;
|
|
526
640
|
el: HTMLElement;
|
|
527
641
|
plane: Plane;
|
|
528
|
-
engine:
|
|
529
|
-
options:
|
|
530
|
-
uniforms: Record<string, Signal<
|
|
642
|
+
engine: Umber;
|
|
643
|
+
options: ResolvedOptions<O>;
|
|
644
|
+
uniforms: Record<string, Signal<unknown>>;
|
|
531
645
|
readonly reducedMotion: boolean;
|
|
532
646
|
viewport: { width: number; height: number };
|
|
533
647
|
/** Only set during update(). */
|
|
@@ -563,7 +677,7 @@ export interface EffectContext {
|
|
|
563
677
|
* only: this pixel on screen, viewport CSS px, whatever turns the element),
|
|
564
678
|
* screenUv() (fragment only: this pixel on screen, 0..1 over the viewport,
|
|
565
679
|
* y down), uScreen (vec2: the element's centre on the viewport, -1..1, y down)
|
|
566
|
-
* #include "name" on a line of its own, in any slot: the
|
|
680
|
+
* #include "name" on a line of its own, in any slot: the umber.chunk() of that name, added
|
|
567
681
|
* once per program (only included chunks are compiled)
|
|
568
682
|
* two effects on one plane that declare the same top-level name in their heads (a
|
|
569
683
|
* function, const, global or #define) each get their own (renamed e<N>_name)
|
|
@@ -572,45 +686,46 @@ export interface EffectContext {
|
|
|
572
686
|
* after the alpha slot, Umber cuts the plane where its parents cut it in the DOM
|
|
573
687
|
* (overflow, clip-path); names starting with uUmber / umber are reserved
|
|
574
688
|
*/
|
|
575
|
-
export interface EffectDef {
|
|
689
|
+
export interface EffectDef<O extends OptionDefaults = OptionDefaults> {
|
|
576
690
|
/**
|
|
577
691
|
* Uniforms it adds, with their first value; Umber writes the GLSL declarations.
|
|
578
692
|
* number -> float, [x, y(, z, w)] -> vec2..4, 9 numbers -> mat3, 16 -> mat4, a URL
|
|
579
693
|
* string -> sampler2D (fragment only), and a Signal
|
|
580
|
-
* ({ value }:
|
|
694
|
+
* ({ value }: umber.progress(el), umber.pointer, umber.velocity, your own) is followed live. A CSS
|
|
581
695
|
* colour string ("#ff3300", "oklch(70% 0.15 30)", "var(--brand)") -> vec4 [r, g, b, a]
|
|
582
696
|
* in sRGB, converted by the browser (var() read from each element once). Anything
|
|
583
|
-
* holding a `texture` (the input module's
|
|
697
|
+
* holding a `texture` (the input module's umber.texture(), umber.touch(), umber.rects()) ->
|
|
584
698
|
* highp sampler2D; a raw canvas, video, a typed array other than Float32Array, or more
|
|
585
|
-
* than 896 numbers (more than a phone's uniforms hold) warns: wrap it in
|
|
699
|
+
* than 896 numbers (more than a phone's uniforms hold) warns: wrap it in umber.texture()
|
|
586
700
|
* (numbers that fit no type above warn only when the GLSL reads them undeclared).
|
|
587
701
|
* @example uniforms: { uShow: 0, uTint: [1, 0.4, 0.2], uNoise: "/noise.png" }
|
|
588
702
|
* @example uniforms: { uTint: "var(--brand)" }
|
|
589
|
-
* @example uniforms: { uStory:
|
|
703
|
+
* @example uniforms: { uStory: umber.progress(".story"), uPointer: umber.pointer }
|
|
590
704
|
*/
|
|
591
705
|
uniforms?: Record<string, unknown>;
|
|
592
706
|
/**
|
|
593
|
-
* Options read per element: data-
|
|
707
|
+
* Options read per element: data-umber-<effect>-<key> > --umber-<effect>-<key> (CSS) > this
|
|
594
708
|
* default. Number, boolean, array and CSS colour options become uniforms too: effect
|
|
595
709
|
* "ripple", option "strength" -> uRippleStrength. Give a colour option a colour default
|
|
596
710
|
* ({ color: "#fff" }) so every element has the vec4. A string with a "/" is an image
|
|
597
|
-
* path -> sampler2D (a per-element map: data-
|
|
711
|
+
* path -> sampler2D (a per-element map: data-umber-depth-map="/img/a-depth.webp" ->
|
|
598
712
|
* uDepthMap; give it a default path). `bleed` (px) draws the plane that much past its
|
|
599
713
|
* element on every side (uBleed: the largest of its effects).
|
|
714
|
+
* setup() and update() read them as ctx.options, typed from these defaults.
|
|
600
715
|
* @example options: { strength: 1, duration: 1.2, ease: "expo.out" }
|
|
601
716
|
* @example options: { map: "/img/blank.webp", bleed: 40 }
|
|
602
717
|
*/
|
|
603
|
-
options?:
|
|
718
|
+
options?: O;
|
|
604
719
|
/**
|
|
605
720
|
* Uniform values used instead when the visitor prefers reduced motion (and
|
|
606
|
-
*
|
|
721
|
+
* createUmber({ reducedMotion }) is "static", the default): keep a fade, still a wave.
|
|
607
722
|
* @example reduced: { uWave: 0 }
|
|
608
723
|
*/
|
|
609
724
|
reduced?: Record<string, unknown>;
|
|
610
725
|
/**
|
|
611
726
|
* A uniform Umber plays 0 -> 1 by itself, with the trigger options every playable
|
|
612
727
|
* effect understands: trigger (auto | scroll | load | manual | hover), delay, duration, ease,
|
|
613
|
-
* start ("top 90%").
|
|
728
|
+
* start ("top 90%"), repeat ("" once | "reverse" | "true": again each time it scrolls in).
|
|
614
729
|
* @example play: "uShow"
|
|
615
730
|
*/
|
|
616
731
|
play?: string;
|
|
@@ -621,7 +736,7 @@ export interface EffectDef {
|
|
|
621
736
|
segments?: number;
|
|
622
737
|
/**
|
|
623
738
|
* Draw the plane many times in ONE draw call (chunks/instances.js). The element's own
|
|
624
|
-
* data-
|
|
739
|
+
* data-umber-instances wins. GLSL then has `instance` (0..uInstances - 1) and `uInstances`,
|
|
625
740
|
* plus per mode:
|
|
626
741
|
* "64" (or { count: 64 }) copies: place each with `instance` in vertex.main
|
|
627
742
|
* "tiles 24x16" one quad per tile: `tile` (vec4 column, row, columns, rows),
|
|
@@ -634,10 +749,26 @@ export interface EffectDef {
|
|
|
634
749
|
* "ink 3000" ("size 3", "luma") 3000 particles seeded where the plane has ink (alpha, or
|
|
635
750
|
* brightness), each a `size` px piece of the plane:
|
|
636
751
|
* `inkPoint` (vec4: uv, ink 0..1, found)
|
|
752
|
+
* "points 20000" ("size 3") 20000 particles spread evenly at random over the plane, placed
|
|
753
|
+
* on the GPU (no seed pass): `point` (vec4: uv, two random
|
|
754
|
+
* numbers 0..1), `pointUv` (vec2: 0..1 across the particle)
|
|
637
755
|
* Every input is there in vertex and fragment code; your attributes in vertex code only.
|
|
638
756
|
* @example instances: "tiles 16x10", vertex: { main: "pos.xy += (tileCenter - 0.5) * uSize * uSpread;" }
|
|
639
757
|
*/
|
|
640
|
-
instances?:
|
|
758
|
+
instances?:
|
|
759
|
+
| number
|
|
760
|
+
| string
|
|
761
|
+
| {
|
|
762
|
+
count?: number;
|
|
763
|
+
tiles?: string | [number, number];
|
|
764
|
+
units?: "chars" | "words" | "lines";
|
|
765
|
+
echo?: number;
|
|
766
|
+
delay?: number;
|
|
767
|
+
ink?: number;
|
|
768
|
+
points?: number;
|
|
769
|
+
size?: number;
|
|
770
|
+
source?: "alpha" | "luma";
|
|
771
|
+
};
|
|
641
772
|
/**
|
|
642
773
|
* Per-instance numbers, as `in` attributes of the vertex shader (declared for you): a size
|
|
643
774
|
* (1-4: a stable random 0..1 per instance and component) or a function of the instance
|
|
@@ -651,32 +782,33 @@ export interface EffectDef {
|
|
|
651
782
|
* fragment.uv changes `uv` before the image is sampled; color changes `color` (vec4);
|
|
652
783
|
* alpha changes `alpha` (float, already the element's opacity and corners: multiply it).
|
|
653
784
|
* head holds functions and globals shared between slots, and #include "name" lines
|
|
654
|
-
* (
|
|
785
|
+
* (umber.chunk()).
|
|
655
786
|
* Helpers: sampleImage(uv), sampleRaw(uv), roundedBox(p, size, vec4 radii), noise(vec2 | vec3), fbm(vec2),
|
|
656
787
|
* rotate2d(a), umberHash(vec2 | vec3), screenPx(), screenUv().
|
|
657
788
|
* @example fragment: { color: "color.rgb *= uTint;" }
|
|
658
789
|
*/
|
|
659
790
|
fragment?: { head?: string; uv?: string; color?: string; alpha?: string };
|
|
660
|
-
/** Once per plane. Return a cleanup (also: ctx.listen() cleans up by itself). */
|
|
661
|
-
setup?:
|
|
791
|
+
/** Once per plane. Return a cleanup (also: ctx.listen() cleans up by itself), or nothing. */
|
|
792
|
+
setup?: Setup<EffectContext<O>>;
|
|
662
793
|
/** Every drawn frame while the plane is on screen (ctx.frame is set). */
|
|
663
|
-
update
|
|
794
|
+
update?(ctx: EffectContext<O>): void;
|
|
664
795
|
}
|
|
665
796
|
|
|
666
|
-
export interface ShaderDef {
|
|
797
|
+
export interface ShaderDef<O extends OptionDefaults = OptionDefaults> {
|
|
667
798
|
/** Set `color` (vec4) from `uv`. */
|
|
668
799
|
fragment: string;
|
|
669
800
|
head?: string;
|
|
670
801
|
uniforms?: Record<string, unknown>;
|
|
671
802
|
/**
|
|
672
|
-
* Options read per element: data-
|
|
803
|
+
* Options read per element: data-umber-shader-<key> > --umber-shader-<key> > this default.
|
|
673
804
|
* Number, boolean and array options become uniforms named u + Option (speed -> uSpeed).
|
|
674
805
|
*/
|
|
675
|
-
options?:
|
|
806
|
+
options?: O;
|
|
676
807
|
/** Keep drawing every frame while visible (not under reduced motion with reducedMotion "static": uTime stands still). @default true */
|
|
677
808
|
animate?: boolean;
|
|
678
|
-
|
|
679
|
-
|
|
809
|
+
/** Once per element. Return a cleanup, or nothing. */
|
|
810
|
+
setup?: Setup<EffectContext<O>>;
|
|
811
|
+
update?(ctx: EffectContext<O>): void;
|
|
680
812
|
}
|
|
681
813
|
|
|
682
814
|
export interface LayerRect {
|
|
@@ -686,14 +818,25 @@ export interface LayerRect {
|
|
|
686
818
|
height: number;
|
|
687
819
|
}
|
|
688
820
|
|
|
689
|
-
|
|
821
|
+
/** What ctx.three() sets on a THREE.WebGLRenderer (a method it lacks is skipped). */
|
|
822
|
+
export interface LayerRendererLike {
|
|
823
|
+
autoClear: boolean;
|
|
824
|
+
resetState?(): void;
|
|
825
|
+
setViewport?(x: number, y: number, width: number, height: number): void;
|
|
826
|
+
setScissor?(x: number, y: number, width: number, height: number): void;
|
|
827
|
+
setScissorTest?(on: boolean): void;
|
|
828
|
+
}
|
|
829
|
+
|
|
830
|
+
/** `O`: the layer's option defaults (ctx.options). `S`: what you keep in ctx.state: umber.layer<O, S>(name, def). */
|
|
831
|
+
export interface LayerContext<O extends OptionDefaults = OptionDefaults, S extends object = Record<string, unknown>> {
|
|
690
832
|
name: string;
|
|
691
833
|
el: HTMLElement;
|
|
692
834
|
gl: WebGL2RenderingContext;
|
|
693
835
|
canvas: HTMLCanvasElement;
|
|
694
|
-
options:
|
|
695
|
-
|
|
696
|
-
|
|
836
|
+
options: ResolvedOptions<O>;
|
|
837
|
+
/** Your own storage for this element's layer (renderer, scene, meshes...): empty when setup() starts, filled by it. */
|
|
838
|
+
state: S;
|
|
839
|
+
engine: Umber;
|
|
697
840
|
rect: LayerRect;
|
|
698
841
|
px: LayerRect;
|
|
699
842
|
viewport: { width: number; height: number };
|
|
@@ -707,18 +850,22 @@ export interface LayerContext {
|
|
|
707
850
|
/** Draw at least `frames` more frames. Under reduced motion ("static") an animating layer draws only on this (and when setup() resolves): call it when a model loaded after setup lands. */
|
|
708
851
|
wake(frames?: number): void;
|
|
709
852
|
busy(on: boolean): void;
|
|
710
|
-
three
|
|
853
|
+
/** three.js: resetState, autoClear off, viewport + scissor to this element. */
|
|
854
|
+
three(renderer: LayerRendererLike): void;
|
|
711
855
|
}
|
|
712
856
|
|
|
713
|
-
export interface LayerDef {
|
|
714
|
-
/** Read per element into ctx.options: data-
|
|
715
|
-
options?:
|
|
716
|
-
/**
|
|
717
|
-
|
|
857
|
+
export interface LayerDef<O extends OptionDefaults = OptionDefaults, S extends object = Record<string, unknown>> {
|
|
858
|
+
/** Read per element into ctx.options: data-umber-layer-<key> > --umber-layer-<key> > this default. */
|
|
859
|
+
options?: O;
|
|
860
|
+
/**
|
|
861
|
+
* Once, when the element comes near the screen; render() and resize() wait for it. May be
|
|
862
|
+
* async; return (or resolve to) a cleanup, or nothing. ctx.state starts empty: fill it here.
|
|
863
|
+
*/
|
|
864
|
+
setup?: Setup<LayerContext<O, Partial<S>>, Cleanup | Promise<Cleanup | undefined>>;
|
|
718
865
|
/** Draw (ctx.three(renderer) first for three.js). */
|
|
719
|
-
render
|
|
866
|
+
render(ctx: LayerContext<O, S>): void;
|
|
720
867
|
/** The element or the screen changed size (before render). */
|
|
721
|
-
resize
|
|
868
|
+
resize?(ctx: LayerContext<O, S>): void;
|
|
722
869
|
/** Draw every frame while visible (not under reduced motion with reducedMotion "static": ctx.time stands still, and it draws on ctx.wake()). false: only on wake(), busy(true), resize and scroll. @default true */
|
|
723
870
|
animate?: boolean;
|
|
724
871
|
/** Clip drawing to the element box. @default true */
|
|
@@ -727,12 +874,14 @@ export interface LayerDef {
|
|
|
727
874
|
followOpacity?: boolean;
|
|
728
875
|
/** Max device px per CSS px for this layer (a heavy scene renders smaller, upscaled). @default the canvas's */
|
|
729
876
|
dpr?: number;
|
|
877
|
+
/**
|
|
878
|
+
* Under the page's passes (data-umber-pass on <body>), like Umber's own planes: drawn alone, copied, and the copy
|
|
879
|
+
* drawn in its place (one copy of its box per frame while the page has passes). false: straight to the canvas,
|
|
880
|
+
* under the passes. @default false (data-umber="model" and the three module's scenes: true)
|
|
881
|
+
*/
|
|
882
|
+
passes?: boolean;
|
|
730
883
|
}
|
|
731
884
|
|
|
732
|
-
// -----------------------------------------
|
|
733
|
-
// Tracking, three.js views and DOM <-> world maths
|
|
734
|
-
// -----------------------------------------
|
|
735
|
-
|
|
736
885
|
export interface TrackRect {
|
|
737
886
|
x: number;
|
|
738
887
|
y: number;
|
|
@@ -747,7 +896,7 @@ export interface TrackOptions {
|
|
|
747
896
|
live?: boolean;
|
|
748
897
|
}
|
|
749
898
|
|
|
750
|
-
/**
|
|
899
|
+
/** umber.track(el): where an element is, every frame, without layout reads or WebGL. */
|
|
751
900
|
export interface Tracker {
|
|
752
901
|
readonly el: Element;
|
|
753
902
|
/** Viewport CSS px this frame (y down), like getBoundingClientRect. */
|
|
@@ -779,15 +928,17 @@ export interface ProgressOptions {
|
|
|
779
928
|
/**
|
|
780
929
|
* Also write the value (4 decimals, only when it changed) to this CSS custom property on
|
|
781
930
|
* the element, through a rule of Umber's own stylesheet (not its style attribute).
|
|
782
|
-
* @example
|
|
931
|
+
* @example umber.progress(".hero", { css: "--hero" }) // .hero img { opacity: calc(1 - var(--hero)) }
|
|
783
932
|
*/
|
|
784
933
|
css?: string;
|
|
785
934
|
/** Measure every frame (a parent moved by transforms). @default auto (sticky, fixed or pinned parents) */
|
|
786
935
|
live?: boolean;
|
|
936
|
+
/** "x": along the screen's width, for a page that scrolls sideways (edges: left / right, or top / bottom read as them). @default "y" */
|
|
937
|
+
axis?: "x" | "y";
|
|
787
938
|
}
|
|
788
939
|
|
|
789
|
-
/**
|
|
790
|
-
export interface ProgressSignal extends Signal
|
|
940
|
+
/** umber.progress(el): a live 0..1 as el scrolls from `start` to `end`. Usable as a uniform. */
|
|
941
|
+
export interface ProgressSignal extends Signal {
|
|
791
942
|
readonly el: Element;
|
|
792
943
|
readonly start: string;
|
|
793
944
|
readonly end: string;
|
|
@@ -800,9 +951,9 @@ export interface ProgressSignal extends Signal<number> {
|
|
|
800
951
|
}
|
|
801
952
|
|
|
802
953
|
/**
|
|
803
|
-
*
|
|
804
|
-
* More inputs (
|
|
805
|
-
* the input module:
|
|
954
|
+
* umber.pointer: the pointer (mouse, pen or touch). Usable as a uniform (vec2).
|
|
955
|
+
* More inputs (umber.drag, umber.velocityOf any Signal, umber.trail, umber.press, umber.step) come with
|
|
956
|
+
* the input module: umber.use(Input) from "@occluze/umber/input" (types/input.d.ts).
|
|
806
957
|
*/
|
|
807
958
|
export interface PointerSignal {
|
|
808
959
|
/** [x, y] in viewport CSS px (y down). The viewport's centre until the pointer first moves. */
|
|
@@ -813,11 +964,22 @@ export interface PointerSignal {
|
|
|
813
964
|
readonly active: boolean;
|
|
814
965
|
}
|
|
815
966
|
|
|
967
|
+
/** What a scope makes with gl's own calls (s.add...), and the definitions and other calls it carries as they are. */
|
|
968
|
+
type ScopeMakes = "add" | "track" | "progress" | "attach" | "view" | "target" | "snapshot" | "sim" | "flow" | "brush";
|
|
969
|
+
type ScopeCarries =
|
|
970
|
+
"effect" | "shader" | "layer" | "chunk" | "on" | "nextFrame" | "scope" | "preload" | "warm" | "leave" | "flip";
|
|
971
|
+
|
|
816
972
|
/**
|
|
817
|
-
*
|
|
973
|
+
* umber.scope(fn, container): everything Umber made inside fn, undone with revert(). The
|
|
818
974
|
* scope has gl's creating methods: after an await, call them on the scope (s.add, s.track...).
|
|
975
|
+
* An add-on's methods join them (types/input.d.ts: s.drag, s.texture...). On revert():
|
|
976
|
+
* targets, snapshots, sims and brushes are released (the shared umber.flow() flowmap only when
|
|
977
|
+
* this scope's call made it and no plane reads uFlow; options a scope set on it stay);
|
|
978
|
+
* umber.preload({ hover }) is turned off (what it fetched is freed unclaimed after 20 s); this
|
|
979
|
+
* scope's umber.leave() comes out, and the newest one left (or none) is on again, once a page
|
|
980
|
+
* change that holds or plays it ends.
|
|
819
981
|
*/
|
|
820
|
-
export interface Scope {
|
|
982
|
+
export interface Scope extends Pick<Umber, ScopeMakes | ScopeCarries> {
|
|
821
983
|
/** Where selector strings resolve inside the scope (null: the document). */
|
|
822
984
|
readonly container: Element | null;
|
|
823
985
|
readonly reverted: boolean;
|
|
@@ -828,61 +990,50 @@ export interface Scope {
|
|
|
828
990
|
/** Destroy everything made in the scope, newest first; previous definitions come back. */
|
|
829
991
|
revert(): void;
|
|
830
992
|
destroy(): void;
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
shader(name: string, def: ShaderDef): void;
|
|
838
|
-
layer(name: string, def: LayerDef): void;
|
|
839
|
-
chunk(name: string, glsl: string): void;
|
|
840
|
-
on(name: "frame", fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number; always?: boolean }): () => void;
|
|
841
|
-
on(name: "ready" | "lost" | "restored" | "destroy", fn: (payload?: any) => void): () => void;
|
|
842
|
-
/** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
|
|
843
|
-
on(name: "added", fn: (roots: Element[]) => void): () => void;
|
|
844
|
-
/**
|
|
845
|
-
* GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
|
|
846
|
-
* page with data-gl-disable): `reason` is gl.reason. Also on document as "umber:off". For
|
|
847
|
-
* the site's own analytics.
|
|
848
|
-
*/
|
|
849
|
-
on(name: "off", fn: (e: { reason: GLReason }) => void): () => void;
|
|
850
|
-
/**
|
|
851
|
-
* A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
|
|
852
|
-
* or GL text that stays DOM text), or null when something failed (a picture or video that
|
|
853
|
-
* could not load, a shader that did not compile: the console says why). Also on document
|
|
854
|
-
* as "umber:fallback".
|
|
855
|
-
*/
|
|
856
|
-
on(name: "fallback", fn: (e: { el: Element; reason: string | null }) => void): () => void;
|
|
857
|
-
nextFrame(fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number }): () => void;
|
|
858
|
-
scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
|
|
859
|
-
/** Released on revert() (the shared gl.flow() flowmap only when this scope's call made it and no plane reads uFlow; options a scope set on it stay). */
|
|
860
|
-
target: GL["target"];
|
|
861
|
-
snapshot: GL["snapshot"];
|
|
862
|
-
sim: GL["sim"];
|
|
863
|
-
flow: GL["flow"];
|
|
864
|
-
brush: GL["brush"];
|
|
865
|
-
/** gl.preload({ hover }) is turned off on revert(); what it fetched is freed unclaimed after 20 s. */
|
|
866
|
-
preload: GL["preload"];
|
|
867
|
-
warm: GL["warm"];
|
|
868
|
-
/** revert() takes this scope's gl.leave() out: the newest one left (or none) is on again, once a page change that holds or plays it ends. */
|
|
869
|
-
leave: GL["leave"];
|
|
870
|
-
flip: GL["flip"];
|
|
871
|
-
}
|
|
872
|
-
|
|
873
|
-
/** What Umber calls on a THREE.WebGLRenderer (Umber never imports three.js). */
|
|
993
|
+
}
|
|
994
|
+
|
|
995
|
+
/**
|
|
996
|
+
* What Umber calls on the THREE.WebGLRenderer you hand umber.attach() (Umber never imports
|
|
997
|
+
* three.js): your renderer's own type flows through to the view's callbacks.
|
|
998
|
+
*/
|
|
874
999
|
export interface ThreeRendererLike {
|
|
875
1000
|
domElement?: HTMLCanvasElement;
|
|
876
1001
|
setSize?(width: number, height: number, updateStyle?: boolean): void;
|
|
877
1002
|
setPixelRatio?(ratio: number): void;
|
|
878
|
-
render
|
|
1003
|
+
/** The default render(): renderer.render(scene, camera), with the scene and camera you passed. */
|
|
1004
|
+
render?(scene: unknown, camera: unknown): void;
|
|
879
1005
|
getContext?(): WebGLRenderingContext | WebGL2RenderingContext;
|
|
880
1006
|
dispose?(): void;
|
|
881
|
-
[key: string]: any;
|
|
882
1007
|
}
|
|
883
1008
|
|
|
884
|
-
/**
|
|
885
|
-
export interface
|
|
1009
|
+
/** What Umber sets and calls on the one renderer umber.renderer(THREE) makes on its canvas. */
|
|
1010
|
+
export interface SharedRendererLike
|
|
1011
|
+
extends LayerRendererLike, Pick<ThreeRendererLike, "setPixelRatio" | "setSize" | "dispose"> {
|
|
1012
|
+
/** The default render(): renderer.render(scene, camera), with the view's scene and camera. */
|
|
1013
|
+
render(scene: unknown, camera: unknown): void;
|
|
1014
|
+
}
|
|
1015
|
+
|
|
1016
|
+
/** What umber.renderer(THREE) needs of the three.js module: its WebGLRenderer, made on Umber's canvas and context. */
|
|
1017
|
+
export interface ThreeModuleLike<R extends SharedRendererLike> {
|
|
1018
|
+
WebGLRenderer: new (params: { canvas: HTMLCanvasElement; context: WebGL2RenderingContext }) => R;
|
|
1019
|
+
}
|
|
1020
|
+
|
|
1021
|
+
/**
|
|
1022
|
+
* A view's camera: what Umber reads of it. A PerspectiveCamera's aspect follows the box
|
|
1023
|
+
* (isPerspectiveCamera, aspect, updateProjectionMatrix), and view.rectToWorld() /
|
|
1024
|
+
* view.worldToRect() map with its matrices (they throw without a camera).
|
|
1025
|
+
*/
|
|
1026
|
+
export type ViewCameraLike = Partial<CameraLike>;
|
|
1027
|
+
|
|
1028
|
+
/**
|
|
1029
|
+
* The object a view's animate / render / resize get. `S`, `C`, `R`: your scene, camera
|
|
1030
|
+
* and renderer types, from the options you passed.
|
|
1031
|
+
*/
|
|
1032
|
+
export interface ViewFrame<
|
|
1033
|
+
S = unknown,
|
|
1034
|
+
C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
|
|
1035
|
+
R = unknown,
|
|
1036
|
+
> {
|
|
886
1037
|
time: number;
|
|
887
1038
|
dt: number;
|
|
888
1039
|
ratio: number;
|
|
@@ -898,31 +1049,40 @@ export interface ViewFrame {
|
|
|
898
1049
|
velocity: number;
|
|
899
1050
|
/** prefers-reduced-motion: animate() still runs, but returning true no longer loops. */
|
|
900
1051
|
reducedMotion: boolean;
|
|
901
|
-
renderer:
|
|
902
|
-
scene:
|
|
903
|
-
camera:
|
|
1052
|
+
renderer: R;
|
|
1053
|
+
scene: S;
|
|
1054
|
+
camera: C;
|
|
904
1055
|
view: View;
|
|
905
1056
|
}
|
|
906
1057
|
|
|
907
|
-
export interface ViewSetupContext
|
|
1058
|
+
export interface ViewSetupContext<
|
|
1059
|
+
S = unknown,
|
|
1060
|
+
C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
|
|
1061
|
+
R = unknown,
|
|
1062
|
+
> {
|
|
908
1063
|
el: HTMLElement;
|
|
909
|
-
renderer:
|
|
910
|
-
scene:
|
|
911
|
-
camera:
|
|
1064
|
+
renderer: R;
|
|
1065
|
+
scene: S;
|
|
1066
|
+
camera: C;
|
|
912
1067
|
view: View;
|
|
913
1068
|
}
|
|
914
1069
|
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
1070
|
+
/** `S`, `C`, `R`: the scene, camera and renderer the callbacks get (umber.view(): the shared renderer, null until umber.renderer() resolved). */
|
|
1071
|
+
export interface ViewOptions<
|
|
1072
|
+
S = unknown,
|
|
1073
|
+
C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
|
|
1074
|
+
R = unknown,
|
|
1075
|
+
> {
|
|
1076
|
+
scene?: S;
|
|
1077
|
+
camera?: C;
|
|
918
1078
|
/** Draw yourself. @default renderer.render(scene, camera) */
|
|
919
|
-
render?: (f: ViewFrame) => void;
|
|
920
|
-
/** Before every drawn frame. Return true to draw the next frame too. */
|
|
921
|
-
animate?: (f: ViewFrame) => boolean |
|
|
922
|
-
/** Once, when the element comes near the screen. May be async (compileAsync)
|
|
923
|
-
setup?:
|
|
1079
|
+
render?: (f: ViewFrame<S, C, R>) => void;
|
|
1080
|
+
/** Before every drawn frame. Return true to draw the next frame too; anything else draws again only on wake(), busy() or a resize. */
|
|
1081
|
+
animate?: (f: ViewFrame<S, C, R>) => boolean | undefined;
|
|
1082
|
+
/** Once, when the element comes near the screen. May be async (compileAsync); return (or resolve to) a cleanup, or nothing. */
|
|
1083
|
+
setup?: Setup<ViewSetupContext<S, C, R>, Cleanup | Promise<Cleanup | undefined>>;
|
|
924
1084
|
/** After Umber sized the drawing (a PerspectiveCamera's aspect is already set). */
|
|
925
|
-
resize?: (f: ViewFrame) => void;
|
|
1085
|
+
resize?: (f: ViewFrame<S, C, R>) => void;
|
|
926
1086
|
/** Devices this view runs on, instead of the engine's. @example "all" (phones on for this scene only) */
|
|
927
1087
|
devices?: "all" | "desktop" | false | ((env: Env) => boolean);
|
|
928
1088
|
/** A max DPR or [min, max] for this view. @default the engine's dpr */
|
|
@@ -931,9 +1091,13 @@ export interface ViewOptions {
|
|
|
931
1091
|
aspect?: boolean;
|
|
932
1092
|
}
|
|
933
1093
|
|
|
934
|
-
export interface AttachOptions
|
|
1094
|
+
export interface AttachOptions<
|
|
1095
|
+
S = unknown,
|
|
1096
|
+
C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
|
|
1097
|
+
R extends ThreeRendererLike = ThreeRendererLike,
|
|
1098
|
+
> extends ViewOptions<S, C, R> {
|
|
935
1099
|
/** Your THREE.WebGLRenderer. Its canvas goes into the element unless it is in the page already. */
|
|
936
|
-
renderer:
|
|
1100
|
+
renderer: R;
|
|
937
1101
|
/** Max drawing pixels (w * h * dpr^2). @default the engine's pixelBudget, else 12e6 */
|
|
938
1102
|
pixelBudget?: number;
|
|
939
1103
|
/** Lower the resolution only when frames get slow. @default the engine's adaptive */
|
|
@@ -942,17 +1106,24 @@ export interface AttachOptions extends ViewOptions {
|
|
|
942
1106
|
dispose?: boolean;
|
|
943
1107
|
}
|
|
944
1108
|
|
|
945
|
-
|
|
1109
|
+
/** `R`: the renderer umber.renderer(THREE) made (null in the callbacks until it resolved). */
|
|
1110
|
+
export interface SharedViewOptions<
|
|
1111
|
+
S = unknown,
|
|
1112
|
+
C extends ViewCameraLike | undefined = ViewCameraLike | undefined,
|
|
1113
|
+
R extends SharedRendererLike = SharedRendererLike,
|
|
1114
|
+
> extends ViewOptions<S, C, R | null> {
|
|
946
1115
|
/** Fade with the element's (and its parents') opacity. @default true */
|
|
947
1116
|
followOpacity?: boolean;
|
|
948
1117
|
/** Clip drawing to the element box. @default true */
|
|
949
1118
|
scissor?: boolean;
|
|
1119
|
+
/** Under the page's passes (data-umber-pass), like Umber's own planes (see LayerDef.passes). @default false */
|
|
1120
|
+
passes?: boolean;
|
|
950
1121
|
}
|
|
951
1122
|
|
|
952
1123
|
export type ViewStatus = "loading" | "ready" | "off" | "error" | "lost" | "destroyed";
|
|
953
1124
|
export type ViewEvent = "ready" | "resize" | "enter" | "leave" | "lost" | "restored" | "error" | "destroy";
|
|
954
1125
|
|
|
955
|
-
/**
|
|
1126
|
+
/** umber.attach() / umber.view(): your three.js scene tied to an element. */
|
|
956
1127
|
export interface View {
|
|
957
1128
|
readonly el: HTMLElement;
|
|
958
1129
|
readonly kind: "attach" | "view";
|
|
@@ -1046,7 +1217,12 @@ export interface UmberMath {
|
|
|
1046
1217
|
/** Aim the camera so it sees exactly `size` at z = 0, `unit` CSS px per world unit (default 1). */
|
|
1047
1218
|
fitCamera<C extends CameraLike>(camera: C, size: { width: number; height: number }, unit?: number): C;
|
|
1048
1219
|
/** A DOM rect's centre on the plane z (default 0) and its size there; writes x, y, z into `out`. */
|
|
1049
|
-
rectToWorld(
|
|
1220
|
+
rectToWorld(
|
|
1221
|
+
rect: RectLike,
|
|
1222
|
+
camera: CameraLike,
|
|
1223
|
+
out?: Partial<Vec3Like> | null,
|
|
1224
|
+
options?: { z?: number; frame?: RectLike },
|
|
1225
|
+
): WorldBox;
|
|
1050
1226
|
/** A world point in viewport CSS px. */
|
|
1051
1227
|
worldToRect(point: Vec3Like, camera: CameraLike, frame?: RectLike): ScreenPoint;
|
|
1052
1228
|
/** Lerp that feels the same at 60, 120 and 144 Hz: damp(current, target, 0.1, f.dt). */
|
|
@@ -1057,125 +1233,152 @@ export interface UmberMath {
|
|
|
1057
1233
|
/** GLSL's smoothstep: 0 below edge0, 1 above edge1, smooth between. */
|
|
1058
1234
|
smoothstep(edge0: number, edge1: number, x: number): number;
|
|
1059
1235
|
/**
|
|
1060
|
-
* 0..1 as a rect scrolls from start to end, written like
|
|
1236
|
+
* 0..1 as a rect scrolls from start to end, written like umber.progress().
|
|
1061
1237
|
* @example rectProgress(el.getBoundingClientRect(), "top bottom", "bottom top")
|
|
1062
1238
|
*/
|
|
1063
|
-
rectProgress(
|
|
1239
|
+
rectProgress(
|
|
1240
|
+
rect: { top?: number; y?: number; height: number },
|
|
1241
|
+
start?: string,
|
|
1242
|
+
end?: string,
|
|
1243
|
+
viewportHeight?: number,
|
|
1244
|
+
): number;
|
|
1064
1245
|
}
|
|
1065
1246
|
|
|
1066
|
-
/**
|
|
1067
|
-
export interface
|
|
1247
|
+
/** umber.on(name, fn): what each event hands fn. Each but "frame" also goes to document as a DOM event, "umber:<name>" (payload in detail). */
|
|
1248
|
+
export interface UmberEvents {
|
|
1249
|
+
/** Every frame the loop runs (umber.on("frame") adds fn to the loop). */
|
|
1250
|
+
frame: Frame;
|
|
1251
|
+
/** GL draws this page's [data-umber] elements: the engine. */
|
|
1252
|
+
ready: Umber;
|
|
1253
|
+
/** The WebGL context was lost. */
|
|
1254
|
+
lost: undefined;
|
|
1255
|
+
/** The WebGL context is back. */
|
|
1256
|
+
restored: undefined;
|
|
1257
|
+
/** umber.destroy(): the engine is gone. */
|
|
1258
|
+
destroy: undefined;
|
|
1259
|
+
/** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
|
|
1260
|
+
added: Element[];
|
|
1261
|
+
/**
|
|
1262
|
+
* GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
|
|
1263
|
+
* page with data-umber-disable): `reason` is umber.reason. For the site's own analytics.
|
|
1264
|
+
*/
|
|
1265
|
+
off: { reason: UmberReason };
|
|
1266
|
+
/**
|
|
1267
|
+
* A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
|
|
1268
|
+
* or GL text that stays DOM text), or null when something failed (a picture or video that
|
|
1269
|
+
* could not load, a shader that did not compile: the console says why).
|
|
1270
|
+
*/
|
|
1271
|
+
fallback: { el: Element; reason: string | null };
|
|
1272
|
+
}
|
|
1273
|
+
|
|
1274
|
+
/** What createUmber() returns. */
|
|
1275
|
+
export interface Umber {
|
|
1068
1276
|
readonly version: string;
|
|
1069
|
-
/** true once GL draws this page's [data-
|
|
1277
|
+
/** true once GL draws this page's [data-umber] elements; false when GL is off or the page has none. */
|
|
1070
1278
|
readonly ready: Promise<boolean>;
|
|
1071
1279
|
readonly enabled: boolean;
|
|
1072
|
-
readonly reason:
|
|
1280
|
+
readonly reason: UmberReason | null;
|
|
1073
1281
|
readonly destroyed: boolean;
|
|
1074
1282
|
/** Smoothed scroll velocity, roughly -1..1. */
|
|
1075
1283
|
readonly velocity: Signal;
|
|
1076
1284
|
/**
|
|
1077
1285
|
* The pointer: { value: [x, y] } viewport px, velocity.value [vx, vy] px/s. Its passive
|
|
1078
1286
|
* listeners attach the first time it is read. Usable as a uniform.
|
|
1079
|
-
* @example
|
|
1287
|
+
* @example umber.effect("lens", { uniforms: { uPointer: umber.pointer }, fragment: { ... } })
|
|
1080
1288
|
*/
|
|
1081
1289
|
readonly pointer: PointerSignal;
|
|
1082
1290
|
/**
|
|
1083
|
-
*
|
|
1291
|
+
* An event (UmberEvents says what fn gets), or "frame": fn joins the loop. Returns off().
|
|
1084
1292
|
* A "frame" callback keeps the loop running every frame; { always: false } only rides
|
|
1085
|
-
* along on frames Umber runs anyway. The
|
|
1086
|
-
*
|
|
1087
|
-
* @example const off =
|
|
1293
|
+
* along on frames Umber runs anyway. The other events are also sent on document as DOM
|
|
1294
|
+
* events (umber:ready, umber:off...; payload in detail).
|
|
1295
|
+
* @example const off = umber.on("frame", (f) => { mesh.rotation.y += f.dt; }, { phase: "update" });
|
|
1296
|
+
* @example umber.on("fallback", ({ el, reason }) => analytics.track("umber-fallback", { reason }));
|
|
1088
1297
|
* @example document.addEventListener("umber:ready", (e) => console.log(e.detail));
|
|
1089
1298
|
*/
|
|
1090
|
-
on(name: "frame", fn: (frame: Frame) => void, opts?:
|
|
1091
|
-
on(name:
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
*/
|
|
1099
|
-
on(name: "off", fn: (e: { reason: GLReason }) => void): () => void;
|
|
1100
|
-
/**
|
|
1101
|
-
* A plane shows its DOM instead of GL: `reason` is the warning's words (what GL can't draw,
|
|
1102
|
-
* or GL text that stays DOM text), or null when something failed (a picture or video that
|
|
1103
|
-
* could not load, a shader that did not compile: the console says why). Also on document
|
|
1104
|
-
* as "umber:fallback".
|
|
1105
|
-
*/
|
|
1106
|
-
on(name: "fallback", fn: (e: { el: Element; reason: string | null }) => void): () => void;
|
|
1107
|
-
off(name: string, fn: (payload?: any) => void): void;
|
|
1108
|
-
effect(name: string, def: EffectDef): void;
|
|
1109
|
-
shader(name: string, def: ShaderDef): void;
|
|
1110
|
-
layer(name: string, def: LayerDef): void;
|
|
1299
|
+
on(name: "frame", fn: (frame: Frame) => void, opts?: FrameOptions): () => void;
|
|
1300
|
+
on<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): () => void;
|
|
1301
|
+
off<E extends keyof UmberEvents>(name: E, fn: (payload: UmberEvents[E]) => void): void;
|
|
1302
|
+
/** `O`: the option defaults, which type ctx.options in setup() and update(). */
|
|
1303
|
+
effect<O extends OptionDefaults>(name: string, def: EffectDef<O>): void;
|
|
1304
|
+
shader<O extends OptionDefaults>(name: string, def: ShaderDef<O>): void;
|
|
1305
|
+
/** `S`: what the layer keeps in ctx.state: umber.layer<{ speed: number }, { scene: THREE.Scene }>("discs", { ... }). */
|
|
1306
|
+
layer<O extends OptionDefaults, S extends object = Record<string, unknown>>(name: string, def: LayerDef<O, S>): void;
|
|
1111
1307
|
/**
|
|
1112
1308
|
* A named piece of GLSL an effect pulls in with a line of its own in any slot:
|
|
1113
1309
|
* #include "name". Only included chunks are compiled, once per program, after Umber's
|
|
1114
1310
|
* helpers and before the effects' heads; a chunk may include others (added first) and is
|
|
1115
1311
|
* never renamed. Defined again: the planes using it are rebuilt. An element whose effect
|
|
1116
1312
|
* includes an unknown name shows its DOM (one [umber] warning) until it is defined.
|
|
1117
|
-
* @example
|
|
1118
|
-
* @example
|
|
1313
|
+
* @example umber.chunk("sdf", "float sdCircle(vec2 p, float r) { return length(p) - r; }")
|
|
1314
|
+
* @example umber.effect("ring", { fragment: { head: '#include "sdf"', alpha: "alpha *= step(sdCircle(uv - 0.5, 0.4), 0.0);" } })
|
|
1119
1315
|
*/
|
|
1120
1316
|
chunk(name: string, glsl: string): void;
|
|
1121
1317
|
/**
|
|
1122
1318
|
* Use an optional module (before or after GL loads). A module script does this itself.
|
|
1123
|
-
* @example
|
|
1319
|
+
* @example umber.use(Scrub, { cacheMB: 128 })
|
|
1124
1320
|
*/
|
|
1125
|
-
use(module: UmberModule, options?: Record<string, unknown>):
|
|
1321
|
+
use(module: UmberModule, options?: Record<string, unknown>): Umber;
|
|
1126
1322
|
/**
|
|
1127
1323
|
* Whether this page's domain is on an Umber licence (the domains listed at occluze.com).
|
|
1128
|
-
* Asked once per page, by GL or by a module that needs it (
|
|
1129
|
-
* native until the answer is yes). Yes on your own computer (localhost, *.test)
|
|
1130
|
-
* the check can't be reached.
|
|
1324
|
+
* Asked once per page, by GL or by a module that needs it (umber.scroll, umber.router: they stay
|
|
1325
|
+
* native until the answer is yes). Yes on your own computer (localhost, *.localhost, *.test);
|
|
1326
|
+
* no when the check can't be reached (umber.reason "licence-unreachable"): only a clear yes counts.
|
|
1131
1327
|
*/
|
|
1132
1328
|
licensed(): Promise<boolean>;
|
|
1133
|
-
/**
|
|
1329
|
+
/** umber.licensed()'s answer once it is in; null while it is asked (or before anything asked). */
|
|
1134
1330
|
readonly licence: boolean | null;
|
|
1135
1331
|
/**
|
|
1136
1332
|
* A plane from code: writes the attributes `options` stand for and builds the plane
|
|
1137
1333
|
* (now when GL is loaded). Resolves with the plane, or null when GL is off. An element
|
|
1138
|
-
* with data-
|
|
1139
|
-
* @example const plane = await
|
|
1334
|
+
* with data-umber already resolves with its own plane.
|
|
1335
|
+
* @example const plane = await umber.add(img, { effects: ["dissolve"], options: { dissolve: { trigger: "manual" } } })
|
|
1140
1336
|
*/
|
|
1141
1337
|
add(el: string | Element, options?: AddOptions): Promise<Plane | null>;
|
|
1142
1338
|
/**
|
|
1143
|
-
* Record every Umber object made inside fn (planes from
|
|
1339
|
+
* Record every Umber object made inside fn (planes from umber.add, views, trackers,
|
|
1144
1340
|
* progress signals, frame callbacks, events, nextFrame, definitions, nested scopes,
|
|
1145
|
-
* targets, snapshots, sims, brushes,
|
|
1146
|
-
*
|
|
1147
|
-
* @example const scope =
|
|
1341
|
+
* targets, snapshots, sims, brushes, umber.leave, and what a module's calls make: umber.drag,
|
|
1342
|
+
* umber.texture...); scope.revert() undoes them all. Selector strings resolve inside `container`.
|
|
1343
|
+
* @example const scope = umber.scope(() => { umber.add(".card img", { effects: ["lens"] }); }, card); scope.revert();
|
|
1148
1344
|
*/
|
|
1149
1345
|
scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
|
|
1150
1346
|
/**
|
|
1151
1347
|
* A live 0..1 as el scrolls from `start` to `end`, from the measure phase (native
|
|
1152
1348
|
* scroll, a scroll container or Lenis alike; also with GL off). Usable as a uniform.
|
|
1153
1349
|
* Ends when el leaves the page.
|
|
1154
|
-
* @example
|
|
1350
|
+
* @example umber.effect("story", { uniforms: { uStory: umber.progress(".story", { start: "top top", end: "bottom bottom" }) } })
|
|
1155
1351
|
*/
|
|
1156
1352
|
progress(el: string | Element, options?: ProgressOptions): ProgressSignal;
|
|
1157
1353
|
/** fn(frame) once, on the next frame (update phase unless `phase`). Returns a cancel. */
|
|
1158
1354
|
nextFrame(fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number }): () => void;
|
|
1159
|
-
/** Look for [data-
|
|
1355
|
+
/** Look for [data-umber] in root now (normally automatic). */
|
|
1160
1356
|
scan(root?: ParentNode): void;
|
|
1161
1357
|
/** Destroy planes whose element left the page (normally automatic). */
|
|
1162
1358
|
prune(): void;
|
|
1163
|
-
/**
|
|
1164
|
-
destroy(el?: Element): void;
|
|
1359
|
+
/** umber.destroy(): the whole engine. umber.destroy(el): that element's plane only (null, a selector that found nothing: nothing, with a warning). */
|
|
1360
|
+
destroy(el?: Element | null): void;
|
|
1165
1361
|
/** Measure every plane (or el's) again on the next frame, and read its effect options again (a CSSOM change, an option attribute set from code). */
|
|
1166
1362
|
invalidate(el?: Element): void;
|
|
1167
1363
|
/** Measure every visible plane every frame: true, false, or for `seconds`. */
|
|
1168
1364
|
live(on: boolean | number): void;
|
|
1169
1365
|
wake(frames?: number): void;
|
|
1366
|
+
/** GL lets the DOM show and holds its planes until resume(). umber.loop.pause() stops the clock instead. */
|
|
1170
1367
|
pause(): void;
|
|
1171
1368
|
resume(): void;
|
|
1369
|
+
/**
|
|
1370
|
+
* Umber's clock: pause(), play() and restart() every frame callback at once (the page's
|
|
1371
|
+
* own loops too, with patch), its measured fps, and a profiler.
|
|
1372
|
+
* @example umber.loop.pause();
|
|
1373
|
+
*/
|
|
1374
|
+
readonly loop: Loop;
|
|
1172
1375
|
plane(el: Element | null | undefined): Plane | null;
|
|
1173
1376
|
/**
|
|
1174
1377
|
* Print one plane to the console (kind, source, tier, effects, uniforms, program) with
|
|
1175
1378
|
* every reason it is not drawn, and resolve with the same report. An element inside a
|
|
1176
|
-
* plane (the <img> in a data-
|
|
1379
|
+
* plane (the <img> in a data-umber wrapper) reports that plane. null when nothing matches.
|
|
1177
1380
|
* Async: what it reads comes with chunks/inspect.js, fetched on the first call.
|
|
1178
|
-
* @example const report = await
|
|
1381
|
+
* @example const report = await umber.inspect(".hero img")
|
|
1179
1382
|
*/
|
|
1180
1383
|
inspect(el: string | Element): Promise<InspectReport | null>;
|
|
1181
1384
|
planes(container?: ParentNode): Plane[];
|
|
@@ -1186,7 +1389,7 @@ export interface GL {
|
|
|
1186
1389
|
/**
|
|
1187
1390
|
* A page change, for any router: call it in the hook where a change starts, and the
|
|
1188
1391
|
* function it returns in the hook where it is done. Plays are held and planes measured
|
|
1189
|
-
* every frame until then, data-
|
|
1392
|
+
* every frame until then, data-umber-id images on screen are noted to fly, and an element
|
|
1190
1393
|
* with a view-transition-name shows its DOM (the browser snapshots it). Optional:
|
|
1191
1394
|
* planes, swaps and flights also work without it. A second call while one runs gives it
|
|
1192
1395
|
* the next page and returns the same end. Ends by itself after 8 s (with a warning).
|
|
@@ -1198,8 +1401,8 @@ export interface GL {
|
|
|
1198
1401
|
* `finished`). Resolves once the image landed and the new page's planes on screen draw
|
|
1199
1402
|
* (4 s at most), so a router hook can await it.
|
|
1200
1403
|
* @example let end = () => {};
|
|
1201
|
-
* swup.hooks.on("visit:start", () => (end =
|
|
1202
|
-
* swup.hooks.on("page:load", (visit, { page }) =>
|
|
1404
|
+
* swup.hooks.on("visit:start", () => (end = umber.transition()));
|
|
1405
|
+
* swup.hooks.on("page:load", (visit, { page }) => umber.transition(page.html)); // Swup 4
|
|
1203
1406
|
* swup.hooks.on("visit:end", () => end());
|
|
1204
1407
|
*/
|
|
1205
1408
|
transition(next?: NextPage): (after?: number | PromiseLike<unknown>) => Promise<void>;
|
|
@@ -1208,26 +1411,27 @@ export interface GL {
|
|
|
1208
1411
|
* GL is laid over the new page and your GLSL takes it away. Define
|
|
1209
1412
|
* `vec4 leave(vec2 uv)` ((0,0) = top left; premultiplied in and out); prev(uv) is the
|
|
1210
1413
|
* old page, next(uv) the new one (calling it makes leave() replace the canvas instead
|
|
1211
|
-
* of drawing over it), uProgress runs 0 -> 1 from
|
|
1212
|
-
* swap, with no
|
|
1213
|
-
* taken only while a change may start (
|
|
1214
|
-
* back / forward), from frames the page draws anyway. null turns it off.
|
|
1215
|
-
*
|
|
1414
|
+
* of drawing over it), uProgress runs 0 -> 1 from umber.transition()'s end() (or from the
|
|
1415
|
+
* swap, with no umber.transition()). GL content only: the DOM is the router's. Copies are
|
|
1416
|
+
* taken only while a change may start (umber.transition(), a same-origin link pressed, a
|
|
1417
|
+
* back / forward), from frames the page draws anyway. null turns it off. Resolves (with
|
|
1418
|
+
* null) once it is set, or at once when GL is off.
|
|
1419
|
+
* @example umber.leave("vec4 leave(vec2 uv) { return prev(uv) * step(uProgress, uv.y); }", { duration: 0.9 });
|
|
1216
1420
|
*/
|
|
1217
|
-
leave(glsl: string | null, options?: LeaveOptions): Promise<
|
|
1421
|
+
leave(glsl: string | null, options?: LeaveOptions): Promise<null>;
|
|
1218
1422
|
/**
|
|
1219
1423
|
* A same-page layout change, flown on the GPU (chunks/flip.js): the GL elements inside
|
|
1220
1424
|
* `els` are noted where they are drawn, `change()` runs (at once, before this returns),
|
|
1221
1425
|
* and each flies from its old rect and corners to its new ones. The DOM jumps; only
|
|
1222
1426
|
* the GL copies move. Resolves once all landed. Without GL, change() simply runs.
|
|
1223
|
-
* @example await
|
|
1427
|
+
* @example await umber.flip(".card", () => grid.classList.toggle("is-list"), { duration: 0.8, stagger: 0.03 });
|
|
1224
1428
|
*/
|
|
1225
1429
|
flip(els: string | Element | ArrayLike<Element>, change?: () => void, options?: FlipOptions): Promise<void>;
|
|
1226
1430
|
/**
|
|
1227
|
-
* The lower-level parts of
|
|
1431
|
+
* The lower-level parts of umber.transition() for data-umber-id flights. capture(next): a
|
|
1228
1432
|
* navigation starts; when the next page is known the matching image freezes where it is
|
|
1229
1433
|
* ("" or nothing = not known yet). settle(): the swap is done.
|
|
1230
|
-
* @example barba.hooks.before((data) =>
|
|
1434
|
+
* @example barba.hooks.before((data) => umber.morph.capture(data.next.html)); barba.hooks.after(() => umber.morph.settle());
|
|
1231
1435
|
*/
|
|
1232
1436
|
morph: { capture(next?: NextPage): void; settle(): void };
|
|
1233
1437
|
/** Where an element is, every frame, without WebGL (works with GL off). Ends when el leaves the page. */
|
|
@@ -1235,32 +1439,45 @@ export interface GL {
|
|
|
1235
1439
|
/**
|
|
1236
1440
|
* Your three.js scene in its own canvas (the drop-in mode). Umber sizes the renderer,
|
|
1237
1441
|
* draws only while el is on screen and something asked, and cleans up when el leaves.
|
|
1238
|
-
* @example
|
|
1442
|
+
* @example umber.attach(el, { renderer, scene, camera, devices: "all", animate: (f) => { mesh.rotation.y += f.dt; return true; } })
|
|
1239
1443
|
*/
|
|
1240
|
-
attach
|
|
1444
|
+
attach<S, C extends ViewCameraLike | undefined, R extends ThreeRendererLike>(
|
|
1445
|
+
el: string | Element,
|
|
1446
|
+
options: AttachOptions<S, C, R>,
|
|
1447
|
+
): View;
|
|
1241
1448
|
/**
|
|
1242
1449
|
* Advanced: a scene drawn into Umber's own canvas, next to the DOM planes, with the one
|
|
1243
|
-
* renderer from
|
|
1244
|
-
* @example const renderer = await
|
|
1450
|
+
* renderer from umber.renderer(THREE). Clipped to el, fades with it, goes when el leaves.
|
|
1451
|
+
* @example const renderer = await umber.renderer(THREE); umber.view(el, { scene, camera });
|
|
1452
|
+
*/
|
|
1453
|
+
view<S, C extends ViewCameraLike | undefined, R extends SharedRendererLike = SharedRendererLike>(
|
|
1454
|
+
el: string | Element,
|
|
1455
|
+
options?: SharedViewOptions<S, C, R>,
|
|
1456
|
+
): View;
|
|
1457
|
+
/**
|
|
1458
|
+
* Advanced: the one THREE.WebGLRenderer on Umber's canvas for the whole visit (compiled
|
|
1459
|
+
* programs survive page changes), made with `params` plus Umber's canvas and context.
|
|
1460
|
+
* Resolves with the renderer three's module makes; null when GL is off.
|
|
1245
1461
|
*/
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1462
|
+
renderer<R extends SharedRendererLike>(
|
|
1463
|
+
three: ThreeModuleLike<R>,
|
|
1464
|
+
params?: Record<string, unknown>,
|
|
1465
|
+
): Promise<R | null>;
|
|
1249
1466
|
/**
|
|
1250
1467
|
* An offscreen render target on Umber's context (its own file, chunks/fx.js, fetched on
|
|
1251
1468
|
* the first call). Draw into it with target.draw(glsl), read it in any effect as a
|
|
1252
1469
|
* uniform, or hand target.texture to three.js on Umber's canvas. Holds premultiplied
|
|
1253
1470
|
* alpha; "half" (RGBA16F) by default where the GPU can render to it. null when GL is off.
|
|
1254
|
-
* @example const t = await
|
|
1471
|
+
* @example const t = await umber.target({ width: 512, height: 512 });
|
|
1255
1472
|
* t.draw("vec4 color(vec2 uv) { return vec4(uv, 0.5, 1.0); }");
|
|
1256
|
-
*
|
|
1473
|
+
* umber.effect("show", { uniforms: { uPattern: t }, fragment: { color: "color = texture(uPattern, uv);" } });
|
|
1257
1474
|
*/
|
|
1258
1475
|
target(options?: TargetOptions): Promise<Target | null>;
|
|
1259
1476
|
/**
|
|
1260
1477
|
* A still copy of what one plane draws right now (its effects included, its parents'
|
|
1261
1478
|
* cuts not), as a target: device px, "u8". Waits up to 5 s for the plane to be able to
|
|
1262
1479
|
* draw. null when there is no plane, GL is off, or it never drew.
|
|
1263
|
-
* @example const still = await
|
|
1480
|
+
* @example const still = await umber.snapshot(".hero img"); umber.effect("echo", { uniforms: { uStill: still }, ... });
|
|
1264
1481
|
*/
|
|
1265
1482
|
snapshot(el: string | Element | Plane): Promise<Target | null>;
|
|
1266
1483
|
/**
|
|
@@ -1269,9 +1486,9 @@ export interface GL {
|
|
|
1269
1486
|
* screen. It steps after an input (a brush, the pointer, set(), wake()) and sleeps once
|
|
1270
1487
|
* settled, so a still page asks for no frames. Read it in any effect as a uniform.
|
|
1271
1488
|
* null when GL is off.
|
|
1272
|
-
* @example const sim = await
|
|
1273
|
-
*
|
|
1274
|
-
*
|
|
1489
|
+
* @example const sim = await umber.sim({ size: 128, next: "vec4 next(vec2 uv) { return texture(state, uv) * 0.95; }" });
|
|
1490
|
+
* umber.brush(sim, { radius: 40 }); // paints where the pointer goes
|
|
1491
|
+
* umber.effect("ink", { uniforms: { uInk: sim }, fragment: { color: "color.rgb += texture(uInk, screenUv()).r;" } });
|
|
1275
1492
|
*/
|
|
1276
1493
|
sim(options: SimOptions): Promise<Sim | null>;
|
|
1277
1494
|
/**
|
|
@@ -1279,19 +1496,19 @@ export interface GL {
|
|
|
1279
1496
|
* (`vec4 f = texture(uFlow, screenUv()); vec2 push = (f.rg * 2.0 - 1.0) * f.a;`). Made on
|
|
1280
1497
|
* the first plane that reads uFlow, or here. Called again with options, it changes them.
|
|
1281
1498
|
* null when GL is off, or where half-float targets can't be rendered (uFlow then uses
|
|
1282
|
-
* the input module's
|
|
1499
|
+
* the input module's umber.touch(), when it is loaded).
|
|
1283
1500
|
*/
|
|
1284
1501
|
flow(options?: FlowOptions): Promise<Sim | null>;
|
|
1285
1502
|
/**
|
|
1286
1503
|
* Soft round stamps into one field of a sim: along the pointer's path while it moves,
|
|
1287
1504
|
* and wherever brush.paint(x, y) says. null when `sim` is null.
|
|
1288
|
-
* @example const dye =
|
|
1505
|
+
* @example const dye = umber.brush(sim, { field: "dye", radius: 30, color: [1, 0.4, 0.2, 1] });
|
|
1289
1506
|
*/
|
|
1290
1507
|
brush(sim: Sim | null, options?: BrushOptions): Brush | null;
|
|
1291
1508
|
/**
|
|
1292
1509
|
* Get the NEXT page ready before it is on the page (its own file, chunks/warm.js): the
|
|
1293
|
-
* images its [data-
|
|
1294
|
-
* element will ask: data-
|
|
1510
|
+
* images its [data-umber] elements show fetched, decoded and on the GPU (keyed the way the
|
|
1511
|
+
* element will ask: data-umber-src, or the srcset candidate the browser will pick), their
|
|
1295
1512
|
* programs compiled, and each drawn once offscreen. When the elements arrive they claim
|
|
1296
1513
|
* all of it: the first frame does no work. Never blocks the page (uploads go in idle
|
|
1297
1514
|
* moments) and never rejects. The promise is also the progress: p.value 0 -> 1, a Signal
|
|
@@ -1301,37 +1518,97 @@ export interface GL {
|
|
|
1301
1518
|
* fine), a parsed Document, Barba's data.next ({ container } / { html } / { url }), or a
|
|
1302
1519
|
* list of these. { hover: true | "selector" }: from now on, a link's page is preloaded
|
|
1303
1520
|
* when the pointer slows down over it (off on Save-Data; { hover: false } stops it).
|
|
1304
|
-
* @example barba.hooks.leave((data) => {
|
|
1305
|
-
* @example
|
|
1521
|
+
* @example barba.hooks.leave((data) => { umber.preload(data.next.url.href); }); // braces: Barba waits for a returned promise
|
|
1522
|
+
* @example umber.preload({ hover: "a.project-link" });
|
|
1306
1523
|
*/
|
|
1307
|
-
preload(
|
|
1524
|
+
preload(
|
|
1525
|
+
what: PreloadSource | PreloadSource[] | { hover: boolean | string },
|
|
1526
|
+
fn?: (progress: number) => void,
|
|
1527
|
+
): Loading;
|
|
1308
1528
|
/**
|
|
1309
1529
|
* Get THIS page ready (chunks/warm.js): every plane in root (default: the page) loads its
|
|
1310
1530
|
* image or text even when far from the screen, compiles, and is drawn once offscreen.
|
|
1311
1531
|
* Resolves when all of them can draw (each plane waits 5 s at most, once chunks/fx.js is in); p.value is a 0..1 progress for a
|
|
1312
1532
|
* preloader. With GL off it resolves at once with value 1.
|
|
1313
|
-
* @example const p =
|
|
1533
|
+
* @example const p = umber.warm(null, (v) => (bar.style.scale = `${v} 1`)); await p; loader.remove();
|
|
1314
1534
|
*/
|
|
1315
1535
|
warm(root?: string | ParentNode | null, fn?: (progress: number) => void): Loading;
|
|
1316
1536
|
/**
|
|
1317
|
-
* The data-
|
|
1537
|
+
* The data-umber-placeholder string for an image (about 50 characters: a preview 6 cells on
|
|
1318
1538
|
* its long side, 4 bits per channel). Run it once (the console will do) and paste the string into the
|
|
1319
1539
|
* element's attribute. null when GL is off or the file can't be read.
|
|
1320
|
-
* @example await
|
|
1540
|
+
* @example await umber.placeholder("/img/dunes.jpg") // "UF..."
|
|
1321
1541
|
*/
|
|
1322
1542
|
placeholder(src: string | Element): Promise<string | null>;
|
|
1323
|
-
readonly info:
|
|
1543
|
+
readonly info: UmberInfo;
|
|
1324
1544
|
readonly canvas: HTMLCanvasElement | null;
|
|
1325
1545
|
readonly context: WebGL2RenderingContext | null;
|
|
1326
1546
|
}
|
|
1327
1547
|
|
|
1328
|
-
/**
|
|
1329
|
-
export
|
|
1548
|
+
/** umber.info.gpu: the device's GPU level, read once when GL starts. */
|
|
1549
|
+
export interface GpuInfo {
|
|
1550
|
+
/** 0 (software) to 5 (strong desktop GPU). */
|
|
1551
|
+
level: number;
|
|
1552
|
+
tier: "high" | "mid" | "low";
|
|
1553
|
+
mobile: boolean;
|
|
1554
|
+
renderer: string;
|
|
1555
|
+
/** "rule: <what matched>", "default" or "url" (?umber-gpu). */
|
|
1556
|
+
reason: string;
|
|
1557
|
+
maxTexture: number;
|
|
1558
|
+
/** Max bytes of image textures kept on the GPU. */
|
|
1559
|
+
textureBudget: number;
|
|
1560
|
+
/** Above this CSS width the canvas DPR is cut (createUmber dpr aside); Infinity: never. */
|
|
1561
|
+
wide: number;
|
|
1562
|
+
}
|
|
1563
|
+
|
|
1564
|
+
/** umber.info while GL runs: what the last frame did, and what the GPU holds. */
|
|
1565
|
+
export interface UmberStats {
|
|
1566
|
+
state:
|
|
1567
|
+
"dormant" | "asleep" | "idle" | "active" | "paused" | "off (canvas host)" | "off (context lost)" | "off (error)";
|
|
1568
|
+
backend: "webgl2";
|
|
1569
|
+
tier: "high" | "mid" | "low";
|
|
1570
|
+
/** null until it is read. */
|
|
1571
|
+
gpu: GpuInfo | null;
|
|
1572
|
+
fps: number;
|
|
1573
|
+
frameMs: number;
|
|
1574
|
+
renders: number;
|
|
1575
|
+
skipped: number;
|
|
1576
|
+
rendersPerSec: number;
|
|
1577
|
+
draws: number;
|
|
1578
|
+
planes: number;
|
|
1579
|
+
visible: number;
|
|
1580
|
+
textures: number;
|
|
1581
|
+
textureMB: number;
|
|
1582
|
+
gpuMB: number;
|
|
1583
|
+
/** What every render target holds on the GPU (absent until chunks/fx.js is here). */
|
|
1584
|
+
targetMB?: number;
|
|
1585
|
+
uploads: number;
|
|
1586
|
+
programs: number;
|
|
1587
|
+
/** Why the loop keeps drawing; [] once it sleeps. */
|
|
1588
|
+
busy: string[];
|
|
1589
|
+
dpr: number;
|
|
1590
|
+
scale: number;
|
|
1591
|
+
width: number;
|
|
1592
|
+
height: number;
|
|
1593
|
+
}
|
|
1594
|
+
|
|
1595
|
+
/** umber.info: UmberStats while GL runs; only its state before GL started; once GL went off, the last numbers it had. */
|
|
1596
|
+
export type UmberInfo =
|
|
1597
|
+
UmberStats | (Partial<Omit<UmberStats, "state">> & { state: "dormant" | `off (${UmberReason})` });
|
|
1598
|
+
|
|
1599
|
+
/** What umber.preload() takes: an image or page URL, an element or container, a parsed Document, or a router's next page. */
|
|
1600
|
+
export type PreloadSource =
|
|
1601
|
+
| string
|
|
1602
|
+
| URL
|
|
1603
|
+
| ParentNode
|
|
1604
|
+
| { container?: ParentNode; html?: string; url?: string | { href?: string } }
|
|
1605
|
+
| null
|
|
1606
|
+
| undefined;
|
|
1330
1607
|
|
|
1331
|
-
/**
|
|
1332
|
-
export type Loading = Promise<void> & Signal
|
|
1608
|
+
/** umber.preload() / umber.warm(): resolves when ready; value is the 0..1 progress (a Signal: usable as a uniform). */
|
|
1609
|
+
export type Loading = Promise<void> & Signal;
|
|
1333
1610
|
|
|
1334
|
-
/**
|
|
1611
|
+
/** umber.leave(glsl, options). */
|
|
1335
1612
|
export interface LeaveOptions {
|
|
1336
1613
|
/** Seconds uProgress takes from 0 to 1. @default 1 */
|
|
1337
1614
|
duration?: number;
|
|
@@ -1339,11 +1616,11 @@ export interface LeaveOptions {
|
|
|
1339
1616
|
ease?: Ease;
|
|
1340
1617
|
/** Your own uniforms (a { value } is read every frame). uPrev, uNext and uProgress are Umber's. */
|
|
1341
1618
|
uniforms?: Record<string, unknown>;
|
|
1342
|
-
/** Arm on a pointerdown on a same-origin link and on back / forward, also with no
|
|
1619
|
+
/** Arm on a pointerdown on a same-origin link and on back / forward, also with no umber.transition(). @default true */
|
|
1343
1620
|
links?: boolean;
|
|
1344
1621
|
}
|
|
1345
1622
|
|
|
1346
|
-
/**
|
|
1623
|
+
/** umber.flip(els, change, options) and plane.land(options). */
|
|
1347
1624
|
export interface FlipOptions {
|
|
1348
1625
|
/** Seconds. @default 0.8 */
|
|
1349
1626
|
duration?: number;
|
|
@@ -1361,7 +1638,7 @@ export interface FreeRect {
|
|
|
1361
1638
|
height: number;
|
|
1362
1639
|
}
|
|
1363
1640
|
|
|
1364
|
-
/**
|
|
1641
|
+
/** umber.target(options). Sizes in device px. */
|
|
1365
1642
|
export interface TargetOptions {
|
|
1366
1643
|
/** Default: the canvas width (device px). The target never follows the canvas: call resize(). */
|
|
1367
1644
|
width?: number;
|
|
@@ -1388,7 +1665,7 @@ export interface Target {
|
|
|
1388
1665
|
/** The first attachment's texture (null once released or while the context is lost). */
|
|
1389
1666
|
readonly texture: WebGLTexture | null;
|
|
1390
1667
|
/** Every attachment's texture (MRT). */
|
|
1391
|
-
readonly textures:
|
|
1668
|
+
readonly textures: readonly (WebGLTexture | null)[];
|
|
1392
1669
|
/** Its resolved framebuffer (for readPixels, or another library's reads). */
|
|
1393
1670
|
readonly framebuffer: WebGLFramebuffer | null;
|
|
1394
1671
|
readonly width: number;
|
|
@@ -1415,10 +1692,10 @@ export interface Target {
|
|
|
1415
1692
|
release(): void;
|
|
1416
1693
|
}
|
|
1417
1694
|
|
|
1418
|
-
/** A size in texels: one number, or one per GPU level 0-5 (
|
|
1695
|
+
/** A size in texels: one number, or one per GPU level 0-5 (umber.info.gpu.level). */
|
|
1419
1696
|
export type SimSize = number | number[];
|
|
1420
1697
|
|
|
1421
|
-
/**
|
|
1698
|
+
/** umber.sim(options). Give `next` (one field, "state") or `fields` + `passes`. */
|
|
1422
1699
|
export interface SimOptions {
|
|
1423
1700
|
/** Texels across (or one per GPU level 0-5). @default 128 */
|
|
1424
1701
|
size?: SimSize;
|
|
@@ -1439,7 +1716,7 @@ export interface SimOptions {
|
|
|
1439
1716
|
/** Named fields: each is a sampler of its name in every pass. */
|
|
1440
1717
|
fields?: Record<string, { size?: SimSize; type?: "u8" | "half" | "float"; init?: string }>;
|
|
1441
1718
|
/** In order, every step: `next` writes field `into` (its old value still readable); `iterations` per step (or one per GPU level). */
|
|
1442
|
-
passes?:
|
|
1719
|
+
passes?: { into: string; next: string; iterations?: number | number[] }[];
|
|
1443
1720
|
/** The field sim.texture is. @default the first */
|
|
1444
1721
|
output?: string;
|
|
1445
1722
|
/** Your uniforms for every pass (numbers, arrays, targets, textures). Change them with sim.set(). */
|
|
@@ -1479,7 +1756,7 @@ export interface Sim {
|
|
|
1479
1756
|
release(): void;
|
|
1480
1757
|
}
|
|
1481
1758
|
|
|
1482
|
-
/**
|
|
1759
|
+
/** umber.brush(sim, options). */
|
|
1483
1760
|
export interface BrushOptions {
|
|
1484
1761
|
/** The field it paints. @default the first */
|
|
1485
1762
|
field?: string;
|
|
@@ -1501,7 +1778,7 @@ export interface Brush {
|
|
|
1501
1778
|
release(): void;
|
|
1502
1779
|
}
|
|
1503
1780
|
|
|
1504
|
-
/**
|
|
1781
|
+
/** umber.flow(options). */
|
|
1505
1782
|
export interface FlowOptions {
|
|
1506
1783
|
/** Texels across (or one per GPU level 0-5). @default [32, 48, 64, 64, 96, 128] */
|
|
1507
1784
|
size?: SimSize;
|
|
@@ -1516,7 +1793,7 @@ export interface FlowOptions {
|
|
|
1516
1793
|
/** window.Umber (the <script> build). */
|
|
1517
1794
|
export interface UmberGlobal {
|
|
1518
1795
|
readonly version: string;
|
|
1519
|
-
|
|
1796
|
+
createUmber(options?: UmberOptions): Umber;
|
|
1520
1797
|
/** DOM <-> three.js maths and frame-rate-free smoothing. No engine needed. */
|
|
1521
1798
|
readonly math: UmberMath;
|
|
1522
1799
|
/** An optional module for the engine on the page and every later one (module scripts call it themselves). */
|
|
@@ -1525,8 +1802,7 @@ export interface UmberGlobal {
|
|
|
1525
1802
|
|
|
1526
1803
|
declare global {
|
|
1527
1804
|
interface Window {
|
|
1528
|
-
|
|
1805
|
+
/** The npm build's chunk folder, set before createUmber() (createUmber({ base }) wins). umber.js loads from its own folder. */
|
|
1529
1806
|
UmberConfig?: { base?: string };
|
|
1530
1807
|
}
|
|
1531
|
-
const Umber: UmberGlobal;
|
|
1532
1808
|
}
|