@occluze/umber 0.0.0-stage → 0.2.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/README.md +64 -2
- package/dist/chunks/capture.js +2 -0
- package/dist/chunks/covers.js +2 -0
- package/dist/chunks/flip.js +2 -0
- package/dist/chunks/fx.js +102 -0
- package/dist/chunks/gl.js +180 -0
- package/dist/chunks/glsl.js +239 -0
- package/dist/chunks/inspect.js +6 -0
- package/dist/chunks/instances.js +93 -0
- package/dist/chunks/layers.js +21 -0
- package/dist/chunks/licence.js +2 -0
- package/dist/chunks/morph.js +2 -0
- package/dist/chunks/restore.js +2 -0
- package/dist/chunks/shapes.js +2 -0
- package/dist/chunks/sim.js +22 -0
- package/dist/chunks/text.js +52 -0
- package/dist/chunks/video.js +2 -0
- package/dist/chunks/views.js +2 -0
- package/dist/chunks/warm.js +2 -0
- package/dist/modules/debug.js +36 -0
- package/dist/modules/debug.mjs +36 -0
- package/dist/modules/handoff.js +2 -0
- package/dist/modules/handoff.mjs +2 -0
- package/dist/modules/input.js +2 -0
- package/dist/modules/input.mjs +2 -0
- package/dist/modules/router-swap.js +13 -0
- package/dist/modules/router.js +2 -0
- package/dist/modules/router.mjs +2 -0
- package/dist/modules/scroll.js +2 -0
- package/dist/modules/scroll.mjs +2 -0
- package/dist/modules/scrub.js +8 -0
- package/dist/modules/scrub.mjs +8 -0
- package/dist/umber.css +2 -0
- package/dist/umber.js +2 -0
- package/dist/umber.mjs +2 -0
- package/docs/npm.md +69 -0
- package/package.json +118 -4
- package/types/debug.d.ts +27 -0
- package/types/esm.d.ts +33 -0
- package/types/handoff.d.ts +116 -0
- package/types/input.d.ts +235 -0
- package/types/router.d.ts +181 -0
- package/types/scroll.d.ts +132 -0
- package/types/scrub.d.ts +74 -0
- package/types/umber.d.ts +1532 -0
package/types/umber.d.ts
ADDED
|
@@ -0,0 +1,1532 @@
|
|
|
1
|
+
// -----------------------------------------
|
|
2
|
+
// UMBER: PUBLIC TYPES FOR SITE CODE
|
|
3
|
+
// -----------------------------------------
|
|
4
|
+
|
|
5
|
+
// Editor autocomplete and type checks for site code (VS Code, Astro, Vite, TS or
|
|
6
|
+
// checkJs projects). Nothing here runs.
|
|
7
|
+
//
|
|
8
|
+
// <script src=".../umber@x.y.z/umber.js"> -> window.Umber: { version, createGL, math, use }
|
|
9
|
+
// import { createGL } from "@occluze/umber" (types/esm.d.ts)
|
|
10
|
+
//
|
|
11
|
+
// For the <script> tag: copy this file into your project (e.g. src/types/umber.d.ts) and
|
|
12
|
+
// list it in tsconfig/jsconfig "include", or add /// <reference path="./types/umber.d.ts" />.
|
|
13
|
+
//
|
|
14
|
+
// Hand-written on purpose: one readable file, also the most compact exact API reference
|
|
15
|
+
// to paste into an AI assistant. Keep it in step with src/types.ts and src/core/create.ts
|
|
16
|
+
// (test/types.test.ts checks the members of Umber and of the engine).
|
|
17
|
+
//
|
|
18
|
+
// ATTRIBUTE CHEAT SHEET (the DOM is the API)
|
|
19
|
+
//
|
|
20
|
+
// data-gl="image | video | text | shader | layer | group" make this element a GPU plane
|
|
21
|
+
// (group: draws the GL planes inside it as one, through
|
|
22
|
+
// its own data-gl-effect; docs/ai/groups.md)
|
|
23
|
+
// data-gl-pass="grade grain" effects run over the whole GL frame (on <html> or <body>)
|
|
24
|
+
// or over one group; per effect -blend, -opacity, -scale
|
|
25
|
+
// data-gl-effect="ripple tint" effects (defined with gl.effect), applied in order
|
|
26
|
+
// data-gl-<effect>-<option>="1.2" an effect option (also --gl-<effect>-<option> in CSS)
|
|
27
|
+
// data-gl-<effect>-trigger auto (default) | scroll | load | manual | hover, for effects with `play`
|
|
28
|
+
// data-gl-<effect>-delay / -duration / -ease / -start the play's timing ("top 90%")
|
|
29
|
+
// data-gl-shader="name" with data-gl="shader": the gl.shader() it draws
|
|
30
|
+
// data-gl-layer="name" with data-gl="layer": the gl.layer() it runs
|
|
31
|
+
// data-gl-src="url" another image than the <img> inside
|
|
32
|
+
// data-gl-fit="cover|contain|fill" object-fit for the texture
|
|
33
|
+
// data-gl-live measure every frame (sticky, fixed or transformed parents)
|
|
34
|
+
// data-gl-clip="false" draw it without its parents' clips (overflow, clip-path, masks)
|
|
35
|
+
// data-gl-wrap="x | y" on a track: its planes wrap around it (an endless gallery)
|
|
36
|
+
// data-gl-order="1" draw order
|
|
37
|
+
// data-gl-instances="64" drawn many times in one call: "64", "tiles 24x16",
|
|
38
|
+
// "chars" | "words" | "lines" (GL text), "echo 6", "ink 3000"
|
|
39
|
+
// data-gl-placeholder="UF…" a blurred preview until the image loads (chunks/warm.js;
|
|
40
|
+
// make it with gl.placeholder(src))
|
|
41
|
+
// data-gl-id="hero" the same id on two pages: the image flies across (morph),
|
|
42
|
+
// with any router (gl.transition() makes it tighter)
|
|
43
|
+
// data-gl-morph-duration="1" / -ease on the element you go to: the flight's timing
|
|
44
|
+
// (also --gl-morph-duration / --gl-morph-ease in CSS)
|
|
45
|
+
// data-gl-shader-<option> / data-gl-layer-<option> a gl.shader() / gl.layer() option
|
|
46
|
+
// data-gl-above a DOM element that must sit on top of the canvas
|
|
47
|
+
// data-gl-disable (on <body>) GL off for this page
|
|
48
|
+
// data-gl-host where the canvas goes (else Umber makes one)
|
|
49
|
+
// data-gl-video-autopause="false" keep a muted loop video playing off screen
|
|
50
|
+
// data-gl-scrub (+ -start, -end, -track, -smooth, -source, -frames...) scroll-scrubbed
|
|
51
|
+
// video: needs the scrub module (types/scrub.d.ts)
|
|
52
|
+
// Modules (same version as umber.js): modules/scrub.js (types/scrub.d.ts) and
|
|
53
|
+
// modules/debug.js, the HUD, outlines and markers (types/debug.d.ts).
|
|
54
|
+
// gl.inspect(el) prints why an element is (not) drawn.
|
|
55
|
+
// Events also go to document: umber:ready (detail = the engine), umber:lost,
|
|
56
|
+
// umber:restored, umber:destroy.
|
|
57
|
+
// From JS: gl.add(el, { type, effects, options }) writes these attributes for you.
|
|
58
|
+
// Written by Umber: html.has-gl, data-gl-status="loading|ready|error", data-gl-media,
|
|
59
|
+
// data-gl-play, data-gl-morphing, data-gl-canvas on the canvas, and
|
|
60
|
+
// data-gl-view="loading|ready|off|error|lost" on gl.attach() / gl.view() elements.
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The next page, as a router hands it over: its HTML, a parsed Document, its container
|
|
64
|
+
* (or a fragment), Barba's cached { html }, or a promise of any of them. "" or null: not
|
|
65
|
+
* known yet.
|
|
66
|
+
*/
|
|
67
|
+
export type NextPage =
|
|
68
|
+
| string
|
|
69
|
+
| ParentNode
|
|
70
|
+
| { html?: string }
|
|
71
|
+
| null
|
|
72
|
+
| undefined
|
|
73
|
+
| PromiseLike<string | ParentNode | { html?: string } | null | undefined | void>;
|
|
74
|
+
|
|
75
|
+
/** A plain { value } anyone can animate (GSAP, Motion, your own code) or read. */
|
|
76
|
+
export interface Signal<T = number> {
|
|
77
|
+
value: T;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
export interface LenisLike {
|
|
81
|
+
animatedScroll?: number;
|
|
82
|
+
scroll?: number;
|
|
83
|
+
velocity?: number;
|
|
84
|
+
isHorizontal?: boolean;
|
|
85
|
+
options?: { wrapper?: Window | Element; orientation?: string };
|
|
86
|
+
on(event: "scroll", fn: (...args: any[]) => void): unknown;
|
|
87
|
+
off?(event: "scroll", fn: (...args: any[]) => void): unknown;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export interface ScrollObject {
|
|
91
|
+
x?: number | (() => number);
|
|
92
|
+
y?: number | (() => number);
|
|
93
|
+
/** px per frame, like Lenis. Omit it to let Umber work it out from the position. */
|
|
94
|
+
velocity?: number | (() => number);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export interface Env {
|
|
98
|
+
readonly reducedMotion: boolean;
|
|
99
|
+
readonly isTouch: boolean;
|
|
100
|
+
readonly isDesktop: boolean;
|
|
101
|
+
readonly forcedColors: boolean;
|
|
102
|
+
readonly saveData: boolean;
|
|
103
|
+
readonly webgl2: boolean;
|
|
104
|
+
readonly designer: boolean;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export interface GLOptions {
|
|
108
|
+
/**
|
|
109
|
+
* Where Umber reads scroll from, read-only: it never creates, drives or configures it.
|
|
110
|
+
* The default also follows <body> when it is the page's scroller (html { overflow: hidden }).
|
|
111
|
+
* @default window
|
|
112
|
+
* @example createGL({ scroll: lenis }) // your Lenis instance
|
|
113
|
+
* @example createGL({ scroll: document.querySelector(".scroller") })
|
|
114
|
+
* @example createGL({ scroll: { y: () => myScroll.y } }) // anything else
|
|
115
|
+
*/
|
|
116
|
+
scroll?: Window | Element | LenisLike | ScrollObject | null;
|
|
117
|
+
/**
|
|
118
|
+
* "auto": Umber runs its own requestAnimationFrame loop, which sleeps when nothing moves.
|
|
119
|
+
* false: nothing runs until you call gl.render(time) from your own loop.
|
|
120
|
+
* @default "auto"
|
|
121
|
+
* @example createGL({ loop: false }); gsap.ticker.add((t) => gl.render(t * 1000));
|
|
122
|
+
*/
|
|
123
|
+
loop?: "auto" | false;
|
|
124
|
+
/**
|
|
125
|
+
* Which devices draw DOM planes in GL (the rest keep the plain DOM, and nothing downloads).
|
|
126
|
+
* "desktop" = hover + fine pointer + at least 768 px wide. Anything else is "desktop", with a warning.
|
|
127
|
+
* @default "all"
|
|
128
|
+
* @example createGL({ devices: "desktop" })
|
|
129
|
+
* @example createGL({ devices: (env) => !env.isTouch })
|
|
130
|
+
*/
|
|
131
|
+
devices?: "all" | "desktop" | false | ((env: Env) => boolean);
|
|
132
|
+
/**
|
|
133
|
+
* Effects only where this CSS media query matches, read when the page loads. Without code: data-gl-media on <body>.
|
|
134
|
+
* @example createGL({ media: "(min-width: 900px)" }) // off in narrower windows
|
|
135
|
+
* @example createGL({ media: "(min-width: 600px)" }) // off on phones
|
|
136
|
+
*/
|
|
137
|
+
media?: string;
|
|
138
|
+
/**
|
|
139
|
+
* Device pixel ratio: a max, [min, max], or a max per device tier.
|
|
140
|
+
* @default { high: 2, mid: 1.5, low: 1 }
|
|
141
|
+
* @example createGL({ dpr: [1, 1.5] })
|
|
142
|
+
*/
|
|
143
|
+
dpr?: number | [number, number] | { high?: number; mid?: number; low?: number };
|
|
144
|
+
/**
|
|
145
|
+
* Max canvas pixels (width × height × dpr²); the DPR drops to stay under it.
|
|
146
|
+
* @default 12e6
|
|
147
|
+
* @example createGL({ pixelBudget: 8e6 })
|
|
148
|
+
*/
|
|
149
|
+
pixelBudget?: number;
|
|
150
|
+
/**
|
|
151
|
+
* Lower the resolution only while the GPU can't keep up, and raise it again after.
|
|
152
|
+
* @default true
|
|
153
|
+
*/
|
|
154
|
+
adaptive?: boolean;
|
|
155
|
+
/**
|
|
156
|
+
* prefers-reduced-motion. "static": planes draw, without motion (plays show at once; uTime
|
|
157
|
+
* and a layer's time stand still, so an animating shader or layer draws one still frame).
|
|
158
|
+
* "off": GL stays off and the DOM shows.
|
|
159
|
+
* @default "static"
|
|
160
|
+
*/
|
|
161
|
+
reducedMotion?: "static" | "off";
|
|
162
|
+
/**
|
|
163
|
+
* Skip GL when the browser asks to save data (Save-Data / Data Saver, a 2G connection, prefers-reduced-data).
|
|
164
|
+
* @default true
|
|
165
|
+
*/
|
|
166
|
+
respectSaveData?: boolean;
|
|
167
|
+
/**
|
|
168
|
+
* Run inside the Webflow Designer / Editor too (normally the DOM shows there).
|
|
169
|
+
* @default false
|
|
170
|
+
*/
|
|
171
|
+
designer?: boolean;
|
|
172
|
+
/**
|
|
173
|
+
* The element the canvas goes in: an element or a selector.
|
|
174
|
+
* @default [data-gl-host], or a fixed full-screen host Umber makes as the first child of <body> (next to it when <body> has a zoom)
|
|
175
|
+
* @example createGL({ host: ".gl-host" })
|
|
176
|
+
*/
|
|
177
|
+
host?: string | HTMLElement;
|
|
178
|
+
/**
|
|
179
|
+
* "over": the canvas sits above the page (pointer-events: none). "under": behind it.
|
|
180
|
+
* @default "over"
|
|
181
|
+
*/
|
|
182
|
+
layer?: "over" | "under";
|
|
183
|
+
/**
|
|
184
|
+
* z-index of the host Umber makes.
|
|
185
|
+
* @default 1 ("over") or -1 ("under")
|
|
186
|
+
*/
|
|
187
|
+
zIndex?: number;
|
|
188
|
+
/**
|
|
189
|
+
* A selector <html> matches while your router changes the page: meanwhile Umber acts as
|
|
190
|
+
* inside gl.transition() (plays held, planes measured every frame, data-gl-id images
|
|
191
|
+
* noted), with no hook to write. Off by default (a flag a site forgets to clear would
|
|
192
|
+
* keep Umber measuring); it ends by itself after 8 s and starts again only once <html>
|
|
193
|
+
* stopped matching in between.
|
|
194
|
+
* @example createGL({ busy: "html.is-changing" }) // Swup
|
|
195
|
+
* @example createGL({ busy: 'html[aria-busy="true"]' }) // Turbo
|
|
196
|
+
* @example createGL({ busy: "html[data-astro-transition]" }) // Astro's client router
|
|
197
|
+
*/
|
|
198
|
+
busy?: string;
|
|
199
|
+
/**
|
|
200
|
+
* 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
|
+
* @default the folder umber.js came from (npm: this version's CDN folder, or window.UmberConfig.base)
|
|
202
|
+
* @example createGL({ base: "/vendor/umber/" })
|
|
203
|
+
*/
|
|
204
|
+
base?: string;
|
|
205
|
+
/**
|
|
206
|
+
* true: debug notes in the console (also ?umber-debug in the URL). An object also sets
|
|
207
|
+
* what the debug module shows, once it is loaded (modules/debug.js).
|
|
208
|
+
* @default false
|
|
209
|
+
* @example createGL({ debug: true })
|
|
210
|
+
* @example createGL({ modules: [Debug], debug: { outlines: true, markers: true } })
|
|
211
|
+
*/
|
|
212
|
+
debug?: boolean | DebugOptions;
|
|
213
|
+
/**
|
|
214
|
+
* false silences warnings. Errors (a shader that does not compile, a callback that threw)
|
|
215
|
+
* always show.
|
|
216
|
+
* @default true
|
|
217
|
+
*/
|
|
218
|
+
warnings?: boolean;
|
|
219
|
+
/**
|
|
220
|
+
* Optional modules from the start, as gl.use() would take them.
|
|
221
|
+
* @example createGL({ modules: [Scrub] }) // import { Scrub } from "@occluze/umber/scrub"
|
|
222
|
+
* @example createGL({ modules: [[Scrub, { cacheMB: 64 }]] })
|
|
223
|
+
*/
|
|
224
|
+
modules?: Array<UmberModule | [UmberModule, Record<string, unknown>]>;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** What the debug module (modules/debug.js) shows. */
|
|
228
|
+
export interface DebugOptions {
|
|
229
|
+
/** The stats panel: fps graph, draws, planes, textures, why busy. Ctrl/Cmd+Shift+H hides it. @default true */
|
|
230
|
+
hud?: boolean;
|
|
231
|
+
/** A box and a label (kind, effects, status) on every plane, where GL draws it. @default false */
|
|
232
|
+
outlines?: boolean;
|
|
233
|
+
/** Lines where scroll plays start, and where scrubbed videos start and end. @default false */
|
|
234
|
+
markers?: boolean;
|
|
235
|
+
/**
|
|
236
|
+
* What each effect stack costs per frame, in the HUD: `cpu` (A/B on every GPU: frames
|
|
237
|
+
* with and without it, timed to a finished GPU) and `gpu` (a timer per draw, where the
|
|
238
|
+
* browser has EXT_disjoint_timer_query_webgl2). Keeps the loop drawing and switches each
|
|
239
|
+
* stack off for a few frames in turn: while you build only. ?umber-debug=hud,cost.
|
|
240
|
+
* @default false
|
|
241
|
+
*/
|
|
242
|
+
cost?: boolean;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** gl.inspect(el): one plane, and every reason it is not drawn on the visible screen right now. */
|
|
246
|
+
export interface InspectReport {
|
|
247
|
+
el: Element;
|
|
248
|
+
kind: "image" | "video" | "shader" | "layer" | "text" | "group" | null;
|
|
249
|
+
status: string;
|
|
250
|
+
/** On the visible screen in GL this frame. */
|
|
251
|
+
drawn: boolean;
|
|
252
|
+
/** Each reason it is not drawn (empty when drawn), e.g. "it is off screen (...)". */
|
|
253
|
+
why: string[];
|
|
254
|
+
/** Worth knowing but not stopping it, e.g. an unknown effect name ("it draws without it"). */
|
|
255
|
+
notes?: string[];
|
|
256
|
+
/** Where its pixels come from: an image or video URL, "the element's text", a shader. */
|
|
257
|
+
source?: string;
|
|
258
|
+
/** The device tier ("high" | "mid" | "low"), plus the scrub tier on scrubbed video. */
|
|
259
|
+
tier?: string;
|
|
260
|
+
effects?: Array<{ name: string; options: Record<string, unknown> }>;
|
|
261
|
+
/** used: the compiled shader reads it (null while it compiles). */
|
|
262
|
+
uniforms?: Record<string, { value: unknown; used: boolean | null }>;
|
|
263
|
+
program?: { key: string; ready: boolean } | null;
|
|
264
|
+
rect?: { x: number; y: number; width: number; height: number } | null;
|
|
265
|
+
inView?: boolean;
|
|
266
|
+
near?: boolean;
|
|
267
|
+
texture?: string;
|
|
268
|
+
modules?: string[];
|
|
269
|
+
/**
|
|
270
|
+
* Every parent (or the element itself) that cuts it, and how GL draws the cut: "scissor"
|
|
271
|
+
* (straight: free), "shader" (rounded, shaped or turned: per pixel), "corners" (a rounded
|
|
272
|
+
* parent hugging the image), "pruned" (cuts nothing), "ignored" (that parent turns past
|
|
273
|
+
* the viewer right now). A data-gl-occlude panel over it is `by: "occlude"`; "uncut": it
|
|
274
|
+
* overlaps, but no shader slot was free, so GL draws over it there this frame.
|
|
275
|
+
*/
|
|
276
|
+
clips?: Array<{ el: Element; by: "overflow" | "clip-path" | "clip" | "occlude"; shape: string; how: "scissor" | "shader" | "corners" | "pruned" | "ignored" | "uncut" }>;
|
|
277
|
+
/** Where GL draws it (null when it has no plane). */
|
|
278
|
+
geometry?: {
|
|
279
|
+
/** "none": flat (translate / scale at most); "2d": rotated, skewed or mirrored; "3d": tilted (perspective). */
|
|
280
|
+
transform: "none" | "2d" | "3d";
|
|
281
|
+
/** uSize: its size on screen (for a turned element: its layout proportions at its on-screen scale). */
|
|
282
|
+
size: [number, number];
|
|
283
|
+
/** The drawn quad, viewport px: top-left, top-right, bottom-right, bottom-left of the element's own box. */
|
|
284
|
+
corners: Array<[number, number]>;
|
|
285
|
+
/**
|
|
286
|
+
* What measures it every frame right now, or null: "CSS transition on <div.card>, 0.32 s
|
|
287
|
+
* left", "infinite CSS animation on <div.track>", "scroll-driven CSS animation on ...",
|
|
288
|
+
* "data-gl-live", "a sticky or fixed parent", "live mode (a page change, gl.live())".
|
|
289
|
+
*/
|
|
290
|
+
live: string | null;
|
|
291
|
+
} | null;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* An optional Umber module (modules/scrub.js, @occluze/umber/scrub). Elements with
|
|
296
|
+
* data-gl-<name> are handed to it; its handle is at plane[name] (gl.plane(el)?.scrub).
|
|
297
|
+
* Writing your own is possible but the plane hooks are advanced (see src/types.ts).
|
|
298
|
+
*/
|
|
299
|
+
export interface UmberModule {
|
|
300
|
+
name: string;
|
|
301
|
+
version?: string;
|
|
302
|
+
/** Attributes it owns, without "data-gl-". @default [name] */
|
|
303
|
+
attributes?: string[];
|
|
304
|
+
/** `keep(off)` records an undo in the gl.scope() running when it is called, and returns it. `root()`: that scope's container, else document. */
|
|
305
|
+
install?(engine: GL, options: Record<string, unknown>, keep: <T>(made: T) => T, root: () => ParentNode): void;
|
|
306
|
+
plane?(ctx: any): any;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
export type GLReason =
|
|
310
|
+
| "disabled"
|
|
311
|
+
| "no-webgl2"
|
|
312
|
+
| "device"
|
|
313
|
+
| "editor"
|
|
314
|
+
| "forced-colors"
|
|
315
|
+
| "reduced-motion"
|
|
316
|
+
| "save-data"
|
|
317
|
+
| "context"
|
|
318
|
+
| "load-failed"
|
|
319
|
+
| "load-timeout"
|
|
320
|
+
| "unlicensed"
|
|
321
|
+
| "context-lost"
|
|
322
|
+
| "error"
|
|
323
|
+
| "server"
|
|
324
|
+
| "destroyed";
|
|
325
|
+
|
|
326
|
+
export type TickPhase = "measure" | "update" | "render";
|
|
327
|
+
|
|
328
|
+
export interface Frame {
|
|
329
|
+
/** Seconds since the engine started, lag-smoothed. */
|
|
330
|
+
time: number;
|
|
331
|
+
/** Seconds since the previous frame. */
|
|
332
|
+
dt: number;
|
|
333
|
+
/** dt relative to 60fps (1 at 60fps, 0.5 at 120fps). */
|
|
334
|
+
ratio: number;
|
|
335
|
+
frame: number;
|
|
336
|
+
/** The first frame after the loop woke up, or after a long gap (a hidden tab): its dt is a stand-in (the screen's frame time, 33 ms after a gap), not the real time. */
|
|
337
|
+
woke: boolean;
|
|
338
|
+
/** px; velocity in px per second. */
|
|
339
|
+
scroll: { x: number; y: number; velocity: number };
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Any ease Umber accepts: "umber" (default), "linear", "ease-out", "cubic-bezier(a,b,c,d)",
|
|
344
|
+
* "expo.out", CSS "linear(0, 0.6 40%, 1)", "spring" / "spring(0.3)" (a spring with that
|
|
345
|
+
* bounce, 0..0.95, default 0.2; it settles in the tween's duration), ... or a function.
|
|
346
|
+
*/
|
|
347
|
+
export type Ease = string | ((t: number) => number);
|
|
348
|
+
|
|
349
|
+
export interface TweenVars {
|
|
350
|
+
value: number;
|
|
351
|
+
/** Seconds. @default 1 */
|
|
352
|
+
duration?: number;
|
|
353
|
+
/** Seconds. @default 0 */
|
|
354
|
+
delay?: number;
|
|
355
|
+
/** A "spring(...)" ease runs as a real spring: it starts with the speed the value had under the tween it replaces, and ends at rest. */
|
|
356
|
+
ease?: Ease;
|
|
357
|
+
onUpdate?: () => void;
|
|
358
|
+
onComplete?: () => void;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/** Umber's own small tween. Await it: it resolves when it completes or is killed. */
|
|
362
|
+
export interface Tween extends PromiseLike<void> {
|
|
363
|
+
readonly progress: number;
|
|
364
|
+
readonly done: boolean;
|
|
365
|
+
readonly paused: boolean;
|
|
366
|
+
pause(): Tween;
|
|
367
|
+
play(): Tween;
|
|
368
|
+
kill(): Tween;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** "text": a GL text plane painted again with other units (a rewrap, new text); not after a colour-only repaint. */
|
|
372
|
+
export type PlaneEvent = "ready" | "enter" | "leave" | "resize" | "error" | "destroy" | "text";
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* One line, word or character of a GL text (plane.text). `t`, `x`, `y`, `z` are four
|
|
376
|
+
* plain numbers per unit (0 at first) that any library can tween; their meaning is the
|
|
377
|
+
* effect's. They are kept by index when the text rewraps.
|
|
378
|
+
* @example gsap.to(gl.plane(h1).text.lines, { t: 1, stagger: 0.08 })
|
|
379
|
+
*/
|
|
380
|
+
export interface TextUnit {
|
|
381
|
+
/** 0-based, in reading order: the same numbers as glyph() in GLSL. */
|
|
382
|
+
readonly index: number;
|
|
383
|
+
/** Its text (a line's and a word's with white space collapsed). */
|
|
384
|
+
readonly text: string;
|
|
385
|
+
/** Where it is at rest: element CSS px from the element's top-left (border box). */
|
|
386
|
+
readonly box: { x: number; y: number; w: number; h: number };
|
|
387
|
+
t: number;
|
|
388
|
+
x: number;
|
|
389
|
+
y: number;
|
|
390
|
+
z: number;
|
|
391
|
+
/** Umber's own tween on one of its numbers. @example lines[i].tween("t", { value: 1, delay: i * 0.08 }) */
|
|
392
|
+
tween(channel: "t" | "x" | "y" | "z", vars: TweenVars): Tween;
|
|
393
|
+
}
|
|
394
|
+
export interface TextLine extends TextUnit {
|
|
395
|
+
/** Its first and last word, and character. */
|
|
396
|
+
readonly words: [number, number];
|
|
397
|
+
readonly chars: [number, number];
|
|
398
|
+
}
|
|
399
|
+
export interface TextWord extends TextUnit {
|
|
400
|
+
readonly line: number;
|
|
401
|
+
/** Its first and last character. */
|
|
402
|
+
readonly chars: [number, number];
|
|
403
|
+
}
|
|
404
|
+
export interface TextChar extends TextUnit {
|
|
405
|
+
readonly line: number;
|
|
406
|
+
readonly word: number;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
/**
|
|
410
|
+
* plane.text on data-gl="text" planes (undefined on others, and until chunks/text.js
|
|
411
|
+
* arrived): its lines, words and characters, empty until the first paint. Where the site
|
|
412
|
+
* split its own lines ([data-line] elements), those are the lines. The counts also reach
|
|
413
|
+
* CSS on the element: var(--gl-lines), var(--gl-words), var(--gl-chars).
|
|
414
|
+
*/
|
|
415
|
+
export interface PlaneText {
|
|
416
|
+
readonly lines: TextLine[];
|
|
417
|
+
readonly words: TextWord[];
|
|
418
|
+
readonly chars: TextChar[];
|
|
419
|
+
/** +1 per paint that changed the units. */
|
|
420
|
+
readonly version: number;
|
|
421
|
+
/**
|
|
422
|
+
* One gl.progress() per line or word (not characters): `start` / `end` written as for
|
|
423
|
+
* the element, measured from each unit's own edges ("top 80%": this line's top at 80 %
|
|
424
|
+
* of the screen). Make them again after a "text" event.
|
|
425
|
+
* @example plane.text.progress("lines", { start: "top 85%", end: "top 55%" }).forEach((p, i) => p.on("change", () => (lines[i].t = p.value)))
|
|
426
|
+
*/
|
|
427
|
+
progress(level: "lines" | "words", options?: ProgressOptions): ProgressSignal[];
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
export interface Plane {
|
|
431
|
+
readonly id: number;
|
|
432
|
+
readonly el: HTMLElement;
|
|
433
|
+
readonly kind: "image" | "video" | "shader" | "layer" | "text" | "group";
|
|
434
|
+
/** "loading" | "ready" | "error" */
|
|
435
|
+
readonly status: string;
|
|
436
|
+
/** This frame's viewport rect as [x, y, width, height] (CSS px): rect[2] is the width. */
|
|
437
|
+
readonly rect: Float32Array;
|
|
438
|
+
/** On screen (the real viewport, like gl.track()); "enter" / "leave" fire as it changes. */
|
|
439
|
+
readonly inView: boolean;
|
|
440
|
+
/** 0 as the element's top enters at the bottom of the screen, 1 as its bottom leaves at the top. */
|
|
441
|
+
readonly progress: number;
|
|
442
|
+
readonly effects: Array<{ name: string; options: Record<string, any> }>;
|
|
443
|
+
/** data-gl="text": its lines, words and characters, as data and tweenable numbers. */
|
|
444
|
+
readonly text?: PlaneText;
|
|
445
|
+
/** data-gl-instances (or an effect's `instances`): its count and per-instance data. Undefined without. */
|
|
446
|
+
readonly instances?: PlaneInstances;
|
|
447
|
+
/** Plain { value } objects: animate them with anything. */
|
|
448
|
+
readonly uniforms: Record<string, Signal<any>>;
|
|
449
|
+
/**
|
|
450
|
+
* Set a uniform. A Signal (gl.progress(el), gl.pointer, any { value }) links it: the
|
|
451
|
+
* uniform follows that Signal from then on. A CSS colour string ("#f30", "oklch(...)",
|
|
452
|
+
* "var(--brand)") becomes [r, g, b, a] in sRGB (var() read from the element now).
|
|
453
|
+
* @example plane.set("uStory", gl.progress(el.closest("section")))
|
|
454
|
+
*/
|
|
455
|
+
set(name: string, value: unknown): Plane;
|
|
456
|
+
get(name: string): unknown;
|
|
457
|
+
/** Umber's own tween on a uniform. */
|
|
458
|
+
tween(name: string, vars: TweenVars): Tween;
|
|
459
|
+
/** Run the plane's `play` uniform(s) to 1 with their effect's options. */
|
|
460
|
+
play(vars?: Partial<TweenVars> & { uniform?: string }): Tween | null;
|
|
461
|
+
/**
|
|
462
|
+
* Let go of its element (chunks/flip.js): resolves with its rect, viewport CSS px, to
|
|
463
|
+
* move with anything (GSAP...). It stays put on screen while the page scrolls, and its
|
|
464
|
+
* element's own DOM stays hidden. land() flies it home.
|
|
465
|
+
* @example const r = await plane.lift(); gsap.to(r, { x: 0, y: 0, width: innerWidth, height: innerHeight });
|
|
466
|
+
*/
|
|
467
|
+
lift(): Promise<FreeRect | null>;
|
|
468
|
+
/** Fly home to its element from wherever it is drawn (after lift()). */
|
|
469
|
+
land(options?: FlipOptions): Promise<void>;
|
|
470
|
+
on(event: PlaneEvent, fn: (plane: Plane) => void): () => void;
|
|
471
|
+
off(event: PlaneEvent, fn: (plane: Plane) => void): void;
|
|
472
|
+
wake(frames?: number): void;
|
|
473
|
+
/** The element shows as normal DOM again. gl.scan(el) brings it back. */
|
|
474
|
+
destroy(): void;
|
|
475
|
+
revert(): void;
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
/** gl.add(el, options): the attributes it writes, as options (the same contract). */
|
|
479
|
+
export interface AddOptions {
|
|
480
|
+
/** data-gl. @default "image" (or "video" for a <video>) */
|
|
481
|
+
type?: "image" | "video" | "text" | "shader" | "layer" | "group";
|
|
482
|
+
/** data-gl-effect: effect names, applied in order. @example effects: ["dissolve"] */
|
|
483
|
+
effects?: string[] | string;
|
|
484
|
+
/** data-gl-<effect>-<option>, per effect. @example options: { dissolve: { scale: 6, trigger: "manual" } } */
|
|
485
|
+
options?: Record<string, Record<string, unknown>>;
|
|
486
|
+
/** data-gl-shader (with type "shader"). */
|
|
487
|
+
shader?: string;
|
|
488
|
+
/** data-gl-layer (with type "layer"). */
|
|
489
|
+
layer?: string;
|
|
490
|
+
/** data-gl-src: another image than the <img> inside. */
|
|
491
|
+
src?: string;
|
|
492
|
+
/** data-gl-fit. */
|
|
493
|
+
fit?: "cover" | "contain" | "fill";
|
|
494
|
+
/** data-gl-order: draw order. */
|
|
495
|
+
order?: number;
|
|
496
|
+
/** data-gl-live: measure every frame. */
|
|
497
|
+
live?: boolean;
|
|
498
|
+
/**
|
|
499
|
+
* data-gl-clip: false draws it without its parents' clips (overflow, clip-path, CSS masks).
|
|
500
|
+
* Its own clip-path still cuts it. @default true
|
|
501
|
+
*/
|
|
502
|
+
clip?: boolean;
|
|
503
|
+
/** data-gl-instances: "64", "tiles 24x16", "chars", "echo 6", "ink 3000". */
|
|
504
|
+
instances?: string | number;
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/**
|
|
508
|
+
* plane.instances on a plane drawn as instances (data-gl-instances, or an effect's
|
|
509
|
+
* `instances`): the per-instance numbers of the attributes its effects declare.
|
|
510
|
+
* @example const seeds = plane.instances.data("aSeed"); seeds[0] = 0.5; plane.instances.update("aSeed");
|
|
511
|
+
*/
|
|
512
|
+
export interface PlaneInstances {
|
|
513
|
+
/** How many are drawn (text: its characters, words or lines). */
|
|
514
|
+
readonly count: number;
|
|
515
|
+
readonly mode: "count" | "tiles" | "chars" | "words" | "lines" | "echo" | "ink";
|
|
516
|
+
/** An attribute's numbers (count x its size), to change in place; then update(name). null when no effect declares it. */
|
|
517
|
+
data(name: string): Float32Array | null;
|
|
518
|
+
/** Replace an attribute's numbers (count x its size); sent to the GPU on the next frame. */
|
|
519
|
+
set(name: string, values: ArrayLike<number>): PlaneInstances;
|
|
520
|
+
/** After changing data(name) in place: send it on the next frame (all of them without a name). */
|
|
521
|
+
update(name?: string): void;
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
export interface EffectContext {
|
|
525
|
+
name: string;
|
|
526
|
+
el: HTMLElement;
|
|
527
|
+
plane: Plane;
|
|
528
|
+
engine: GL;
|
|
529
|
+
options: Record<string, any>;
|
|
530
|
+
uniforms: Record<string, Signal<any>>;
|
|
531
|
+
readonly reducedMotion: boolean;
|
|
532
|
+
viewport: { width: number; height: number };
|
|
533
|
+
/** Only set during update(). */
|
|
534
|
+
frame: Frame | null;
|
|
535
|
+
trackMouse(on: boolean): void;
|
|
536
|
+
busy(on: boolean): void;
|
|
537
|
+
wake(frames?: number): void;
|
|
538
|
+
/** addEventListener for each type; returns one cleanup (also run when the plane goes). */
|
|
539
|
+
listen(target: EventTarget, map: Record<string, (e: Event) => void>): () => void;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
/**
|
|
543
|
+
* An effect: GLSL snippets for named slots plus uniforms. The slots, inputs and helpers
|
|
544
|
+
* are a fixed contract (src/gl/shaders.ts; names are only ever added):
|
|
545
|
+
* vertex.head / vertex.main (change `pos`, px offset in the element's own axes, using `uv`)
|
|
546
|
+
* fragment.head / uv / color (vec4) / alpha (float)
|
|
547
|
+
* inputs: vUv, uSize, uViewport, uRect, uMouse, uTime, uScrollVelocity, uProgress,
|
|
548
|
+
* uPlaneMatrix (mat3: own px -> viewport px; a translation when flat),
|
|
549
|
+
* uSurface (vec4: where this draw goes, viewport px x, y, w, h; today the
|
|
550
|
+
* canvas: 0, 0, uViewport), uBleed (px the quad reaches past the element:
|
|
551
|
+
* the `bleed` option; vUv then runs below 0 and above 1 there);
|
|
552
|
+
* fragment only: uAlpha, uDpr, uImage, uImageSize, uCanvas
|
|
553
|
+
* a rotated, skewed or 3D-tilted element: vUv, uMouse and `pos` follow its own edges;
|
|
554
|
+
* uSize is its layout size at its on-screen scale; uRect = centre - uSize / 2, uSize
|
|
555
|
+
* helpers, fragment only: sampleImage(uv), sampleRaw(uv) (premultiplied: what a blur
|
|
556
|
+
* adds up), fitUv(uv) (the image's object-fit crop:
|
|
557
|
+
* texture(uMap, fitUv(uv)) keeps a map in line with its image),
|
|
558
|
+
* roundedBox(p, size, vec4 radii) (radii per corner: top-left, top-right,
|
|
559
|
+
* bottom-right, bottom-left; px)
|
|
560
|
+
* helpers added when called (with chunks/glsl.js; glyph() with chunks/text.js; the
|
|
561
|
+
* plane waits for it, its DOM showing): noise(vec2 | vec3), fbm(vec2),
|
|
562
|
+
* rotate2d(angle), umberHash(vec2 | vec3), glyph(uv), screenPx() (fragment
|
|
563
|
+
* only: this pixel on screen, viewport CSS px, whatever turns the element),
|
|
564
|
+
* screenUv() (fragment only: this pixel on screen, 0..1 over the viewport,
|
|
565
|
+
* 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 gl.chunk() of that name, added
|
|
567
|
+
* once per program (only included chunks are compiled)
|
|
568
|
+
* two effects on one plane that declare the same top-level name in their heads (a
|
|
569
|
+
* function, const, global or #define) each get their own (renamed e<N>_name)
|
|
570
|
+
* glyph(uv), GL text: Glyph { float line, word, char, lines, words, chars;
|
|
571
|
+
* vec4 lineBox, wordBox, charBox (x, y, width, height in uv); float ink }
|
|
572
|
+
* after the alpha slot, Umber cuts the plane where its parents cut it in the DOM
|
|
573
|
+
* (overflow, clip-path); names starting with uUmber / umber are reserved
|
|
574
|
+
*/
|
|
575
|
+
export interface EffectDef {
|
|
576
|
+
/**
|
|
577
|
+
* Uniforms it adds, with their first value; Umber writes the GLSL declarations.
|
|
578
|
+
* number -> float, [x, y(, z, w)] -> vec2..4, 9 numbers -> mat3, 16 -> mat4, a URL
|
|
579
|
+
* string -> sampler2D (fragment only), and a Signal
|
|
580
|
+
* ({ value }: gl.progress(el), gl.pointer, gl.velocity, your own) is followed live. A CSS
|
|
581
|
+
* colour string ("#ff3300", "oklch(70% 0.15 30)", "var(--brand)") -> vec4 [r, g, b, a]
|
|
582
|
+
* in sRGB, converted by the browser (var() read from each element once). Anything
|
|
583
|
+
* holding a `texture` (the input module's gl.texture(), gl.touch(), gl.rects()) ->
|
|
584
|
+
* 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 gl.texture()
|
|
586
|
+
* (numbers that fit no type above warn only when the GLSL reads them undeclared).
|
|
587
|
+
* @example uniforms: { uShow: 0, uTint: [1, 0.4, 0.2], uNoise: "/noise.png" }
|
|
588
|
+
* @example uniforms: { uTint: "var(--brand)" }
|
|
589
|
+
* @example uniforms: { uStory: gl.progress(".story"), uPointer: gl.pointer }
|
|
590
|
+
*/
|
|
591
|
+
uniforms?: Record<string, unknown>;
|
|
592
|
+
/**
|
|
593
|
+
* Options read per element: data-gl-<effect>-<key> > --gl-<effect>-<key> (CSS) > this
|
|
594
|
+
* default. Number, boolean, array and CSS colour options become uniforms too: effect
|
|
595
|
+
* "ripple", option "strength" -> uRippleStrength. Give a colour option a colour default
|
|
596
|
+
* ({ color: "#fff" }) so every element has the vec4. A string with a "/" is an image
|
|
597
|
+
* path -> sampler2D (a per-element map: data-gl-depth-map="/img/a-depth.webp" ->
|
|
598
|
+
* uDepthMap; give it a default path). `bleed` (px) draws the plane that much past its
|
|
599
|
+
* element on every side (uBleed: the largest of its effects).
|
|
600
|
+
* @example options: { strength: 1, duration: 1.2, ease: "expo.out" }
|
|
601
|
+
* @example options: { map: "/img/blank.webp", bleed: 40 }
|
|
602
|
+
*/
|
|
603
|
+
options?: Record<string, unknown>;
|
|
604
|
+
/**
|
|
605
|
+
* Uniform values used instead when the visitor prefers reduced motion (and
|
|
606
|
+
* createGL({ reducedMotion }) is "static", the default): keep a fade, still a wave.
|
|
607
|
+
* @example reduced: { uWave: 0 }
|
|
608
|
+
*/
|
|
609
|
+
reduced?: Record<string, unknown>;
|
|
610
|
+
/**
|
|
611
|
+
* A uniform Umber plays 0 -> 1 by itself, with the trigger options every playable
|
|
612
|
+
* effect understands: trigger (auto | scroll | load | manual | hover), delay, duration, ease,
|
|
613
|
+
* start ("top 90%").
|
|
614
|
+
* @example play: "uShow"
|
|
615
|
+
*/
|
|
616
|
+
play?: string;
|
|
617
|
+
/**
|
|
618
|
+
* Grid segments per side: more than 1 when vertex.main bends the plane.
|
|
619
|
+
* @default 1
|
|
620
|
+
*/
|
|
621
|
+
segments?: number;
|
|
622
|
+
/**
|
|
623
|
+
* Draw the plane many times in ONE draw call (chunks/instances.js). The element's own
|
|
624
|
+
* data-gl-instances wins. GLSL then has `instance` (0..uInstances - 1) and `uInstances`,
|
|
625
|
+
* plus per mode:
|
|
626
|
+
* "64" (or { count: 64 }) copies: place each with `instance` in vertex.main
|
|
627
|
+
* "tiles 24x16" one quad per tile: `tile` (vec4 column, row, columns, rows),
|
|
628
|
+
* `tileCenter` (vec2, uv); move tiles apart with `pos`
|
|
629
|
+
* "chars" | "words" | "lines" GL text, one quad per unit: `unitValue` (vec4: its t, x, y, z from
|
|
630
|
+
* plane.text, what GSAP writes; .x is t), `unitBox` (vec4, its box in uv)
|
|
631
|
+
* "echo 6" ("echo 6 delay 0.05") 5 copies where the plane was 0.05 s, 0.1 s... ago (a trail):
|
|
632
|
+
* `echoOffset` (vec2 px); instance 0 is the plane, drawn on top;
|
|
633
|
+
* copies that caught up are not drawn
|
|
634
|
+
* "ink 3000" ("size 3", "luma") 3000 particles seeded where the plane has ink (alpha, or
|
|
635
|
+
* brightness), each a `size` px piece of the plane:
|
|
636
|
+
* `inkPoint` (vec4: uv, ink 0..1, found)
|
|
637
|
+
* Every input is there in vertex and fragment code; your attributes in vertex code only.
|
|
638
|
+
* @example instances: "tiles 16x10", vertex: { main: "pos.xy += (tileCenter - 0.5) * uSize * uSpread;" }
|
|
639
|
+
*/
|
|
640
|
+
instances?: number | string | { count?: number; tiles?: string | [number, number]; units?: "chars" | "words" | "lines"; echo?: number; delay?: number; ink?: number; size?: number; source?: "alpha" | "luma" };
|
|
641
|
+
/**
|
|
642
|
+
* Per-instance numbers, as `in` attributes of the vertex shader (declared for you): a size
|
|
643
|
+
* (1-4: a stable random 0..1 per instance and component) or a function of the instance
|
|
644
|
+
* that returns 1-4 numbers. Change them later with plane.instances.
|
|
645
|
+
* @example attributes: { aSeed: 2, aHue: (i, n) => i / n }
|
|
646
|
+
*/
|
|
647
|
+
attributes?: Record<string, number | ((i: number, count: number) => number | ArrayLike<number>)>;
|
|
648
|
+
/** vertex.main changes `pos` (vec3, px offset) using `uv` (0..1). */
|
|
649
|
+
vertex?: { head?: string; main?: string };
|
|
650
|
+
/**
|
|
651
|
+
* fragment.uv changes `uv` before the image is sampled; color changes `color` (vec4);
|
|
652
|
+
* alpha changes `alpha` (float, already the element's opacity and corners: multiply it).
|
|
653
|
+
* head holds functions and globals shared between slots, and #include "name" lines
|
|
654
|
+
* (gl.chunk()).
|
|
655
|
+
* Helpers: sampleImage(uv), sampleRaw(uv), roundedBox(p, size, vec4 radii), noise(vec2 | vec3), fbm(vec2),
|
|
656
|
+
* rotate2d(a), umberHash(vec2 | vec3), screenPx(), screenUv().
|
|
657
|
+
* @example fragment: { color: "color.rgb *= uTint;" }
|
|
658
|
+
*/
|
|
659
|
+
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?: (ctx: EffectContext) => void | (() => void);
|
|
662
|
+
/** Every drawn frame while the plane is on screen (ctx.frame is set). */
|
|
663
|
+
update?: (ctx: EffectContext) => void;
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
export interface ShaderDef {
|
|
667
|
+
/** Set `color` (vec4) from `uv`. */
|
|
668
|
+
fragment: string;
|
|
669
|
+
head?: string;
|
|
670
|
+
uniforms?: Record<string, unknown>;
|
|
671
|
+
/**
|
|
672
|
+
* Options read per element: data-gl-shader-<key> > --gl-shader-<key> > this default.
|
|
673
|
+
* Number, boolean and array options become uniforms named u + Option (speed -> uSpeed).
|
|
674
|
+
*/
|
|
675
|
+
options?: Record<string, unknown>;
|
|
676
|
+
/** Keep drawing every frame while visible (not under reduced motion with reducedMotion "static": uTime stands still). @default true */
|
|
677
|
+
animate?: boolean;
|
|
678
|
+
setup?: (ctx: EffectContext) => void | (() => void);
|
|
679
|
+
update?: (ctx: EffectContext) => void;
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
export interface LayerRect {
|
|
683
|
+
x: number;
|
|
684
|
+
y: number;
|
|
685
|
+
width: number;
|
|
686
|
+
height: number;
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
export interface LayerContext {
|
|
690
|
+
name: string;
|
|
691
|
+
el: HTMLElement;
|
|
692
|
+
gl: WebGL2RenderingContext;
|
|
693
|
+
canvas: HTMLCanvasElement;
|
|
694
|
+
options: Record<string, any>;
|
|
695
|
+
state: Record<string, any>;
|
|
696
|
+
engine: GL;
|
|
697
|
+
rect: LayerRect;
|
|
698
|
+
px: LayerRect;
|
|
699
|
+
viewport: { width: number; height: number };
|
|
700
|
+
dpr: number;
|
|
701
|
+
mouse: { x: number; y: number };
|
|
702
|
+
scrollVelocity: number;
|
|
703
|
+
opacity: number;
|
|
704
|
+
time: number;
|
|
705
|
+
frame: Frame | null;
|
|
706
|
+
readonly reducedMotion: boolean;
|
|
707
|
+
/** 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
|
+
wake(frames?: number): void;
|
|
709
|
+
busy(on: boolean): void;
|
|
710
|
+
three(renderer: any): void;
|
|
711
|
+
}
|
|
712
|
+
|
|
713
|
+
export interface LayerDef {
|
|
714
|
+
/** Read per element into ctx.options: data-gl-layer-<key> > --gl-layer-<key> > this default. */
|
|
715
|
+
options?: Record<string, unknown>;
|
|
716
|
+
/** Once, when the element comes near the screen. May be async; return a cleanup. */
|
|
717
|
+
setup?: (ctx: LayerContext) => void | (() => void) | Promise<void | (() => void)>;
|
|
718
|
+
/** Draw (ctx.three(renderer) first for three.js). */
|
|
719
|
+
render: (ctx: LayerContext) => void;
|
|
720
|
+
/** The element or the screen changed size (before render). */
|
|
721
|
+
resize?: (ctx: LayerContext) => void;
|
|
722
|
+
/** 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
|
+
animate?: boolean;
|
|
724
|
+
/** Clip drawing to the element box. @default true */
|
|
725
|
+
scissor?: boolean;
|
|
726
|
+
/** Fade with the element's (and its parents') opacity. @default true */
|
|
727
|
+
followOpacity?: boolean;
|
|
728
|
+
/** Max device px per CSS px for this layer (a heavy scene renders smaller, upscaled). @default the canvas's */
|
|
729
|
+
dpr?: number;
|
|
730
|
+
}
|
|
731
|
+
|
|
732
|
+
// -----------------------------------------
|
|
733
|
+
// Tracking, three.js views and DOM <-> world maths
|
|
734
|
+
// -----------------------------------------
|
|
735
|
+
|
|
736
|
+
export interface TrackRect {
|
|
737
|
+
x: number;
|
|
738
|
+
y: number;
|
|
739
|
+
width: number;
|
|
740
|
+
height: number;
|
|
741
|
+
}
|
|
742
|
+
|
|
743
|
+
export type TrackEvent = "enter" | "leave" | "resize" | "destroy";
|
|
744
|
+
|
|
745
|
+
export interface TrackOptions {
|
|
746
|
+
/** Measure every frame while near the screen. @default auto (sticky, fixed or pinned parents) */
|
|
747
|
+
live?: boolean;
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
/** gl.track(el): where an element is, every frame, without layout reads or WebGL. */
|
|
751
|
+
export interface Tracker {
|
|
752
|
+
readonly el: Element;
|
|
753
|
+
/** Viewport CSS px this frame (y down), like getBoundingClientRect. */
|
|
754
|
+
readonly rect: TrackRect;
|
|
755
|
+
readonly inView: boolean;
|
|
756
|
+
/** Within 1.5 screens of the viewport. */
|
|
757
|
+
readonly near: boolean;
|
|
758
|
+
/** 0 as its top enters at the bottom of the screen, 1 as its bottom leaves at the top. */
|
|
759
|
+
readonly progress: number;
|
|
760
|
+
readonly dpr: number;
|
|
761
|
+
readonly destroyed: boolean;
|
|
762
|
+
on(event: TrackEvent, fn: (t: Tracker) => void): () => void;
|
|
763
|
+
off(event: TrackEvent, fn: (t: Tracker) => void): void;
|
|
764
|
+
/** Automatic when the element leaves the page. */
|
|
765
|
+
destroy(): void;
|
|
766
|
+
revert(): void;
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
export interface ProgressOptions {
|
|
770
|
+
/**
|
|
771
|
+
* Where 0 is: "<element edge> <viewport line>", with optional offsets ("top+=100 80%"), or
|
|
772
|
+
* a CSS view-timeline range: "cover 0%", "entry 50%", "exit", "contain", "entry-crossing",
|
|
773
|
+
* "exit-crossing" (a name alone is its 0% here, its 100% in `end`; "cover 50px" is 50 px of
|
|
774
|
+
* scrolling past its 0%). @default "top bottom"
|
|
775
|
+
*/
|
|
776
|
+
start?: string;
|
|
777
|
+
/** Where 1 is. @default "bottom top" */
|
|
778
|
+
end?: string;
|
|
779
|
+
/**
|
|
780
|
+
* Also write the value (4 decimals, only when it changed) to this CSS custom property on
|
|
781
|
+
* the element, through a rule of Umber's own stylesheet (not its style attribute).
|
|
782
|
+
* @example gl.progress(".hero", { css: "--hero" }) // .hero img { opacity: calc(1 - var(--hero)) }
|
|
783
|
+
*/
|
|
784
|
+
css?: string;
|
|
785
|
+
/** Measure every frame (a parent moved by transforms). @default auto (sticky, fixed or pinned parents) */
|
|
786
|
+
live?: boolean;
|
|
787
|
+
}
|
|
788
|
+
|
|
789
|
+
/** gl.progress(el): a live 0..1 as el scrolls from `start` to `end`. Usable as a uniform. */
|
|
790
|
+
export interface ProgressSignal extends Signal<number> {
|
|
791
|
+
readonly el: Element;
|
|
792
|
+
readonly start: string;
|
|
793
|
+
readonly end: string;
|
|
794
|
+
readonly destroyed: boolean;
|
|
795
|
+
on(event: "change" | "destroy", fn: (p: ProgressSignal) => void): () => void;
|
|
796
|
+
off(event: "change" | "destroy", fn: (p: ProgressSignal) => void): void;
|
|
797
|
+
/** Automatic when el leaves the page. */
|
|
798
|
+
destroy(): void;
|
|
799
|
+
revert(): void;
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
/**
|
|
803
|
+
* gl.pointer: the pointer (mouse, pen or touch). Usable as a uniform (vec2).
|
|
804
|
+
* More inputs (gl.drag, gl.velocityOf any Signal, gl.trail, gl.press, gl.step) come with
|
|
805
|
+
* the input module: gl.use(Input) from "@occluze/umber/input" (types/input.d.ts).
|
|
806
|
+
*/
|
|
807
|
+
export interface PointerSignal {
|
|
808
|
+
/** [x, y] in viewport CSS px (y down). The viewport's centre until the pointer first moves. */
|
|
809
|
+
readonly value: [number, number];
|
|
810
|
+
/** [vx, vy] in px per second, smoothed; 0 when it rests. Usable as a uniform too. */
|
|
811
|
+
readonly velocity: { readonly value: [number, number] };
|
|
812
|
+
/** true once the pointer moved over the page (or a finger touched it). */
|
|
813
|
+
readonly active: boolean;
|
|
814
|
+
}
|
|
815
|
+
|
|
816
|
+
/**
|
|
817
|
+
* gl.scope(fn, container): everything Umber made inside fn, undone with revert(). The
|
|
818
|
+
* scope has gl's creating methods: after an await, call them on the scope (s.add, s.track...).
|
|
819
|
+
*/
|
|
820
|
+
export interface Scope {
|
|
821
|
+
/** Where selector strings resolve inside the scope (null: the document). */
|
|
822
|
+
readonly container: Element | null;
|
|
823
|
+
readonly reverted: boolean;
|
|
824
|
+
/** Resolves once fn (and every run(fn)) finished, also when async. */
|
|
825
|
+
readonly ready: Promise<void>;
|
|
826
|
+
/** Run more code in this scope (later, from an event handler). */
|
|
827
|
+
run<T>(fn: (scope: Scope) => T): T;
|
|
828
|
+
/** Destroy everything made in the scope, newest first; previous definitions come back. */
|
|
829
|
+
revert(): void;
|
|
830
|
+
destroy(): void;
|
|
831
|
+
add(el: string | Element, options?: AddOptions): Promise<Plane | null>;
|
|
832
|
+
track(el: string | Element, options?: TrackOptions): Tracker;
|
|
833
|
+
progress(el: string | Element, options?: ProgressOptions): ProgressSignal;
|
|
834
|
+
attach(el: string | Element, options: AttachOptions): View;
|
|
835
|
+
view(el: string | Element, options?: SharedViewOptions): View;
|
|
836
|
+
effect(name: string, def: EffectDef): void;
|
|
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). */
|
|
874
|
+
export interface ThreeRendererLike {
|
|
875
|
+
domElement?: HTMLCanvasElement;
|
|
876
|
+
setSize?(width: number, height: number, updateStyle?: boolean): void;
|
|
877
|
+
setPixelRatio?(ratio: number): void;
|
|
878
|
+
render?(scene: any, camera: any): void;
|
|
879
|
+
getContext?(): WebGLRenderingContext | WebGL2RenderingContext;
|
|
880
|
+
dispose?(): void;
|
|
881
|
+
[key: string]: any;
|
|
882
|
+
}
|
|
883
|
+
|
|
884
|
+
/** The object a view's animate / render / resize get. */
|
|
885
|
+
export interface ViewFrame {
|
|
886
|
+
time: number;
|
|
887
|
+
dt: number;
|
|
888
|
+
ratio: number;
|
|
889
|
+
frame: number;
|
|
890
|
+
/** The drawing's size, CSS px. */
|
|
891
|
+
width: number;
|
|
892
|
+
height: number;
|
|
893
|
+
/** Device px per CSS px it renders at (DPR range, pixel budget and adaptive scale applied). */
|
|
894
|
+
dpr: number;
|
|
895
|
+
rect: TrackRect;
|
|
896
|
+
progress: number;
|
|
897
|
+
/** Scroll velocity, px per second. */
|
|
898
|
+
velocity: number;
|
|
899
|
+
/** prefers-reduced-motion: animate() still runs, but returning true no longer loops. */
|
|
900
|
+
reducedMotion: boolean;
|
|
901
|
+
renderer: any;
|
|
902
|
+
scene: any;
|
|
903
|
+
camera: any;
|
|
904
|
+
view: View;
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
export interface ViewSetupContext {
|
|
908
|
+
el: HTMLElement;
|
|
909
|
+
renderer: any;
|
|
910
|
+
scene: any;
|
|
911
|
+
camera: any;
|
|
912
|
+
view: View;
|
|
913
|
+
}
|
|
914
|
+
|
|
915
|
+
export interface ViewOptions {
|
|
916
|
+
scene?: any;
|
|
917
|
+
camera?: any;
|
|
918
|
+
/** 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 | void;
|
|
922
|
+
/** Once, when the element comes near the screen. May be async (compileAsync) and return a cleanup. */
|
|
923
|
+
setup?: (ctx: ViewSetupContext) => void | (() => void) | Promise<void | (() => void)>;
|
|
924
|
+
/** After Umber sized the drawing (a PerspectiveCamera's aspect is already set). */
|
|
925
|
+
resize?: (f: ViewFrame) => void;
|
|
926
|
+
/** Devices this view runs on, instead of the engine's. @example "all" (phones on for this scene only) */
|
|
927
|
+
devices?: "all" | "desktop" | false | ((env: Env) => boolean);
|
|
928
|
+
/** A max DPR or [min, max] for this view. @default the engine's dpr */
|
|
929
|
+
dpr?: number | [number, number];
|
|
930
|
+
/** Keep a PerspectiveCamera's aspect in step with the box. @default true */
|
|
931
|
+
aspect?: boolean;
|
|
932
|
+
}
|
|
933
|
+
|
|
934
|
+
export interface AttachOptions extends ViewOptions {
|
|
935
|
+
/** Your THREE.WebGLRenderer. Its canvas goes into the element unless it is in the page already. */
|
|
936
|
+
renderer: ThreeRendererLike;
|
|
937
|
+
/** Max drawing pixels (w * h * dpr^2). @default the engine's pixelBudget, else 12e6 */
|
|
938
|
+
pixelBudget?: number;
|
|
939
|
+
/** Lower the resolution only when frames get slow. @default the engine's adaptive */
|
|
940
|
+
adaptive?: boolean;
|
|
941
|
+
/** renderer.dispose() and free its WebGL context when the view goes. false for a renderer you reuse. @default true */
|
|
942
|
+
dispose?: boolean;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
export interface SharedViewOptions extends ViewOptions {
|
|
946
|
+
/** Fade with the element's (and its parents') opacity. @default true */
|
|
947
|
+
followOpacity?: boolean;
|
|
948
|
+
/** Clip drawing to the element box. @default true */
|
|
949
|
+
scissor?: boolean;
|
|
950
|
+
}
|
|
951
|
+
|
|
952
|
+
export type ViewStatus = "loading" | "ready" | "off" | "error" | "lost" | "destroyed";
|
|
953
|
+
export type ViewEvent = "ready" | "resize" | "enter" | "leave" | "lost" | "restored" | "error" | "destroy";
|
|
954
|
+
|
|
955
|
+
/** gl.attach() / gl.view(): your three.js scene tied to an element. */
|
|
956
|
+
export interface View {
|
|
957
|
+
readonly el: HTMLElement;
|
|
958
|
+
readonly kind: "attach" | "view";
|
|
959
|
+
readonly status: ViewStatus;
|
|
960
|
+
/** false when it is not drawn on this device, failed, or was destroyed. */
|
|
961
|
+
readonly enabled: boolean;
|
|
962
|
+
/** Why it is off ("device", "save-data", ...) or failed ("setup", "render"), else null. */
|
|
963
|
+
readonly reason: string | null;
|
|
964
|
+
/** true once the first frame is drawn; false when it is off, fails or goes first. */
|
|
965
|
+
readonly ready: Promise<boolean>;
|
|
966
|
+
readonly rect: TrackRect;
|
|
967
|
+
readonly inView: boolean;
|
|
968
|
+
readonly progress: number;
|
|
969
|
+
/** The drawing's CSS px size and device px per CSS px (0 until sized). */
|
|
970
|
+
readonly width: number;
|
|
971
|
+
readonly height: number;
|
|
972
|
+
readonly dpr: number;
|
|
973
|
+
/** Draw at least `frames` more frames. */
|
|
974
|
+
wake(frames?: number): void;
|
|
975
|
+
/** Draw every frame while a reason is on: busy("drag", true) ... busy("drag", false). */
|
|
976
|
+
busy(reason: string | boolean, on?: boolean): void;
|
|
977
|
+
on(event: ViewEvent, fn: (view: View) => void): () => void;
|
|
978
|
+
off(event: ViewEvent, fn: (view: View) => void): void;
|
|
979
|
+
/** rectToWorld with this view's camera and box. */
|
|
980
|
+
rectToWorld(rect: RectLike, out?: Partial<Vec3Like> | null, z?: number): WorldBox;
|
|
981
|
+
/** worldToRect with this view's camera and box. */
|
|
982
|
+
worldToRect(point: Vec3Like): ScreenPoint;
|
|
983
|
+
/** Automatic when the element leaves the page. */
|
|
984
|
+
destroy(): void;
|
|
985
|
+
revert(): void;
|
|
986
|
+
}
|
|
987
|
+
|
|
988
|
+
export interface RectLike {
|
|
989
|
+
left?: number;
|
|
990
|
+
top?: number;
|
|
991
|
+
x?: number;
|
|
992
|
+
y?: number;
|
|
993
|
+
width: number;
|
|
994
|
+
height: number;
|
|
995
|
+
}
|
|
996
|
+
|
|
997
|
+
export interface Vec3Like {
|
|
998
|
+
x: number;
|
|
999
|
+
y: number;
|
|
1000
|
+
z: number;
|
|
1001
|
+
}
|
|
1002
|
+
|
|
1003
|
+
/** A three.js PerspectiveCamera or OrthographicCamera (duck-typed). */
|
|
1004
|
+
export interface CameraLike {
|
|
1005
|
+
isPerspectiveCamera?: boolean;
|
|
1006
|
+
isOrthographicCamera?: boolean;
|
|
1007
|
+
fov?: number;
|
|
1008
|
+
aspect?: number;
|
|
1009
|
+
zoom?: number;
|
|
1010
|
+
near?: number;
|
|
1011
|
+
far?: number;
|
|
1012
|
+
left?: number;
|
|
1013
|
+
right?: number;
|
|
1014
|
+
top?: number;
|
|
1015
|
+
bottom?: number;
|
|
1016
|
+
position?: Vec3Like;
|
|
1017
|
+
matrixWorld: { elements: ArrayLike<number> };
|
|
1018
|
+
matrixWorldInverse: { elements: ArrayLike<number> };
|
|
1019
|
+
projectionMatrix: { elements: ArrayLike<number> };
|
|
1020
|
+
projectionMatrixInverse: { elements: ArrayLike<number> };
|
|
1021
|
+
updateMatrixWorld?(force?: boolean): void;
|
|
1022
|
+
updateProjectionMatrix?(): void;
|
|
1023
|
+
}
|
|
1024
|
+
|
|
1025
|
+
export interface WorldBox {
|
|
1026
|
+
x: number;
|
|
1027
|
+
y: number;
|
|
1028
|
+
z: number;
|
|
1029
|
+
/** World units. */
|
|
1030
|
+
width: number;
|
|
1031
|
+
height: number;
|
|
1032
|
+
}
|
|
1033
|
+
|
|
1034
|
+
export interface ScreenPoint {
|
|
1035
|
+
/** Viewport CSS px (y down). */
|
|
1036
|
+
x: number;
|
|
1037
|
+
y: number;
|
|
1038
|
+
/** In front of the camera and inside its picture. */
|
|
1039
|
+
visible: boolean;
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
/** Pure helpers: Umber.math, or named imports from the npm package. `frame` = the canvas box in viewport px (default: the viewport). */
|
|
1043
|
+
export interface UmberMath {
|
|
1044
|
+
/** CSS px per world unit at `distance` (default: the camera's distance to z = 0) on a picture `heightPx` tall (default: the viewport). */
|
|
1045
|
+
pxPerWorld(camera: CameraLike, distance?: number, heightPx?: number): number;
|
|
1046
|
+
/** Aim the camera so it sees exactly `size` at z = 0, `unit` CSS px per world unit (default 1). */
|
|
1047
|
+
fitCamera<C extends CameraLike>(camera: C, size: { width: number; height: number }, unit?: number): C;
|
|
1048
|
+
/** A DOM rect's centre on the plane z (default 0) and its size there; writes x, y, z into `out`. */
|
|
1049
|
+
rectToWorld(rect: RectLike, camera: CameraLike, out?: Partial<Vec3Like> | null, options?: { z?: number; frame?: RectLike }): WorldBox;
|
|
1050
|
+
/** A world point in viewport CSS px. */
|
|
1051
|
+
worldToRect(point: Vec3Like, camera: CameraLike, frame?: RectLike): ScreenPoint;
|
|
1052
|
+
/** Lerp that feels the same at 60, 120 and 144 Hz: damp(current, target, 0.1, f.dt). */
|
|
1053
|
+
damp(current: number, target: number, amount: number, dt: number): number;
|
|
1054
|
+
clamp(v: number, min?: number, max?: number): number;
|
|
1055
|
+
lerp(a: number, b: number, t: number): number;
|
|
1056
|
+
mapRange(v: number, a: number, b: number, c: number, d: number): number;
|
|
1057
|
+
/** GLSL's smoothstep: 0 below edge0, 1 above edge1, smooth between. */
|
|
1058
|
+
smoothstep(edge0: number, edge1: number, x: number): number;
|
|
1059
|
+
/**
|
|
1060
|
+
* 0..1 as a rect scrolls from start to end, written like gl.progress().
|
|
1061
|
+
* @example rectProgress(el.getBoundingClientRect(), "top bottom", "bottom top")
|
|
1062
|
+
*/
|
|
1063
|
+
rectProgress(rect: { top?: number; y?: number; height: number }, start?: string, end?: string, viewportHeight?: number): number;
|
|
1064
|
+
}
|
|
1065
|
+
|
|
1066
|
+
/** What createGL() returns. */
|
|
1067
|
+
export interface GL {
|
|
1068
|
+
readonly version: string;
|
|
1069
|
+
/** true once GL draws this page's [data-gl] elements; false when GL is off or the page has none. */
|
|
1070
|
+
readonly ready: Promise<boolean>;
|
|
1071
|
+
readonly enabled: boolean;
|
|
1072
|
+
readonly reason: GLReason | null;
|
|
1073
|
+
readonly destroyed: boolean;
|
|
1074
|
+
/** Smoothed scroll velocity, roughly -1..1. */
|
|
1075
|
+
readonly velocity: Signal;
|
|
1076
|
+
/**
|
|
1077
|
+
* The pointer: { value: [x, y] } viewport px, velocity.value [vx, vy] px/s. Its passive
|
|
1078
|
+
* listeners attach the first time it is read. Usable as a uniform.
|
|
1079
|
+
* @example gl.effect("lens", { uniforms: { uPointer: gl.pointer }, fragment: { ... } })
|
|
1080
|
+
*/
|
|
1081
|
+
readonly pointer: PointerSignal;
|
|
1082
|
+
/**
|
|
1083
|
+
* "ready" | "lost" | "restored" | "destroy", or "frame" (adds fn to the loop). Returns off().
|
|
1084
|
+
* A "frame" callback keeps the loop running every frame; { always: false } only rides
|
|
1085
|
+
* along on frames Umber runs anyway. The four state events are also sent on document as
|
|
1086
|
+
* DOM events (umber:ready, umber:lost, umber:restored, umber:destroy; payload in detail).
|
|
1087
|
+
* @example const off = gl.on("frame", (f) => { mesh.rotation.y += f.dt; }, { phase: "update" });
|
|
1088
|
+
* @example document.addEventListener("umber:ready", (e) => console.log(e.detail));
|
|
1089
|
+
*/
|
|
1090
|
+
on(name: "frame", fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number; always?: boolean }): () => void;
|
|
1091
|
+
on(name: "ready" | "lost" | "restored" | "destroy", fn: (payload?: any) => void): () => void;
|
|
1092
|
+
/** The roots of the subtrees that entered the page (a router's new page), once per frame; <html> on the first scan. */
|
|
1093
|
+
on(name: "added", fn: (roots: Element[]) => void): () => void;
|
|
1094
|
+
/**
|
|
1095
|
+
* GL is off for this visit, from the start (a device it skips, ?umber=off) or later (a new
|
|
1096
|
+
* page with data-gl-disable): `reason` is gl.reason. Also on document as "umber:off". For
|
|
1097
|
+
* the site's own analytics.
|
|
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;
|
|
1111
|
+
/**
|
|
1112
|
+
* A named piece of GLSL an effect pulls in with a line of its own in any slot:
|
|
1113
|
+
* #include "name". Only included chunks are compiled, once per program, after Umber's
|
|
1114
|
+
* helpers and before the effects' heads; a chunk may include others (added first) and is
|
|
1115
|
+
* never renamed. Defined again: the planes using it are rebuilt. An element whose effect
|
|
1116
|
+
* includes an unknown name shows its DOM (one [umber] warning) until it is defined.
|
|
1117
|
+
* @example gl.chunk("sdf", "float sdCircle(vec2 p, float r) { return length(p) - r; }")
|
|
1118
|
+
* @example gl.effect("ring", { fragment: { head: '#include "sdf"', alpha: "alpha *= step(sdCircle(uv - 0.5, 0.4), 0.0);" } })
|
|
1119
|
+
*/
|
|
1120
|
+
chunk(name: string, glsl: string): void;
|
|
1121
|
+
/**
|
|
1122
|
+
* Use an optional module (before or after GL loads). A module script does this itself.
|
|
1123
|
+
* @example gl.use(Scrub, { cacheMB: 128 })
|
|
1124
|
+
*/
|
|
1125
|
+
use(module: UmberModule, options?: Record<string, unknown>): GL;
|
|
1126
|
+
/**
|
|
1127
|
+
* 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 (gl.scroll, gl.router: they stay
|
|
1129
|
+
* native until the answer is yes). Yes on your own computer (localhost, *.test), and when
|
|
1130
|
+
* the check can't be reached.
|
|
1131
|
+
*/
|
|
1132
|
+
licensed(): Promise<boolean>;
|
|
1133
|
+
/** gl.licensed()'s answer once it is in; null while it is asked (or before anything asked). */
|
|
1134
|
+
readonly licence: boolean | null;
|
|
1135
|
+
/**
|
|
1136
|
+
* A plane from code: writes the attributes `options` stand for and builds the plane
|
|
1137
|
+
* (now when GL is loaded). Resolves with the plane, or null when GL is off. An element
|
|
1138
|
+
* with data-gl already resolves with its own plane.
|
|
1139
|
+
* @example const plane = await gl.add(img, { effects: ["dissolve"], options: { dissolve: { trigger: "manual" } } })
|
|
1140
|
+
*/
|
|
1141
|
+
add(el: string | Element, options?: AddOptions): Promise<Plane | null>;
|
|
1142
|
+
/**
|
|
1143
|
+
* Record every Umber object made inside fn (planes from gl.add, views, trackers,
|
|
1144
|
+
* progress signals, frame callbacks, events, nextFrame, definitions, nested scopes,
|
|
1145
|
+
* targets, snapshots, sims, brushes, gl.leave, and what a module's calls make: gl.drag,
|
|
1146
|
+
* gl.texture...); scope.revert() undoes them all. Selector strings resolve inside `container`.
|
|
1147
|
+
* @example const scope = gl.scope(() => { gl.add(".card img", { effects: ["lens"] }); }, card); scope.revert();
|
|
1148
|
+
*/
|
|
1149
|
+
scope(fn?: (scope: Scope) => unknown, container?: string | Element | null): Scope;
|
|
1150
|
+
/**
|
|
1151
|
+
* A live 0..1 as el scrolls from `start` to `end`, from the measure phase (native
|
|
1152
|
+
* scroll, a scroll container or Lenis alike; also with GL off). Usable as a uniform.
|
|
1153
|
+
* Ends when el leaves the page.
|
|
1154
|
+
* @example gl.effect("story", { uniforms: { uStory: gl.progress(".story", { start: "top top", end: "bottom bottom" }) } })
|
|
1155
|
+
*/
|
|
1156
|
+
progress(el: string | Element, options?: ProgressOptions): ProgressSignal;
|
|
1157
|
+
/** fn(frame) once, on the next frame (update phase unless `phase`). Returns a cancel. */
|
|
1158
|
+
nextFrame(fn: (frame: Frame) => void, opts?: { phase?: TickPhase; order?: number }): () => void;
|
|
1159
|
+
/** Look for [data-gl] in root now (normally automatic). */
|
|
1160
|
+
scan(root?: ParentNode): void;
|
|
1161
|
+
/** Destroy planes whose element left the page (normally automatic). */
|
|
1162
|
+
prune(): void;
|
|
1163
|
+
/** gl.destroy(): the whole engine. gl.destroy(el): that element's plane only. */
|
|
1164
|
+
destroy(el?: Element): void;
|
|
1165
|
+
/** 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
|
+
invalidate(el?: Element): void;
|
|
1167
|
+
/** Measure every visible plane every frame: true, false, or for `seconds`. */
|
|
1168
|
+
live(on: boolean | number): void;
|
|
1169
|
+
wake(frames?: number): void;
|
|
1170
|
+
pause(): void;
|
|
1171
|
+
resume(): void;
|
|
1172
|
+
plane(el: Element | null | undefined): Plane | null;
|
|
1173
|
+
/**
|
|
1174
|
+
* Print one plane to the console (kind, source, tier, effects, uniforms, program) with
|
|
1175
|
+
* every reason it is not drawn, and resolve with the same report. An element inside a
|
|
1176
|
+
* plane (the <img> in a data-gl wrapper) reports that plane. null when nothing matches.
|
|
1177
|
+
* Async: what it reads comes with chunks/inspect.js, fetched on the first call.
|
|
1178
|
+
* @example const report = await gl.inspect(".hero img")
|
|
1179
|
+
*/
|
|
1180
|
+
inspect(el: string | Element): Promise<InspectReport | null>;
|
|
1181
|
+
planes(container?: ParentNode): Plane[];
|
|
1182
|
+
/** Hold every play back. Returns release(delaySeconds?); hold(promise) releases when it settles. */
|
|
1183
|
+
hold(until?: PromiseLike<unknown>): (delay?: number) => void;
|
|
1184
|
+
/** One frame from your own loop (with loop: false). time in ms, like requestAnimationFrame. */
|
|
1185
|
+
render(time?: number): void;
|
|
1186
|
+
/**
|
|
1187
|
+
* A page change, for any router: call it in the hook where a change starts, and the
|
|
1188
|
+
* function it returns in the hook where it is done. Plays are held and planes measured
|
|
1189
|
+
* every frame until then, data-gl-id images on screen are noted to fly, and an element
|
|
1190
|
+
* with a view-transition-name shows its DOM (the browser snapshots it). Optional:
|
|
1191
|
+
* planes, swaps and flights also work without it. A second call while one runs gives it
|
|
1192
|
+
* the next page and returns the same end. Ends by itself after 8 s (with a warning).
|
|
1193
|
+
*
|
|
1194
|
+
* next: the next page when the router has it (HTML, a parsed Document, its container,
|
|
1195
|
+
* or a promise of one): a matching image freezes at once instead of fading with its page.
|
|
1196
|
+
*
|
|
1197
|
+
* end(after?): after = seconds before plays start, or a promise (a View Transition's
|
|
1198
|
+
* `finished`). Resolves once the image landed and the new page's planes on screen draw
|
|
1199
|
+
* (4 s at most), so a router hook can await it.
|
|
1200
|
+
* @example let end = () => {};
|
|
1201
|
+
* swup.hooks.on("visit:start", () => (end = gl.transition()));
|
|
1202
|
+
* swup.hooks.on("page:load", (visit, { page }) => gl.transition(page.html)); // Swup 4
|
|
1203
|
+
* swup.hooks.on("visit:end", () => end());
|
|
1204
|
+
*/
|
|
1205
|
+
transition(next?: NextPage): (after?: number | PromiseLike<unknown>) => Promise<void>;
|
|
1206
|
+
/**
|
|
1207
|
+
* The page-change look (chunks/fx.js): on every page change, a copy of the old page's
|
|
1208
|
+
* GL is laid over the new page and your GLSL takes it away. Define
|
|
1209
|
+
* `vec4 leave(vec2 uv)` ((0,0) = top left; premultiplied in and out); prev(uv) is the
|
|
1210
|
+
* 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 gl.transition()'s end() (or from the
|
|
1212
|
+
* swap, with no gl.transition()). GL content only: the DOM is the router's. Copies are
|
|
1213
|
+
* taken only while a change may start (gl.transition(), a same-origin link pressed, a
|
|
1214
|
+
* back / forward), from frames the page draws anyway. null turns it off.
|
|
1215
|
+
* @example gl.leave("vec4 leave(vec2 uv) { return prev(uv) * step(uProgress, uv.y); }", { duration: 0.9 });
|
|
1216
|
+
*/
|
|
1217
|
+
leave(glsl: string | null, options?: LeaveOptions): Promise<void>;
|
|
1218
|
+
/**
|
|
1219
|
+
* A same-page layout change, flown on the GPU (chunks/flip.js): the GL elements inside
|
|
1220
|
+
* `els` are noted where they are drawn, `change()` runs (at once, before this returns),
|
|
1221
|
+
* and each flies from its old rect and corners to its new ones. The DOM jumps; only
|
|
1222
|
+
* the GL copies move. Resolves once all landed. Without GL, change() simply runs.
|
|
1223
|
+
* @example await gl.flip(".card", () => grid.classList.toggle("is-list"), { duration: 0.8, stagger: 0.03 });
|
|
1224
|
+
*/
|
|
1225
|
+
flip(els: string | Element | ArrayLike<Element>, change?: () => void, options?: FlipOptions): Promise<void>;
|
|
1226
|
+
/**
|
|
1227
|
+
* The lower-level parts of gl.transition() for data-gl-id flights. capture(next): a
|
|
1228
|
+
* navigation starts; when the next page is known the matching image freezes where it is
|
|
1229
|
+
* ("" or nothing = not known yet). settle(): the swap is done.
|
|
1230
|
+
* @example barba.hooks.before((data) => gl.morph.capture(data.next.html)); barba.hooks.after(() => gl.morph.settle());
|
|
1231
|
+
*/
|
|
1232
|
+
morph: { capture(next?: NextPage): void; settle(): void };
|
|
1233
|
+
/** Where an element is, every frame, without WebGL (works with GL off). Ends when el leaves the page. */
|
|
1234
|
+
track(el: string | Element, options?: TrackOptions): Tracker;
|
|
1235
|
+
/**
|
|
1236
|
+
* Your three.js scene in its own canvas (the drop-in mode). Umber sizes the renderer,
|
|
1237
|
+
* draws only while el is on screen and something asked, and cleans up when el leaves.
|
|
1238
|
+
* @example gl.attach(el, { renderer, scene, camera, devices: "all", animate: (f) => { mesh.rotation.y += f.dt; return true; } })
|
|
1239
|
+
*/
|
|
1240
|
+
attach(el: string | Element, options: AttachOptions): View;
|
|
1241
|
+
/**
|
|
1242
|
+
* Advanced: a scene drawn into Umber's own canvas, next to the DOM planes, with the one
|
|
1243
|
+
* renderer from gl.renderer(THREE). Clipped to el, fades with it, goes when el leaves.
|
|
1244
|
+
* @example const renderer = await gl.renderer(THREE); gl.view(el, { scene, camera });
|
|
1245
|
+
*/
|
|
1246
|
+
view(el: string | Element, options?: SharedViewOptions): View;
|
|
1247
|
+
/** Advanced: the one THREE.WebGLRenderer on Umber's canvas for the whole visit (compiled programs survive page changes). null when GL is off. */
|
|
1248
|
+
renderer(three: any, params?: Record<string, unknown>): Promise<any>;
|
|
1249
|
+
/**
|
|
1250
|
+
* An offscreen render target on Umber's context (its own file, chunks/fx.js, fetched on
|
|
1251
|
+
* the first call). Draw into it with target.draw(glsl), read it in any effect as a
|
|
1252
|
+
* uniform, or hand target.texture to three.js on Umber's canvas. Holds premultiplied
|
|
1253
|
+
* alpha; "half" (RGBA16F) by default where the GPU can render to it. null when GL is off.
|
|
1254
|
+
* @example const t = await gl.target({ width: 512, height: 512 });
|
|
1255
|
+
* t.draw("vec4 color(vec2 uv) { return vec4(uv, 0.5, 1.0); }");
|
|
1256
|
+
* gl.effect("show", { uniforms: { uPattern: t }, fragment: { color: "color = texture(uPattern, uv);" } });
|
|
1257
|
+
*/
|
|
1258
|
+
target(options?: TargetOptions): Promise<Target | null>;
|
|
1259
|
+
/**
|
|
1260
|
+
* A still copy of what one plane draws right now (its effects included, its parents'
|
|
1261
|
+
* cuts not), as a target: device px, "u8". Waits up to 5 s for the plane to be able to
|
|
1262
|
+
* draw. null when there is no plane, GL is off, or it never drew.
|
|
1263
|
+
* @example const still = await gl.snapshot(".hero img"); gl.effect("echo", { uniforms: { uStill: still }, ... });
|
|
1264
|
+
*/
|
|
1265
|
+
snapshot(el: string | Element | Plane): Promise<Target | null>;
|
|
1266
|
+
/**
|
|
1267
|
+
* A simulation on the GPU (its own file, chunks/sim.js, fetched on the first call):
|
|
1268
|
+
* fields (textures) that fragment passes step forward at `hz` steps a second on every
|
|
1269
|
+
* screen. It steps after an input (a brush, the pointer, set(), wake()) and sleeps once
|
|
1270
|
+
* settled, so a still page asks for no frames. Read it in any effect as a uniform.
|
|
1271
|
+
* null when GL is off.
|
|
1272
|
+
* @example const sim = await gl.sim({ size: 128, next: "vec4 next(vec2 uv) { return texture(state, uv) * 0.95; }" });
|
|
1273
|
+
* gl.brush(sim, { radius: 40 }); // paints where the pointer goes
|
|
1274
|
+
* gl.effect("ink", { uniforms: { uInk: sim }, fragment: { color: "color.rgb += texture(uInk, screenUv()).r;" } });
|
|
1275
|
+
*/
|
|
1276
|
+
sim(options: SimOptions): Promise<Sim | null>;
|
|
1277
|
+
/**
|
|
1278
|
+
* The page's one pointer flowmap: the sim behind `uFlow`, which any effect can read
|
|
1279
|
+
* (`vec4 f = texture(uFlow, screenUv()); vec2 push = (f.rg * 2.0 - 1.0) * f.a;`). Made on
|
|
1280
|
+
* the first plane that reads uFlow, or here. Called again with options, it changes them.
|
|
1281
|
+
* null when GL is off, or where half-float targets can't be rendered (uFlow then uses
|
|
1282
|
+
* the input module's gl.touch(), when it is loaded).
|
|
1283
|
+
*/
|
|
1284
|
+
flow(options?: FlowOptions): Promise<Sim | null>;
|
|
1285
|
+
/**
|
|
1286
|
+
* Soft round stamps into one field of a sim: along the pointer's path while it moves,
|
|
1287
|
+
* and wherever brush.paint(x, y) says. null when `sim` is null.
|
|
1288
|
+
* @example const dye = gl.brush(sim, { field: "dye", radius: 30, color: [1, 0.4, 0.2, 1] });
|
|
1289
|
+
*/
|
|
1290
|
+
brush(sim: Sim | null, options?: BrushOptions): Brush | null;
|
|
1291
|
+
/**
|
|
1292
|
+
* Get the NEXT page ready before it is on the page (its own file, chunks/warm.js): the
|
|
1293
|
+
* images its [data-gl] elements show fetched, decoded and on the GPU (keyed the way the
|
|
1294
|
+
* element will ask: data-gl-src, or the srcset candidate the browser will pick), their
|
|
1295
|
+
* programs compiled, and each drawn once offscreen. When the elements arrive they claim
|
|
1296
|
+
* all of it: the first frame does no work. Never blocks the page (uploads go in idle
|
|
1297
|
+
* moments) and never rejects. The promise is also the progress: p.value 0 -> 1, a Signal
|
|
1298
|
+
* (fn(v) hears each step). With GL off it resolves at once with value 1.
|
|
1299
|
+
*
|
|
1300
|
+
* what: image URLs, a page URL (fetched and read), an element or container (detached is
|
|
1301
|
+
* fine), a parsed Document, Barba's data.next ({ container } / { html } / { url }), or a
|
|
1302
|
+
* list of these. { hover: true | "selector" }: from now on, a link's page is preloaded
|
|
1303
|
+
* when the pointer slows down over it (off on Save-Data; { hover: false } stops it).
|
|
1304
|
+
* @example barba.hooks.leave((data) => { gl.preload(data.next.url.href); }); // braces: Barba waits for a returned promise
|
|
1305
|
+
* @example gl.preload({ hover: "a.project-link" });
|
|
1306
|
+
*/
|
|
1307
|
+
preload(what: PreloadSource | PreloadSource[] | { hover: boolean | string }, fn?: (progress: number) => void): Loading;
|
|
1308
|
+
/**
|
|
1309
|
+
* Get THIS page ready (chunks/warm.js): every plane in root (default: the page) loads its
|
|
1310
|
+
* image or text even when far from the screen, compiles, and is drawn once offscreen.
|
|
1311
|
+
* 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
|
+
* preloader. With GL off it resolves at once with value 1.
|
|
1313
|
+
* @example const p = gl.warm(null, (v) => (bar.style.scale = `${v} 1`)); await p; loader.remove();
|
|
1314
|
+
*/
|
|
1315
|
+
warm(root?: string | ParentNode | null, fn?: (progress: number) => void): Loading;
|
|
1316
|
+
/**
|
|
1317
|
+
* The data-gl-placeholder string for an image (about 50 characters: a preview 6 cells on
|
|
1318
|
+
* its long side, 4 bits per channel). Run it once (the console will do) and paste the string into the
|
|
1319
|
+
* element's attribute. null when GL is off or the file can't be read.
|
|
1320
|
+
* @example await gl.placeholder("/img/dunes.jpg") // "UF..."
|
|
1321
|
+
*/
|
|
1322
|
+
placeholder(src: string | Element): Promise<string | null>;
|
|
1323
|
+
readonly info: Record<string, unknown>;
|
|
1324
|
+
readonly canvas: HTMLCanvasElement | null;
|
|
1325
|
+
readonly context: WebGL2RenderingContext | null;
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1328
|
+
/** What gl.preload() takes: an image or page URL, an element or container, a parsed Document, or a router's next page. */
|
|
1329
|
+
export type PreloadSource = string | URL | ParentNode | { container?: ParentNode; html?: string; url?: string | { href?: string } } | null | undefined;
|
|
1330
|
+
|
|
1331
|
+
/** gl.preload() / gl.warm(): resolves when ready; value is the 0..1 progress (a Signal: usable as a uniform). */
|
|
1332
|
+
export type Loading = Promise<void> & Signal<number>;
|
|
1333
|
+
|
|
1334
|
+
/** gl.leave(glsl, options). */
|
|
1335
|
+
export interface LeaveOptions {
|
|
1336
|
+
/** Seconds uProgress takes from 0 to 1. @default 1 */
|
|
1337
|
+
duration?: number;
|
|
1338
|
+
/** @default "umber" */
|
|
1339
|
+
ease?: Ease;
|
|
1340
|
+
/** Your own uniforms (a { value } is read every frame). uPrev, uNext and uProgress are Umber's. */
|
|
1341
|
+
uniforms?: Record<string, unknown>;
|
|
1342
|
+
/** Arm on a pointerdown on a same-origin link and on back / forward, also with no gl.transition(). @default true */
|
|
1343
|
+
links?: boolean;
|
|
1344
|
+
}
|
|
1345
|
+
|
|
1346
|
+
/** gl.flip(els, change, options) and plane.land(options). */
|
|
1347
|
+
export interface FlipOptions {
|
|
1348
|
+
/** Seconds. @default 0.8 */
|
|
1349
|
+
duration?: number;
|
|
1350
|
+
/** @default "umber" */
|
|
1351
|
+
ease?: Ease;
|
|
1352
|
+
/** Seconds between one element's start and the next (page order). @default 0 */
|
|
1353
|
+
stagger?: number;
|
|
1354
|
+
}
|
|
1355
|
+
|
|
1356
|
+
/** A lifted plane's rect (plane.lift()): viewport CSS px. Setting any of them draws it there. */
|
|
1357
|
+
export interface FreeRect {
|
|
1358
|
+
x: number;
|
|
1359
|
+
y: number;
|
|
1360
|
+
width: number;
|
|
1361
|
+
height: number;
|
|
1362
|
+
}
|
|
1363
|
+
|
|
1364
|
+
/** gl.target(options). Sizes in device px. */
|
|
1365
|
+
export interface TargetOptions {
|
|
1366
|
+
/** Default: the canvas width (device px). The target never follows the canvas: call resize(). */
|
|
1367
|
+
width?: number;
|
|
1368
|
+
height?: number;
|
|
1369
|
+
/**
|
|
1370
|
+
* "half" (RGBA16F, the default), "float" (RGBA32F) or "u8" (RGBA8). A type the GPU can't
|
|
1371
|
+
* render to steps down (float -> half -> u8) and says so once; the default steps down quietly.
|
|
1372
|
+
*/
|
|
1373
|
+
type?: "u8" | "half" | "float";
|
|
1374
|
+
/** MSAA samples (0 = off, the default; capped at the GPU's maximum). Resolved after every draw. */
|
|
1375
|
+
msaa?: number;
|
|
1376
|
+
/** 1-4 colour attachments (MRT): target.textures; write them from your own main(). */
|
|
1377
|
+
attachments?: number;
|
|
1378
|
+
}
|
|
1379
|
+
|
|
1380
|
+
/**
|
|
1381
|
+
* An offscreen render target. The object stays the same for its whole life; its
|
|
1382
|
+
* WebGLTextures do not: a resize (or a restored WebGL context) gives NEW ones and bumps
|
|
1383
|
+
* `version`, and handles read before are invalid. As an effect uniform it is always
|
|
1384
|
+
* current. Holds PREMULTIPLIED alpha; its first row is its top (sample it with a plane's
|
|
1385
|
+
* uv the right way up).
|
|
1386
|
+
*/
|
|
1387
|
+
export interface Target {
|
|
1388
|
+
/** The first attachment's texture (null once released or while the context is lost). */
|
|
1389
|
+
readonly texture: WebGLTexture | null;
|
|
1390
|
+
/** Every attachment's texture (MRT). */
|
|
1391
|
+
readonly textures: ReadonlyArray<WebGLTexture | null>;
|
|
1392
|
+
/** Its resolved framebuffer (for readPixels, or another library's reads). */
|
|
1393
|
+
readonly framebuffer: WebGLFramebuffer | null;
|
|
1394
|
+
readonly width: number;
|
|
1395
|
+
readonly height: number;
|
|
1396
|
+
/** The type it got after the format ladder. */
|
|
1397
|
+
readonly type: "u8" | "half" | "float";
|
|
1398
|
+
/** MSAA samples it got (0 = off). */
|
|
1399
|
+
readonly msaa: number;
|
|
1400
|
+
/** +1 each time its WebGLTextures change (resize, restored context). */
|
|
1401
|
+
readonly version: number;
|
|
1402
|
+
/**
|
|
1403
|
+
* One fullscreen pass into it, replacing what it held. `glsl` defines
|
|
1404
|
+
* `vec4 color(vec2 uv)` (straight alpha: Umber premultiplies), or its own `void main()`
|
|
1405
|
+
* writing `outColor` (premultiplied; more attachments: layout(location = 1) out vec4 ...).
|
|
1406
|
+
* Built in: vUv, uSize (device px), uTime. Uniforms are declared for you; a target or a
|
|
1407
|
+
* texture holder is a sampler. Drawn again after a resize and a restored context.
|
|
1408
|
+
*/
|
|
1409
|
+
draw(glsl: string, uniforms?: Record<string, unknown>): Target;
|
|
1410
|
+
/** Transparent again. */
|
|
1411
|
+
clear(): Target;
|
|
1412
|
+
/** A new size (device px): NEW textures, then the last draw() again. */
|
|
1413
|
+
resize(width: number, height: number): Target;
|
|
1414
|
+
/** Back to the pool (its GPU memory is freed after 5 s unused). texture is null from now on. */
|
|
1415
|
+
release(): void;
|
|
1416
|
+
}
|
|
1417
|
+
|
|
1418
|
+
/** A size in texels: one number, or one per GPU level 0-5 (gl.info.gpu.level). */
|
|
1419
|
+
export type SimSize = number | number[];
|
|
1420
|
+
|
|
1421
|
+
/** gl.sim(options). Give `next` (one field, "state") or `fields` + `passes`. */
|
|
1422
|
+
export interface SimOptions {
|
|
1423
|
+
/** Texels across (or one per GPU level 0-5). @default 128 */
|
|
1424
|
+
size?: SimSize;
|
|
1425
|
+
/** "screen": the height follows the viewport's shape (and a new shape starts it again). "square": size x size. @default "screen" */
|
|
1426
|
+
shape?: "screen" | "square";
|
|
1427
|
+
/** Every field's type: "half" (default), "float" or "u8". Where the GPU can't render it, 8-bit, said once. */
|
|
1428
|
+
type?: "u8" | "half" | "float";
|
|
1429
|
+
/** Steps per second, whatever the screen's refresh rate. @default 60 */
|
|
1430
|
+
hz?: number;
|
|
1431
|
+
/**
|
|
1432
|
+
* One field ("state"): GLSL defining `vec4 next(vec2 uv)`, the field's next value at uv.
|
|
1433
|
+
* Read the old value with texture(state, uv). Built in: uDt (seconds per step), uStep,
|
|
1434
|
+
* uPointer (0..1, y down; -1 before the first move), uSize (texels), uTime, vUv.
|
|
1435
|
+
*/
|
|
1436
|
+
next?: string;
|
|
1437
|
+
/** GLSL defining `vec4 init(vec2 uv)`: the first value (default 0). */
|
|
1438
|
+
init?: string;
|
|
1439
|
+
/** Named fields: each is a sampler of its name in every pass. */
|
|
1440
|
+
fields?: Record<string, { size?: SimSize; type?: "u8" | "half" | "float"; init?: string }>;
|
|
1441
|
+
/** In order, every step: `next` writes field `into` (its old value still readable); `iterations` per step (or one per GPU level). */
|
|
1442
|
+
passes?: Array<{ into: string; next: string; iterations?: number | number[] }>;
|
|
1443
|
+
/** The field sim.texture is. @default the first */
|
|
1444
|
+
output?: string;
|
|
1445
|
+
/** Your uniforms for every pass (numbers, arrays, targets, textures). Change them with sim.set(). */
|
|
1446
|
+
uniforms?: Record<string, unknown>;
|
|
1447
|
+
/** When it sleeps: seconds after the last input (default 2), a function saying it is settled, or false (never: it asks for every frame). It starts asleep unless it has an init, a pass reads uTime or uStep, or settle is false. */
|
|
1448
|
+
settle?: number | false | ((sim: Sim) => boolean);
|
|
1449
|
+
}
|
|
1450
|
+
|
|
1451
|
+
/**
|
|
1452
|
+
* A GPU simulation. Its fields are two targets each, swapped after every pass (never
|
|
1453
|
+
* copied). The object stays; its textures change every step: as an effect uniform it is
|
|
1454
|
+
* always current, elsewhere read sim.texture again each frame.
|
|
1455
|
+
*/
|
|
1456
|
+
export interface Sim {
|
|
1457
|
+
/** The output field's current texture (null once released or while the context is lost). */
|
|
1458
|
+
readonly texture: WebGLTexture | null;
|
|
1459
|
+
readonly width: number;
|
|
1460
|
+
readonly height: number;
|
|
1461
|
+
/** The type it got after the format ladder. */
|
|
1462
|
+
readonly type: "u8" | "half" | "float";
|
|
1463
|
+
/** Steps since it started (or reset()). */
|
|
1464
|
+
readonly steps: number;
|
|
1465
|
+
/** Seconds of steps since the last input. */
|
|
1466
|
+
readonly idle: number;
|
|
1467
|
+
/** Stepping now (false: asleep, until an input). */
|
|
1468
|
+
readonly awake: boolean;
|
|
1469
|
+
/** One field as a sampler uniform: uniforms: { uDye: sim.field("dye") }. */
|
|
1470
|
+
field(name: string): { readonly texture: WebGLTexture | null } | null;
|
|
1471
|
+
/** A uniform of its passes; it wakes. */
|
|
1472
|
+
set(name: string, value: unknown): Sim;
|
|
1473
|
+
/** Step again from the next frame until it settles. */
|
|
1474
|
+
wake(): Sim;
|
|
1475
|
+
/** Every field as it started. */
|
|
1476
|
+
reset(): Sim;
|
|
1477
|
+
brush(options?: BrushOptions): Brush | null;
|
|
1478
|
+
/** Its targets back to the pool. texture is null from now on. */
|
|
1479
|
+
release(): void;
|
|
1480
|
+
}
|
|
1481
|
+
|
|
1482
|
+
/** gl.brush(sim, options). */
|
|
1483
|
+
export interface BrushOptions {
|
|
1484
|
+
/** The field it paints. @default the first */
|
|
1485
|
+
field?: string;
|
|
1486
|
+
/** Gaussian radius, CSS px. @default 24 */
|
|
1487
|
+
radius?: number;
|
|
1488
|
+
/** What a stamp adds ("add") or mixes towards by its alpha ("mix"). @default [1, 1, 1, 1] */
|
|
1489
|
+
color?: number[];
|
|
1490
|
+
/** The stroke's movement (CSS px) times this is added to .xy: a push for a fluid or a flowmap. @default 0 */
|
|
1491
|
+
motion?: number;
|
|
1492
|
+
/** @default "add" */
|
|
1493
|
+
mode?: "add" | "mix";
|
|
1494
|
+
/** Paint along the pointer's path while it moves. @default true */
|
|
1495
|
+
pointer?: boolean;
|
|
1496
|
+
}
|
|
1497
|
+
|
|
1498
|
+
export interface Brush {
|
|
1499
|
+
/** One stamp at viewport CSS px x, y (dx, dy: the stroke's movement there, CSS px) at the next step; the sim wakes. */
|
|
1500
|
+
paint(x: number, y: number, dx?: number, dy?: number): Brush;
|
|
1501
|
+
release(): void;
|
|
1502
|
+
}
|
|
1503
|
+
|
|
1504
|
+
/** gl.flow(options). */
|
|
1505
|
+
export interface FlowOptions {
|
|
1506
|
+
/** Texels across (or one per GPU level 0-5). @default [32, 48, 64, 64, 96, 128] */
|
|
1507
|
+
size?: SimSize;
|
|
1508
|
+
/** The pointer's reach, CSS px. @default 8 % of the viewport width */
|
|
1509
|
+
radius?: number;
|
|
1510
|
+
/** How much of a push stays per step (60 a second). @default 0.92 */
|
|
1511
|
+
fade?: number;
|
|
1512
|
+
/** How hard a CSS px of movement pushes. @default 0.04 */
|
|
1513
|
+
motion?: number;
|
|
1514
|
+
}
|
|
1515
|
+
|
|
1516
|
+
/** window.Umber (the <script> build). */
|
|
1517
|
+
export interface UmberGlobal {
|
|
1518
|
+
readonly version: string;
|
|
1519
|
+
createGL(options?: GLOptions): GL;
|
|
1520
|
+
/** DOM <-> three.js maths and frame-rate-free smoothing. No engine needed. */
|
|
1521
|
+
readonly math: UmberMath;
|
|
1522
|
+
/** An optional module for the engine on the page and every later one (module scripts call it themselves). */
|
|
1523
|
+
use(module: UmberModule, options?: Record<string, unknown>): void;
|
|
1524
|
+
}
|
|
1525
|
+
|
|
1526
|
+
declare global {
|
|
1527
|
+
interface Window {
|
|
1528
|
+
Umber: UmberGlobal;
|
|
1529
|
+
UmberConfig?: { base?: string };
|
|
1530
|
+
}
|
|
1531
|
+
const Umber: UmberGlobal;
|
|
1532
|
+
}
|