@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/docs/AI.md
CHANGED
|
@@ -8,13 +8,33 @@ Umber is a **DOM-to-WebGL engine**. You tag DOM elements (images, video, text, s
|
|
|
8
8
|
|
|
9
9
|
Umber is a product of Occluze, a product of R—K.
|
|
10
10
|
|
|
11
|
-
**Umber needs nothing else.** No
|
|
11
|
+
**Umber needs nothing else.** No animation, scroll or router library: it has its own `requestAnimationFrame` loop (which sleeps when nothing moves) and its own small timing (duration, delay, cubic-bezier eases). It never reads `window.Lenis` or `window.barba`, and reads `window.gsap` only when you ask for one clock for the page (`patch`, in Utilities).
|
|
12
12
|
|
|
13
|
-
**
|
|
13
|
+
**The core works next to them and controls none of them.** `umber.js` on its own never intercepts links, never touches history or scroll restoration, and you set up the site's own libraries the way their docs show.
|
|
14
14
|
|
|
15
|
-
**
|
|
15
|
+
**Two add-ons can take their place, if the site wants Umber to drive scroll and page changes too.** Name them on the script tag: `<script src=".../umber.js" data-umber-modules="scroll router">`. The facts, to recommend from (never load both an add-on and the library it replaces):
|
|
16
16
|
|
|
17
|
-
**
|
|
17
|
+
- **scroll** eases the page's real scroll on Umber's own frame loop: GL elements stay on their HTML to the pixel every frame, GSAP ScrollTrigger pins and scrubs update in the same frame. It honours `data-lenis-prevent` ("Smooth scroll" below).
|
|
18
|
+
- **router** changes pages without a reload and needs no other library: the new page's GL elements come up as it comes in, reveals wait for the transition, and a `data-umber-id` image flies to the next page with any transition.
|
|
19
|
+
- **Lenis, Barba, Swup...** work too: Umber reads Lenis's scroll (`createUmber({ scroll: lenis })`) and "Any router" has a recipe for each. Keep them when the site is built on them and the user wants to.
|
|
20
|
+
|
|
21
|
+
**The licence.** Umber runs free, with no key, on `localhost`, `*.localhost`, `*.test` and private IP addresses (`10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`, IPv6 `fc00::/7` and `fe80::/10`: a phone on the same Wi-Fi; a name such as `*.local` still needs a licence), and on preview addresses (`webflow.io`, `vercel.app`, `pages.dev`, ngrok, `trycloudflare.com`, `loca.lt`), which show a small Occluze badge and use no slot. A live site needs the account's public key in the install code (`data-umber-key="YOUR_KEY"`, or `createUmber({ key: "YOUR_KEY" })` on npm), from occluze.com/dashboard?view=umber. While your account is on Approve automatically (the first 30 minutes after buying, or 30 minutes whenever you switch it on in the dashboard) it joins your domains and runs on the next refresh; on Block all, nothing new gets in. A domain, its `www` and its subdomains are one of the account's 25 slots. Until then the page shows without GL, `umber.reason` is `"unlicensed"` and the console says why. Every add-on follows the same one check.
|
|
22
|
+
|
|
23
|
+
**One canvas, linked to the whole DOM.** Everything Umber draws, every tagged element, every effect and every three.js scene (`umber.renderer` + `umber.view`), shares one canvas that follows the page, so any effect can go on any element anywhere. Don't give an effect or a scene a canvas of its own; `umber.attach()` (a second canvas) is only for porting an existing scene.
|
|
24
|
+
|
|
25
|
+
**It is an engine, not an effects library.** Umber ships no effects. An effect is a few lines of GLSL you write and register with `umber.effect()`; the examples gallery (`examples/`) shows how, with reveals, a dissolve, a hover lens, a velocity bend, parallax and grain written as plain example code.
|
|
26
|
+
|
|
27
|
+
**The DOM stays the truth.** The real `<img alt>`, `<video>` and text stay in the page for search engines, screen readers and layout. Each turns invisible only after the GPU has painted the same pixels, and shows again whenever GL can't run (no WebGL2, a device the site turned off, Save-Data or a 2G connection, a lost context, a load that is too slow).
|
|
28
|
+
|
|
29
|
+
**Every element says what it is, how it behaves, and what it's set to.** `data-umber` holds one kind (what it is: `image`, `video`, `text`, `shader`, `layer`, `model`, `group`...) and any behaviours after it (how it behaves: `above`, `pin`, `inview`...); every setting is an attribute of its own, `data-umber-<setting>`:
|
|
30
|
+
|
|
31
|
+
```html
|
|
32
|
+
<figure data-umber="image pin" data-umber-effect="dissolve" data-umber-dissolve-scale="6">
|
|
33
|
+
<img src="/img/dunes.jpg" alt="Dunes at dusk">
|
|
34
|
+
</figure>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
One kind per element; a behaviour that needs a value is written only as its setting (`data-umber-pin="80px"`). The full word list is under Attributes, and on `localhost` Umber warns about a word it doesn't know.
|
|
18
38
|
|
|
19
39
|
## The 30-second setup
|
|
20
40
|
|
|
@@ -22,90 +42,99 @@ Webflow (**Site settings > Custom code**), or the same tags in any HTML page:
|
|
|
22
42
|
|
|
23
43
|
```html
|
|
24
44
|
<!-- Head code: the GL handshake CSS -->
|
|
25
|
-
<link rel="stylesheet" href="https://umber.occluze.com/umber@0.
|
|
26
|
-
|
|
27
|
-
<!-- Footer code.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
45
|
+
<link rel="stylesheet" href="https://umber.occluze.com/umber@0.3.0/umber.css">
|
|
46
|
+
|
|
47
|
+
<!-- Footer code: umber.js, with the add-ons it should load named in data-umber-modules (they load at once, before any click,
|
|
48
|
+
from the same version):
|
|
49
|
+
scroll smooth scrolling on Umber's own frame loop
|
|
50
|
+
scrollfx scroll effects from attributes: in-view classes, progress, parallax, pins
|
|
51
|
+
router page transitions without a reload
|
|
52
|
+
handoff image flights across full page loads, for a site without a router
|
|
53
|
+
scrub scroll-scrubbed video
|
|
54
|
+
input umber.drag, umber.trail, umber.press...
|
|
55
|
+
three glTF models (data-umber="model") and three.js on Umber's canvas
|
|
56
|
+
debug a HUD while you build; never on the live site
|
|
57
|
+
A site that keeps its own smooth scrolling or router leaves scroll or router out (their tags can sit before or after this).
|
|
58
|
+
umber@0.3.0 is an exact version, so nothing changes under the site: to update, change the number in every umber@ URL.
|
|
59
|
+
data-umber-key is your account's public key, from occluze.com/dashboard?view=umber.
|
|
60
|
+
data-umber-debug on this tag (or ?umber-debug in the address) turns on every warning and the debug overlay, for staging. -->
|
|
61
|
+
<script src="https://umber.occluze.com/umber@0.3.0/umber.js" data-umber-key="YOUR_KEY" data-umber-modules="scroll router"></script>
|
|
37
62
|
<script>
|
|
38
|
-
const
|
|
39
|
-
//
|
|
63
|
+
const umber = Umber.createUmber(); // every device; { devices: "desktop" } or { media: "(min-width: 900px)" } turns some off
|
|
64
|
+
// umber.effect("dissolve", { ... }); // the effects this site uses: yours to write
|
|
40
65
|
</script>
|
|
41
66
|
```
|
|
42
67
|
|
|
43
68
|
Umber needs no library. The examples load Lenis 1.3.23, @barba/core 2.10.3 and three.js 0.178.0 themselves; Umber only reads a Lenis instance and only sizes and calls the three.js renderer you hand it, so other Lenis 1.x, Barba 2.x and three.js versions work the same way. Pin exact versions on live sites.
|
|
44
69
|
|
|
45
|
-
Bundled sites (Vite, Astro, Next) install the
|
|
70
|
+
Bundled sites (Vite, Astro, Next) install the npm package instead:
|
|
46
71
|
|
|
47
72
|
```js
|
|
48
|
-
// npm install @occluze/umber@0.
|
|
49
|
-
import {
|
|
73
|
+
// npm install @occluze/umber@0.3.0 (docs/npm.md)
|
|
74
|
+
import { createUmber } from "@occluze/umber";
|
|
50
75
|
import "@occluze/umber/umber.css";
|
|
51
|
-
import {
|
|
76
|
+
import { Scroll } from "@occluze/umber/scroll"; // smooth scrolling, on Umber's clock
|
|
77
|
+
import { Router } from "@occluze/umber/router"; // page transitions without a reload
|
|
52
78
|
|
|
53
|
-
const
|
|
79
|
+
const umber = createUmber({ key: "YOUR_KEY", modules: [Scroll, Router] }); // client code only; on the server it does nothing
|
|
54
80
|
```
|
|
55
81
|
|
|
56
|
-
- `umber.js` is a plain script that sets `window.Umber = { version,
|
|
82
|
+
- `umber.js` is a plain script that sets `window.Umber = { version, createUmber, math, use }`. It downloads no GL code until the device passes the checks **and** the page has a `[data-umber]` element (or the code calls `umber.renderer()`, `umber.view()`, `umber.target()` or `umber.preload()`); then it loads `chunks/gl.js` from its own folder (and, only when the page needs them, `chunks/shapes.js` for GL elements cut, turned or tilted by CSS or by an animation, `chunks/text.js` for `data-umber="text"`, `chunks/layers.js` for three.js on Umber's canvas, and the other chunks listed under Loading the engine). `umber.attach()` loads only `chunks/views.js`. `umber.inspect()` and some warnings load `chunks/inspect.js`.
|
|
57
83
|
- `umber.css` goes in `<head>` on every page: it holds the canvas host and the rules that hide a DOM image only once GL has drawn it. A page without it (a 404 template a router swaps in) keeps GL off, with a warning, until it is back; the canvas is hidden meanwhile, so it takes no room in that page.
|
|
58
|
-
- Load `umber.js` before the code that calls `Umber.
|
|
59
|
-
- Call `
|
|
84
|
+
- Load `umber.js` before the code that calls `Umber.createUmber()`. Its place relative to Lenis, Barba or GSAP tags does not matter.
|
|
85
|
+
- Call `createUmber()` **once per visit**, not per page. A second call warns and returns the first engine.
|
|
60
86
|
|
|
61
|
-
##
|
|
87
|
+
## createUmber(options)
|
|
62
88
|
|
|
63
89
|
```js
|
|
64
|
-
const
|
|
90
|
+
const umber = Umber.createUmber(); // zero config: window scroll, own loop, every device
|
|
65
91
|
|
|
66
|
-
const
|
|
92
|
+
const umber = Umber.createUmber({ // every option is optional
|
|
67
93
|
scroll: lenis, // read-only scroll source: a Lenis instance, an element, { y, velocity }. Default: window (or <body> when it is the scroller)
|
|
68
|
-
loop: "auto", // "auto": Umber's own rAF loop, asleep when idle. false: call
|
|
69
|
-
devices: "all", // "all" | "desktop" (hover + fine pointer + >= 768px; or data-
|
|
70
|
-
media: "(min-width: 900px)", // optional: effects only where this CSS media query matches (or data-
|
|
94
|
+
loop: "auto", // "auto": Umber's own rAF loop, asleep when idle. false: call umber.render(time) yourself
|
|
95
|
+
devices: "all", // "all" | "desktop" (hover + fine pointer + >= 768px; or data-umber-devices="desktop" on <body>) | (env) => boolean | false (anything else: "desktop", with a warning)
|
|
96
|
+
media: "(min-width: 900px)", // optional: effects only where this CSS media query matches (or data-umber-media on <body>)
|
|
71
97
|
dpr: { high: 2, mid: 1.5, low: 1 }, // or a max (2), or [min, max]. Below the screen's own (a 3x phone at "mid" 1.5) GL text is softer than DOM text: speed over sharpness
|
|
72
98
|
pixelBudget: 12e6, // max canvas pixels (w * h * dpr^2)
|
|
73
99
|
adaptive: true, // lower the resolution only while the GPU can't keep up
|
|
100
|
+
software: false, // true: run GL even where WebGL draws on the processor (no usable GPU; default: the DOM shows)
|
|
101
|
+
patch: false, // true: every requestAnimationFrame loop on the page runs inside Umber's frame (Utilities: the loop)
|
|
74
102
|
reducedMotion: "static",// "static": draw without motion (uTime stands still); "off": GL off for reduced motion
|
|
75
103
|
respectSaveData: true, // GL off when the browser asks to save data (Save-Data, prefers-reduced-data), or on a 2G connection
|
|
76
104
|
layer: "over", // the canvas over the page ("over") or behind it ("under")
|
|
77
105
|
zIndex: 1, // z-index of the host Umber makes (default 1 over, -1 under)
|
|
78
|
-
host: "[data-
|
|
106
|
+
host: "[data-umber-host]", // where the canvas goes (default: a [data-umber-host] already in the page, else a fixed host Umber makes)
|
|
79
107
|
designer: false, // run inside the Webflow Designer / Editor too
|
|
108
|
+
key: undefined, // your account's public key (or data-umber-key on the umber.js tag)
|
|
80
109
|
base: undefined, // folder the chunks (chunks/gl.js...) load from (default: next to umber.js)
|
|
81
110
|
modules: [], // optional modules: [Scrub], [[Scrub, { cacheMB: 64 }]]
|
|
82
|
-
busy: undefined, // a selector on <html> a router sets during a page change ("html.is-changing"):
|
|
83
|
-
debug: false, // true: debug notes in the console; { hud, outlines, markers, cost } for modules/debug.js
|
|
84
|
-
warnings:
|
|
111
|
+
busy: undefined, // a selector on <html> a router sets during a page change ("html.is-changing"): umber.transition() without hooks
|
|
112
|
+
debug: false, // true: debug notes in the console; { hud, outlines, markers, cost, profiler } for modules/debug.js
|
|
113
|
+
warnings: undefined, // default: on for localhost and with debug on, off on live sites; true or false sets it
|
|
85
114
|
});
|
|
86
115
|
```
|
|
87
116
|
|
|
88
117
|
## Is GL on? (three ways to know)
|
|
89
118
|
|
|
90
|
-
- **Properties:** `await
|
|
91
|
-
- **Events:** `
|
|
92
|
-
- **CSS hooks:** `html.has-
|
|
119
|
+
- **Properties:** `await umber.ready` is `true` once GL draws this page's `[data-umber]` elements, `false` when it chose not to or the page has none. `umber.enabled` is `false` when GL is off for this visit, and `umber.reason` says why: `"device"`, `"no-webgl2"`, `"save-data"`, `"software"` (no usable GPU: WebGL would draw on the processor, as with SwiftShader, llvmpipe or Microsoft Basic Render, and every frame would cost the page its smoothness; `createUmber({ software: true })` or `data-umber-software` on `<body>` runs it anyway), `"reduced-motion"`, `"forced-colors"`, `"editor"`, `"disabled"` (`devices: false`, `data-umber-disable` or `?umber=off`), `"context"`, `"load-failed"`, `"load-timeout"`, `"unlicensed"` (no key, or this site isn't on the account's domains: turn on Approve automatically at occluze.com/dashboard?view=umber), `"licence-unreachable"` (the licence check got no clear answer: umber.occluze.com unreachable or blocked, or `chunks/licence.js` didn't load; GL stays off, and the console prints the report line of Umber's own failures), `"context-lost"` (the WebGL context was lost too often), `"error"` (an error inside a GL frame), `"server"` or `"destroyed"`.
|
|
120
|
+
- **Events:** `umber.on("ready" | "lost" | "restored" | "destroy", fn)`. Every `on()` returns its `off()`. The same events also go to `document` as DOM events, with the payload as `event.detail`, for code that has no `umber` at hand: `document.addEventListener("umber:ready", (e) => ...)` (`umber:ready`, `umber:lost`, `umber:restored`, `umber:destroy`, `umber:off`, `umber:fallback`). `umber.on("off", ({ reason }) => ...)`: GL is off for this visit, from the start or later; `umber.on("fallback", ({ el, reason }) => ...)`: an element shows its DOM instead of GL (see "Reporting to your own analytics" in the debugging section). `umber.on("added", (roots) => ...)` hands over the roots of what entered the page, once per frame (a router's new page; `<html>` on the first scan): what `umber.drag(selector)` binds again on. Listening keeps the DOM watch on, also with GL off.
|
|
121
|
+
- **CSS hooks:** `html.has-umber` while GL may run; per element `data-umber-status="loading | ready | error"`. Elements Umber drew are `ready`; `error` means it gave up and the DOM shows.
|
|
93
122
|
|
|
94
123
|
```js
|
|
95
|
-
const
|
|
96
|
-
if (await
|
|
97
|
-
else console.log("plain DOM:",
|
|
124
|
+
const umber = Umber.createUmber();
|
|
125
|
+
if (await umber.ready) console.log("GL is drawing");
|
|
126
|
+
else console.log("plain DOM:", umber.reason);
|
|
98
127
|
```
|
|
99
128
|
|
|
100
129
|
## The rules (read these first)
|
|
101
130
|
|
|
102
|
-
1. **One engine per visit.** `
|
|
131
|
+
1. **One engine per visit.** `createUmber()` once, in code that runs once (not in a Barba hook). `umber.destroy()` only to start fresh.
|
|
103
132
|
2. **Bring your own libraries.** Umber never loads Lenis, Barba, GSAP or three.js. Load them yourself, as their docs say. Pass a Lenis instance with `scroll: lenis` so planes follow its smooth position.
|
|
104
|
-
3. **Mark elements, don't call Umber per page.** Planes appear when a `[data-
|
|
133
|
+
3. **Mark elements, don't call Umber per page.** An element says what it is, how it behaves, and what it's set to: `data-umber="image pin"` (one kind, then behaviours) and `data-umber-effect="dissolve"` (a setting); the words are in Attributes. Planes appear when a `[data-umber]` element enters the DOM and go when it leaves. Barba, a CMS "load more", a framework re-render: all the same.
|
|
105
134
|
4. **The page must look right without GL.** GL runs on every device by default (a site can keep it to desktops), and is off for Save-Data (or a 2G connection), no WebGL2 and High Contrast. Never hide content for an effect; GL draws over the real `<img>` and text.
|
|
106
|
-
5. **Effects are yours.** `data-
|
|
135
|
+
5. **Effects are yours.** `data-umber-effect="name"` needs `umber.effect("name", {...})`, written by you (see Writing effects). An unknown name warns and draws the plane without it.
|
|
107
136
|
6. **Everything Umber exposes is a plain `{ value }`.** Tween uniforms with Umber's own `plane.tween()`, with GSAP, Motion or a line of your own code.
|
|
108
|
-
7. **Read the warnings.** Every Umber message starts with `[umber]`, shows once, and says how to fix it. `
|
|
137
|
+
7. **Read the warnings.** Every Umber message starts with `[umber]`, shows once, and says how to fix it. `umber.inspect(el)` tells you why one element is or is not drawn.
|
|
109
138
|
|
|
110
139
|
---
|
|
111
140
|
|
|
@@ -116,9 +145,9 @@ Set up Lenis and Barba exactly as their own docs show. Start Umber once. That is
|
|
|
116
145
|
```js
|
|
117
146
|
// site.js: plain Lenis, plain Barba, Umber next to them.
|
|
118
147
|
const lenis = new Lenis({ autoRaf: true }); // your Lenis, your loop
|
|
119
|
-
const
|
|
148
|
+
const umber = Umber.createUmber({ scroll: lenis }); // read-only: position + velocity
|
|
120
149
|
|
|
121
|
-
|
|
150
|
+
umber.effect("dissolve", { /* your own effect (examples/effects/dissolve.js is one) */ });
|
|
122
151
|
|
|
123
152
|
barba.init({
|
|
124
153
|
transitions: [{
|
|
@@ -130,51 +159,51 @@ barba.hooks.after(() => lenis.scrollTo(0, { immediate: true })); // Barba and
|
|
|
130
159
|
|
|
131
160
|
// Optional, only if you want them (examples/transitions/transition.js uses them):
|
|
132
161
|
// let release = () => {};
|
|
133
|
-
// barba.hooks.before(() => { release =
|
|
134
|
-
// barba.hooks.after(() => { release();
|
|
162
|
+
// barba.hooks.before(() => { release = umber.hold(); umber.live(true); });
|
|
163
|
+
// barba.hooks.after(() => { release(); umber.live(1); });
|
|
135
164
|
```
|
|
136
165
|
|
|
137
166
|
What Umber does by itself, with no Barba hook:
|
|
138
167
|
|
|
139
|
-
- **Page swaps.** One `MutationObserver` sees Barba's new container arrive and the old one leave. New `[data-
|
|
168
|
+
- **Page swaps.** One `MutationObserver` sees Barba's new container arrive and the old one leave. New `[data-umber]` elements get planes; planes whose element left are destroyed and their GPU memory freed. The first page load takes the same path, so there is nothing to call on load either.
|
|
140
169
|
- **Moving containers.** For 1.5 s after planes arrive or leave, Umber measures every visible plane every frame, so a container that slides in by `transform` is followed. CSS transitions and animations on a plane's parents are followed for as long as they run, and a style or class change on a parent (a GSAP tween writes `style`) re-measures the planes inside it.
|
|
141
|
-
- **Lenis.** With `
|
|
142
|
-
- **Lenis made later** (in Barba's `once()`, after a preloader): `
|
|
170
|
+
- **Lenis.** With `createUmber({ scroll: lenis })` Umber reads the scroll position Lenis writes to the page (or to its wrapper) in each frame's measure phase, as an absolute position, plus Lenis's `velocity` and its `scroll` event. It never adds up scroll deltas, so it does not matter whose `requestAnimationFrame` runs first: Lenis's `autoRaf`, a `gsap.ticker` callback or Umber's own loop. Umber never calls `lenis.raf()`, `start()`, `stop()` or `scrollTo()`, unless you ask for one clock for the page (`createUmber({ scroll: lenis, patch: true })`, in Utilities: the loop): then it steps an `autoRaf` Lenis first in its own frame.
|
|
171
|
+
- **Lenis made later** (in Barba's `once()`, after a preloader): `createUmber()` runs once, first, so it can't take the instance yet. Leave `scroll` out: Lenis scrolls the window itself, and Umber reads that and works out the speed. For Lenis's own velocity, pass getters over a variable you fill in later (Umber also wakes on the window's scroll by itself, which Lenis moves):
|
|
143
172
|
|
|
144
173
|
```js
|
|
145
174
|
let lenis = null;
|
|
146
|
-
const
|
|
175
|
+
const umber = Umber.createUmber({ scroll: { y: () => window.scrollY, velocity: () => (lenis ? lenis.velocity : 0) } });
|
|
147
176
|
barba.init({ transitions: [{ once() { lenis = new Lenis({ autoRaf: true }); } }] });
|
|
148
177
|
```
|
|
149
178
|
|
|
150
|
-
- **Any scroller.** `scroll: document.querySelector(".scroller")` follows an element that scrolls instead of the window. `scroll: { y: () => myY, velocity: () => myV }` follows anything else (velocity is optional: Umber works it out). Umber can't hear such a source change unless the window scrolls too (Umber always listens to the window's scroll): call `
|
|
179
|
+
- **Any scroller.** `scroll: document.querySelector(".scroller")` follows an element that scrolls instead of the window. `scroll: { y: () => myY, velocity: () => myV }` follows anything else (velocity is optional: Umber works it out). Umber can't hear such a source change unless the window scrolls too (Umber always listens to the window's scroll): call `umber.wake()` when your scroller moves, or use `createUmber({ loop: false })` and call `umber.render(time)` from its loop.
|
|
151
180
|
|
|
152
181
|
### Optional one-liners (only if you want them)
|
|
153
182
|
|
|
154
183
|
```js
|
|
155
184
|
let release = () => {};
|
|
156
185
|
barba.hooks.before(() => {
|
|
157
|
-
release =
|
|
158
|
-
|
|
186
|
+
release = umber.hold(); // the new page's plays (reveals) wait...
|
|
187
|
+
umber.live(true); // ...and every visible plane is measured every frame
|
|
159
188
|
});
|
|
160
189
|
barba.hooks.after(() => {
|
|
161
190
|
release(0.1); // ...until 0.1 s after the swap
|
|
162
|
-
|
|
191
|
+
umber.live(1); // one more second, then back to "measure on change"
|
|
163
192
|
});
|
|
164
193
|
```
|
|
165
194
|
|
|
166
|
-
- `
|
|
167
|
-
- `
|
|
168
|
-
- **A new page that slides over the old one.** GL draws on one canvas above the page, so an old page's GL image shows through the new container while that container covers it (the DOM would hide it). A fade is fine (GL follows the container's opacity). For a cover transition, hand the old images back to the DOM when the cover starts: `barba.hooks.leave(({ current }) =>
|
|
169
|
-
- **Planes taking part in the transition:** `
|
|
170
|
-
- **The same image on both pages (`data-
|
|
195
|
+
- `umber.hold()` holds every play (an effect's `play` uniform, such as a reveal) back and returns `release(delaySeconds?)`. Holds stack. `umber.hold(promise)` releases when the promise settles.
|
|
196
|
+
- `umber.live(true | false | seconds)` measures every visible plane every frame. Use it while something moves the page that Umber cannot see (a WebGL-driven layout, a `transform` set by your own rAF loop).
|
|
197
|
+
- **A new page that slides over the old one.** GL draws on one canvas above the page, so an old page's GL image shows through the new container while that container covers it (the DOM would hide it). A fade is fine (GL follows the container's opacity). For a cover transition, hand the old images back to the DOM when the cover starts: `barba.hooks.leave(({ current }) => umber.planes(current.container).forEach((p) => p.destroy()))`. The DOM image is then the one being covered, exactly as without GL.
|
|
198
|
+
- **Planes taking part in the transition:** `umber.planes(current.container)` lists the old page's planes. Play them back to 0 in `leave` and Barba waits for them, because `plane.play()` and `plane.tween()` return an awaitable tween. `examples/transitions/transition.js` does this.
|
|
199
|
+
- **The same image on both pages (`data-umber-id`).** Give it the same `data-umber-id` on both pages and it flies from its old place to its new one instead of fading out and in. It works without hooks. Barba adds the new container below the old one, and Umber flies only to an image on the first screen, so take the old page out of the layout once it has left, or stack the containers. The Barba recipe in the next section does both in four lines, with `umber.transition()` (it holds plays and measures live too, so it replaces the two hooks above). Options on the element you go to: `data-umber-morph-duration` (seconds, default 1) and `data-umber-morph-ease`, also as `--umber-morph-duration` / `--umber-morph-ease` in CSS (on `:root` for the whole site). Other routers: the next section.
|
|
171
200
|
|
|
172
201
|
### With GSAP
|
|
173
202
|
|
|
174
203
|
GSAP is not needed, but it works with everything Umber exposes, because every uniform is a plain `{ value }`:
|
|
175
204
|
|
|
176
205
|
```js
|
|
177
|
-
const uShow =
|
|
206
|
+
const uShow = umber.plane(el)?.uniforms.uShow; // null with GL off: guard it
|
|
178
207
|
if (uShow) gsap.to(uShow, { value: 1, duration: 1.2, ease: "expo.out" });
|
|
179
208
|
if (uShow) gsap.to(uShow, { value: 1, scrollTrigger: { trigger: el, scrub: true } });
|
|
180
209
|
```
|
|
@@ -182,10 +211,12 @@ if (uShow) gsap.to(uShow, { value: 1, scrollTrigger: { trigger: el, scrub: true
|
|
|
182
211
|
Driving Umber from `gsap.ticker` instead of its own loop (where you create it):
|
|
183
212
|
|
|
184
213
|
```js
|
|
185
|
-
const
|
|
186
|
-
gsap.ticker.add((time) =>
|
|
214
|
+
const umber = Umber.createUmber({ loop: false });
|
|
215
|
+
gsap.ticker.add((time) => umber.render(time * 1000)); // ms, like requestAnimationFrame
|
|
187
216
|
```
|
|
188
217
|
|
|
218
|
+
Or keep Umber's loop and run GSAP's ticker inside it, one `requestAnimationFrame` for both: `createUmber({ patch: true })` (Utilities: the loop).
|
|
219
|
+
|
|
189
220
|
Umber never calls `gsap.ticker.lagSmoothing()`, `gsap.defaults()` or `CustomEase.create()`. Its own lag smoothing (a long gap between frames counts as 33 ms, so a reveal half-way when the tab was hidden is still half-way) lives in its own loop only.
|
|
190
221
|
|
|
191
222
|
---
|
|
@@ -196,59 +227,59 @@ Umber works next to any router: Barba, Swup, Taxi, Highway, Turbo, Astro's clien
|
|
|
196
227
|
|
|
197
228
|
What Umber does by itself, with no hook:
|
|
198
229
|
|
|
199
|
-
- **The whole `<body>` replaced** (Turbo, Astro, Swup with `body` as its container) or **everything inside it** (htmx `hx-boost`). Umber's canvas leaves with the old body. Umber puts it back right in the `MutationObserver` callback, before that frame paints, and draws the new page in that same frame, so no frame shows the page without GL. A site's own `[data-
|
|
230
|
+
- **The whole `<body>` replaced** (Turbo, Astro, Swup with `body` as its container) or **everything inside it** (htmx `hx-boost`). Umber's canvas leaves with the old body. Umber puts it back right in the `MutationObserver` callback, before that frame paints, and draws the new page in that same frame, so no frame shows the page without GL. A site's own `[data-umber-host]` on every page takes the canvas over; one that is missing on the new page is put back, with a warning that names the fix (`data-turbo-permanent`, `transition:persist`, `hx-preserve`).
|
|
200
231
|
- **Cached copies of a page** (Turbo's cache, htmx's history, a back button): they bring a blank copy of the canvas and Umber's old marks. The copy is removed (one canvas stays) and the marks are taken over by the new planes in the same frame.
|
|
201
|
-
- **`<html>`'s attributes wiped** (Astro copies the new page's): `has-
|
|
202
|
-
- **The same image on both pages (`data-
|
|
203
|
-
- both pages in the DOM at once (Barba with `sync: true`, a Vue `<Transition>` with no `mode`): it flies from where it is. When the new page sits below the old one (not on the first screen yet), it flies only inside a page change (`
|
|
232
|
+
- **`<html>`'s attributes wiped** (Astro copies the new page's): `has-umber` comes back.
|
|
233
|
+
- **The same image on both pages (`data-umber-id`).** It flies from its old place to its new one, whatever order the router swaps in:
|
|
234
|
+
- both pages in the DOM at once (Barba with `sync: true`, a Vue `<Transition>` with no `mode`): it flies from where it is. When the new page sits below the old one (not on the first screen yet), it flies only inside a page change (`umber.transition()` or `createUmber({ busy })`): Umber then asks again once the old page leaves. With no hook it reveals on scroll as usual;
|
|
204
235
|
- one swap (Swup, Turbo, Astro, htmx, Next): from where it was last drawn; an image its page had already faded out flies in from transparent;
|
|
205
236
|
- the old page removed before the new one is in (Taxi, Nuxt `out-in`, a Next loading state, a filter grid re-ordered): an on-screen image whose element left waits 3 s for its id to come back (at most 8 wait; each keeps a texture), then is freed;
|
|
206
237
|
- the element it flies to replaced mid-flight (Turbo shows a cached copy, then the real page; a framework re-mounts it): the flight goes on from where it is.
|
|
207
238
|
- **Thumbnail to hero.** A small and a large copy of one picture (`srcset` candidates of the same image, or the same `src`) fly with the large copy's texture as soon as it is on the GPU: no upscaled thumbnail once the real one is there, and nothing pops when it lands.
|
|
208
239
|
|
|
209
|
-
Options on the element you go to: `data-
|
|
240
|
+
Options on the element you go to: `data-umber-morph-duration` (seconds, default 1) and `data-umber-morph-ease`, also as `--umber-morph-duration` / `--umber-morph-ease` in CSS (on `:root` for the whole site). Only an element on the new page's first screen is flown to; one below it reveals on scroll as usual. While the image is frozen and its old element still shows, it moves with the page when the visitor scrolls (a wheel's momentum right after the click); on a fixed or sticky element it moves only as far as that element does.
|
|
210
241
|
|
|
211
|
-
###
|
|
242
|
+
### umber.transition(): one line where the change starts, one where it ends
|
|
212
243
|
|
|
213
244
|
Optional (the recipes below show where it goes for each router). With it, Umber knows the page change from its start: plays (reveals) wait, every plane is measured every frame, and an image that will fly freezes as soon as the next page is known, instead of fading out with the old one.
|
|
214
245
|
|
|
215
246
|
```js
|
|
216
247
|
let end = () => {};
|
|
217
248
|
// where the router starts a page change:
|
|
218
|
-
end =
|
|
249
|
+
end = umber.transition(); // or umber.transition(next): the next page, when the router has it
|
|
219
250
|
// where it is done:
|
|
220
251
|
end(); // end(0.2): plays start 0.2 s later; end(promise): when it settles
|
|
221
252
|
await end(); // also: resolves once the image landed and the new page draws (4 s at most)
|
|
222
253
|
```
|
|
223
254
|
|
|
224
255
|
- `next` is the next page in any form the router hands over: its HTML string, a parsed `Document`, its container element, Barba's cached `{ html }`, or a promise of one. A `Document` or element is matched exactly, and the `srcset` candidate the browser will pick there (its `sizes` at this screen and DPR) is fetched at once, so the hero's texture is ready when the image lands.
|
|
225
|
-
- A second `
|
|
256
|
+
- A second `umber.transition(next)` while one runs adds the next page to it and returns the same `end`, so "start at the click, refine when the router has the page" is two calls to one function.
|
|
226
257
|
- An `end` that never comes: after 8 s Umber ends it with a warning. Calling `end` twice does nothing.
|
|
227
|
-
- `
|
|
258
|
+
- `umber.hold()`, `umber.live()` and `umber.morph.capture(next)` / `umber.morph.settle()` stay as the lower-level parts.
|
|
228
259
|
|
|
229
260
|
### Recipes, one per router
|
|
230
261
|
|
|
231
|
-
Each recipe is the few lines you add next to the router's own setup, which stays exactly as its docs show. `
|
|
262
|
+
Each recipe is the few lines you add next to the router's own setup, which stays exactly as its docs show. `umber` is your engine, made once: `const umber = Umber.createUmber()`, or `createUmber()` from the npm package. The `umber.transition()` lines are optional: the image flies without them. With them Umber knows the page change from the click, so reveals wait and the image stops fading with the old page as soon as the router has the new one.
|
|
232
263
|
|
|
233
|
-
On the elements, the same for every router: give the image the same `data-
|
|
264
|
+
On the elements, the same for every router: give the image the same `data-umber-id` on both pages, inside the part the router swaps. Each id once per page. The image lands where the DOM shows its target: a target under another section (one with a z-index and a background over the canvas) ends the flight hidden, and Umber warns once at landing.
|
|
234
265
|
|
|
235
266
|
```html
|
|
236
267
|
<!-- the list page -->
|
|
237
|
-
<a href="/work/dunes"><div data-
|
|
268
|
+
<a href="/work/dunes"><div data-umber="image" data-umber-id="dunes"><img src="dunes-480.jpg" alt="Sand dunes"></div></a>
|
|
238
269
|
<!-- the detail page -->
|
|
239
|
-
<div data-
|
|
270
|
+
<div data-umber="image" data-umber-id="dunes"><img src="dunes.jpg" alt="Sand dunes"></div>
|
|
240
271
|
```
|
|
241
272
|
|
|
242
273
|
#### Barba 2
|
|
243
274
|
|
|
244
275
|
```js
|
|
245
276
|
let end = () => {};
|
|
246
|
-
barba.hooks.before((data) => { end =
|
|
277
|
+
barba.hooks.before((data) => { end = umber.transition(data.next.html); });
|
|
247
278
|
barba.hooks.afterLeave(({ current }) => { current.container.style.display = "none"; });
|
|
248
279
|
barba.hooks.after(() => { end(0.1); });
|
|
249
280
|
```
|
|
250
281
|
|
|
251
|
-
- Next to your `barba.init()`. It replaces the `
|
|
282
|
+
- Next to your `barba.init()`. It replaces the `umber.hold()` / `umber.live()` pair: it holds reveals and measures every frame too. Reveals start 0.1 s after the swap.
|
|
252
283
|
- Barba adds the new container below the old one and removes the old one only after `enter`. Umber flies only to an image on the first screen, so the `afterLeave` line takes the faded-out page out of the layout, and the image flies as the new page comes in. Without it, Umber asks again when Barba removes the old container, and the image flies only then, after `enter`. With `sync: true` both pages show at once: leave that line out and stack the containers, so it flies at once:
|
|
253
284
|
|
|
254
285
|
```css
|
|
@@ -258,44 +289,44 @@ barba.hooks.after(() => { end(0.1); });
|
|
|
258
289
|
|
|
259
290
|
- Keep the braces in `after`. Barba waits for a promise a hook returns, and a click while it waits reloads the page.
|
|
260
291
|
- `data.next.html` is only filled in `before` with `sync: true`: then the image stops fading with the old page at the click. In Barba's default transition it is `""` there, which Umber reads as "not known yet".
|
|
261
|
-
- Elements: `data-
|
|
292
|
+
- Elements: `data-umber-id` on the image inside `data-barba="container"`.
|
|
262
293
|
- Umber: with `sync: true` the image flies from where it is; otherwise from where it was last drawn (from transparent if your `leave` faded it out).
|
|
263
294
|
|
|
264
295
|
#### Swup 4 (tested on 4.8.2)
|
|
265
296
|
|
|
266
297
|
```js
|
|
267
298
|
let end = () => {};
|
|
268
|
-
swup.hooks.on("visit:start", () => (end =
|
|
269
|
-
swup.hooks.on("page:load", (visit, { page }) =>
|
|
299
|
+
swup.hooks.on("visit:start", () => (end = umber.transition()));
|
|
300
|
+
swup.hooks.on("page:load", (visit, { page }) => umber.transition(page.html));
|
|
270
301
|
swup.hooks.on("visit:end", () => end());
|
|
271
302
|
```
|
|
272
303
|
|
|
273
|
-
- After `const swup = new Swup()`. No hook at all: `Umber.
|
|
274
|
-
- Elements: `data-
|
|
304
|
+
- After `const swup = new Swup()`. No hook at all: `Umber.createUmber({ busy: "html.is-changing" })` instead.
|
|
305
|
+
- Elements: `data-umber-id` on the image inside Swup's container (`#swup`).
|
|
275
306
|
- Umber: Swup fades the container out, swaps it in one go and fades it in. The image stops fading once Swup has the page and flies from there. With `body` as the container, Umber puts its canvas back too.
|
|
276
307
|
|
|
277
308
|
#### Taxi
|
|
278
309
|
|
|
279
310
|
```js
|
|
280
311
|
let end = () => {};
|
|
281
|
-
router.on("NAVIGATE_OUT", () => (end =
|
|
312
|
+
router.on("NAVIGATE_OUT", () => (end = umber.transition()));
|
|
282
313
|
router.on("NAVIGATE_END", () => end());
|
|
283
314
|
```
|
|
284
315
|
|
|
285
316
|
- `router` is your `new Core()` from Taxi (`new taxi.Core()` from its script tag).
|
|
286
|
-
- Elements: `data-
|
|
317
|
+
- Elements: `data-umber-id` on the image inside `data-taxi-view`.
|
|
287
318
|
- Umber: Taxi removes the old view before the new one comes, so for a moment there is no page. The image waits up to 3 s for its id and flies across the gap.
|
|
288
319
|
|
|
289
320
|
#### Highway
|
|
290
321
|
|
|
291
322
|
```js
|
|
292
323
|
let end = () => {};
|
|
293
|
-
H.on("NAVIGATE_OUT", () => (end =
|
|
324
|
+
H.on("NAVIGATE_OUT", () => (end = umber.transition()));
|
|
294
325
|
H.on("NAVIGATE_END", () => end());
|
|
295
326
|
```
|
|
296
327
|
|
|
297
328
|
- `H` is your `new Highway.Core()`.
|
|
298
|
-
- Elements: `data-
|
|
329
|
+
- Elements: `data-umber-id` on the image inside `data-router-view`.
|
|
299
330
|
- Highway adds the new view below the old one. Remove `from` at the start of your `in` transition, as Highway's own examples do, so the new view starts on the first screen: Umber flies only to an image there.
|
|
300
331
|
- Umber: the image flies from where it was last drawn.
|
|
301
332
|
|
|
@@ -303,16 +334,16 @@ H.on("NAVIGATE_END", () => end());
|
|
|
303
334
|
|
|
304
335
|
```html
|
|
305
336
|
<script data-turbo-eval="false">
|
|
306
|
-
const
|
|
337
|
+
const umber = Umber.createUmber();
|
|
307
338
|
let end = () => {};
|
|
308
|
-
addEventListener("turbo:visit", () => (end =
|
|
309
|
-
addEventListener("turbo:before-render", (e) =>
|
|
339
|
+
addEventListener("turbo:visit", () => (end = umber.transition()));
|
|
340
|
+
addEventListener("turbo:before-render", (e) => umber.transition(e.detail.newBody));
|
|
310
341
|
addEventListener("turbo:load", () => end());
|
|
311
342
|
</script>
|
|
312
343
|
```
|
|
313
344
|
|
|
314
|
-
- Turbo runs the scripts in each new `<body>`: keep `data-turbo-eval="false"` on this tag (or put it in `<head>`), so the engine is made once. No hook at all: `Umber.
|
|
315
|
-
- Elements: `data-
|
|
345
|
+
- Turbo runs the scripts in each new `<body>`: keep `data-turbo-eval="false"` on this tag (or put it in `<head>`), so the engine is made once. No hook at all: `Umber.createUmber({ busy: 'html[aria-busy="true"]' })`.
|
|
346
|
+
- Elements: `data-umber-id` on the image, anywhere in `<body>`. Umber's canvas needs no `data-turbo-permanent`.
|
|
316
347
|
- Umber: Turbo replaces `<body>`, canvas and all. Umber puts the canvas back before the frame paints. When Turbo shows a cached copy and then the real page, the flight goes on to the real one.
|
|
317
348
|
|
|
318
349
|
#### htmx (`hx-boost`)
|
|
@@ -320,34 +351,34 @@ H.on("NAVIGATE_END", () => end());
|
|
|
320
351
|
```js
|
|
321
352
|
let end = () => {};
|
|
322
353
|
const on = (type, fn) => document.addEventListener(type, (e) => e.detail.boosted && fn(e.detail));
|
|
323
|
-
on("htmx:beforeRequest", () => (end =
|
|
324
|
-
on("htmx:beforeSwap", (d) =>
|
|
354
|
+
on("htmx:beforeRequest", () => (end = umber.transition()));
|
|
355
|
+
on("htmx:beforeSwap", (d) => umber.transition(d.serverResponse));
|
|
325
356
|
on("htmx:afterRequest", (d) => d.successful || end());
|
|
326
357
|
on("htmx:afterSettle", () => end());
|
|
327
358
|
```
|
|
328
359
|
|
|
329
|
-
- In `<head>`, with `
|
|
360
|
+
- In `<head>`, with `createUmber()`: a boosted swap leaves `<head>` alone, so it runs once.
|
|
330
361
|
- `on()` listens to boosted navigations only: an `hx-get` partial or a poll is not a page change. A 404, a network error or an abort never settles, so `htmx:afterRequest` ends the change then (without it, Umber ends it after 8 s, with a warning).
|
|
331
|
-
- Elements: `data-
|
|
362
|
+
- Elements: `data-umber-id` on the image, anywhere in `<body hx-boost="true">`.
|
|
332
363
|
- Umber: htmx replaces everything inside `<body>`. Umber puts its canvas back and flies the image. The back button restores htmx's saved copy with no request, so no hook runs: Umber drops the copy's blank canvas and the image flies anyway.
|
|
333
364
|
|
|
334
365
|
#### Astro (client router)
|
|
335
366
|
|
|
336
367
|
```astro
|
|
337
368
|
<script>
|
|
338
|
-
import {
|
|
339
|
-
const
|
|
369
|
+
import { createUmber } from "@occluze/umber";
|
|
370
|
+
const umber = createUmber();
|
|
340
371
|
let end = () => {};
|
|
341
|
-
document.addEventListener("astro:before-preparation", () => { end =
|
|
342
|
-
document.addEventListener("astro:before-swap", (e) => {
|
|
372
|
+
document.addEventListener("astro:before-preparation", () => { end = umber.transition(); });
|
|
373
|
+
document.addEventListener("astro:before-swap", (e) => { umber.transition(e.newDocument); });
|
|
343
374
|
document.addEventListener("astro:page-load", () => { end(); });
|
|
344
375
|
</script>
|
|
345
376
|
```
|
|
346
377
|
|
|
347
|
-
- In the layout that has `<ClientRouter />`. A bundled `<script>` runs once. No hook at all: `
|
|
348
|
-
- **Without the npm package** (Umber's files from the CDN, or copied into `public/umber/`): link `umber.css` in the layout's `<head>`, load `umber.js` there too with `<script is:inline src="/umber/umber.js"></script>` (`is:inline`: Astro must not bundle it), and use `window.Umber.
|
|
349
|
-
- Elements: `data-
|
|
350
|
-
- Umber: Astro swaps `<body>` and copies `<html>`'s attributes inside a View Transition. Umber puts its canvas and `has-
|
|
378
|
+
- In the layout that has `<ClientRouter />`. A bundled `<script>` runs once. No hook at all: `createUmber({ busy: "html[data-astro-transition]" })`.
|
|
379
|
+
- **Without the npm package** (Umber's files from the CDN, or copied into `public/umber/`): link `umber.css` in the layout's `<head>`, load `umber.js` there too with `<script is:inline src="/umber/umber.js"></script>` (`is:inline`: Astro must not bundle it), and use `window.Umber.createUmber(...)` in the bundled script above instead of the import (its type: `/// <reference types="@occluze/umber/global" />`). Self-hosting the npm build (`umber.mjs`) instead: `createUmber({ base: "/umber/" })`, so its chunks load from that folder, not the CDN.
|
|
380
|
+
- Elements: `data-umber-id` on the image. It does not need `transition:name`; a `transition:name` makes the browser fly it instead (see View Transitions below).
|
|
381
|
+
- Umber: Astro swaps `<body>` and copies `<html>`'s attributes inside a View Transition. Umber puts its canvas and `has-umber` back and flies the image.
|
|
351
382
|
|
|
352
383
|
#### Next.js (App Router)
|
|
353
384
|
|
|
@@ -356,11 +387,11 @@ on("htmx:afterSettle", () => end());
|
|
|
356
387
|
"use client";
|
|
357
388
|
import { useEffect } from "react";
|
|
358
389
|
import { usePathname } from "next/navigation";
|
|
359
|
-
import {
|
|
390
|
+
import { createUmber } from "@occluze/umber";
|
|
360
391
|
|
|
361
|
-
const
|
|
392
|
+
const umber = createUmber(); // module level: once, also in StrictMode; on the server it does nothing
|
|
362
393
|
let end = () => {};
|
|
363
|
-
const start = () => { end =
|
|
394
|
+
const start = () => { end = umber.transition(); };
|
|
364
395
|
if (typeof window !== "undefined") {
|
|
365
396
|
addEventListener("click", (e) => {
|
|
366
397
|
const a = (e.target as Element).closest("a");
|
|
@@ -377,34 +408,34 @@ export function Umber() {
|
|
|
377
408
|
```
|
|
378
409
|
|
|
379
410
|
- The App Router has no navigation events, so the change starts at a link click or the back button, and ends once the new route has rendered. Import `@occluze/umber/umber.css` in `app/layout.tsx`.
|
|
380
|
-
- Elements: `data-
|
|
411
|
+
- Elements: `data-umber-id` on the image in each page's JSX: `<div data-umber="image" data-umber-id={slug}>`.
|
|
381
412
|
- Umber: React swaps the page in one go and the image flies from where it was last drawn. Behind a `loading.tsx` state it waits up to 3 s for the page.
|
|
382
413
|
|
|
383
414
|
#### Nuxt
|
|
384
415
|
|
|
385
416
|
```ts
|
|
386
417
|
// plugins/umber.client.ts: runs once, in the browser only
|
|
387
|
-
import {
|
|
418
|
+
import { createUmber } from "@occluze/umber";
|
|
388
419
|
import "@occluze/umber/umber.css";
|
|
389
420
|
|
|
390
421
|
export default defineNuxtPlugin((nuxtApp) => {
|
|
391
|
-
const
|
|
422
|
+
const umber = createUmber();
|
|
392
423
|
let end = () => {};
|
|
393
|
-
useRouter().beforeEach((to, from) => { if (to.path !== from.path) end =
|
|
424
|
+
useRouter().beforeEach((to, from) => { if (to.path !== from.path) end = umber.transition(); });
|
|
394
425
|
nuxtApp.hook("page:finish", () => { end(); });
|
|
395
|
-
return { provide: {
|
|
426
|
+
return { provide: { umber } };
|
|
396
427
|
});
|
|
397
428
|
```
|
|
398
429
|
|
|
399
430
|
- `to.path !== from.path`: a query or hash change on the same page is not a page change, so it starts nothing.
|
|
400
|
-
- Elements: `data-
|
|
431
|
+
- Elements: `data-umber-id` on the image in each page's template: `<div data-umber="image" :data-umber-id="slug">`.
|
|
401
432
|
- Umber: with no page transition Vue swaps the page in one go, and the image flies from where it was last drawn. With `pageTransition: { mode: "out-in" }` the old page leaves first, and the image waits up to 3 s for the new one. With both pages in at once (no `mode`), stack them in CSS so the new one starts on the first screen; otherwise the image flies once the old page has left.
|
|
402
433
|
|
|
403
434
|
#### Your own View Transition
|
|
404
435
|
|
|
405
436
|
```js
|
|
406
437
|
function go(swap) {
|
|
407
|
-
const end =
|
|
438
|
+
const end = umber.transition();
|
|
408
439
|
if (!document.startViewTransition) {
|
|
409
440
|
swap();
|
|
410
441
|
end();
|
|
@@ -414,18 +445,18 @@ function go(swap) {
|
|
|
414
445
|
}
|
|
415
446
|
```
|
|
416
447
|
|
|
417
|
-
- `swap` is your function that changes the page. Call `
|
|
418
|
-
- Elements: `data-
|
|
419
|
-
- Umber: GL flies the `data-
|
|
448
|
+
- `swap` is your function that changes the page. Call `umber.transition()` before `startViewTransition()`, so the browser's snapshot is taken after Umber stepped aside.
|
|
449
|
+
- Elements: `data-umber-id` on an image Umber flies. An element with a `view-transition-name` is flown by the browser instead.
|
|
450
|
+
- Umber: GL flies the `data-umber-id` image, the browser cross-fades the rest, and reveals start once the browser's animation is over.
|
|
420
451
|
|
|
421
|
-
Working pages: `examples/transitions/swup.html`, `taxi.html`, `turbo.html`, `htmx.html` and `view-transition.html` (each has the lines above), and `barba.html` (Barba without `data-
|
|
452
|
+
Working pages: `examples/transitions/swup.html`, `taxi.html`, `turbo.html`, `htmx.html` and `view-transition.html` (each has the lines above), and `barba.html` (Barba without `data-umber-id`). Highway, Astro, Next and Nuxt have no example page yet.
|
|
422
453
|
|
|
423
|
-
###
|
|
454
|
+
### umber.leave(): the old page's GL over the new one
|
|
424
455
|
|
|
425
456
|
A page-change look drawn by the renderer, for any router. On every page change a copy of what the old page's GL drew is laid over the new page, and a few lines of your GLSL take it away:
|
|
426
457
|
|
|
427
458
|
```js
|
|
428
|
-
|
|
459
|
+
umber.leave(`vec4 leave(vec2 uv) {
|
|
429
460
|
float edge = uProgress * 1.2 - 0.1;
|
|
430
461
|
return prev(uv) * smoothstep(edge - 0.1, edge, 1.0 - uv.y); // wiped off from the bottom
|
|
431
462
|
}`, { duration: 0.9, ease: "expo.inOut" });
|
|
@@ -434,49 +465,49 @@ gl.leave(`vec4 leave(vec2 uv) {
|
|
|
434
465
|
- `leave(uv)`: what to show at `uv`, (0, 0) the screen's top left. Premultiplied in and out, like the canvas. `prev(uv)` is the old page; `uProgress` runs 0 -> 1, eased; `uSize` (device px) and `uTime` are there, and your own `uniforms: { ... }` (a `{ value }` is read every frame: change the direction before each change).
|
|
435
466
|
- Without `next(uv)` your result is laid **over** the new page (return transparent where it should show). Call `next(uv)` and it **replaces** the canvas: `mix(prev(uv), next(uv), uProgress)` is a true cross-fade (the new page is copied every frame while it plays).
|
|
436
467
|
- It covers **GL content only**: the images, videos, GL text and shaders the old page drew. Its DOM (text, backgrounds) is the router's job, as always.
|
|
437
|
-
- When: the copy is armed by `
|
|
438
|
-
- `data-
|
|
439
|
-
- Start `
|
|
440
|
-
- With `data-
|
|
468
|
+
- When: the copy is armed by `umber.transition()` and (unless `links: false`) by pressing a same-origin link to another page (a link that only changes the hash, `#filters`, does not) or going back / forward. While armed, every frame the page draws anyway is copied; nothing is asked for while nothing is armed, and a still page stays at 0 frames a second. The copy freezes when the old page goes (GL elements leave or arrive, or inside `umber.transition()` fewer of them are drawn than the frame before, as when a router hides the old container), and plays out from `end()`. With no `umber.transition()` at all, it plays from the swap itself.
|
|
469
|
+
- `data-umber-id` images fly above it. With `data-umber-pass` on the page, the copy is the frame before the passes, drawn back under them: the passes run over the old page and the new one together, once, and the flying images keep their look. So give both pages the same `data-umber-pass` (on `<html>`, which routers leave alone); when it changes with the page, the old page leaves under the new page's passes (said once). Reduced motion: none. `umber.leave(null)` turns it off. Not the handoff module's cover pass (`umber.handoff.cover()`, a shader that closes over the page): this one is the old page's own GL.
|
|
470
|
+
- Start `umber.transition()` where the change starts (the click), as the recipes above do. With no copy yet (a key press, a router's own navigation), `umber.transition()` draws one frame right away and copies it, so a router that swaps in the same task still gets its leave.
|
|
471
|
+
- With `data-umber-pass` on the page, the copy is the frame before the passes, laid over the new page before them: the passes run over both, once.
|
|
441
472
|
|
|
442
|
-
### Same page:
|
|
473
|
+
### Same page: umber.flip(), plane.lift(), plane.land()
|
|
443
474
|
|
|
444
475
|
A layout change on one page (a grid becomes a list, a card opens, a filter re-orders) flown on the GPU. The DOM jumps to its new layout at once; each GL element's copy flies from its old box to its new one, corners and all. Nothing in the DOM is animated, and the new place is measured once.
|
|
445
476
|
|
|
446
477
|
```js
|
|
447
|
-
await
|
|
478
|
+
await umber.flip(".cards", () => cards.classList.toggle("is-list"), { duration: 0.8, ease: "expo.out", stagger: 0.03 });
|
|
448
479
|
```
|
|
449
480
|
|
|
450
|
-
- `els`: a selector, an element or a list; every GL element inside flies. `change()` runs right away, before `
|
|
481
|
+
- `els`: a selector, an element or a list; every GL element inside flies. `change()` runs right away, before `umber.flip()` returns. Resolves once all have landed. A new `umber.flip()` mid-flight flies on from where they are.
|
|
451
482
|
- Only elements in both layouts fly (one that arrives reveals as usual) and only flat ones (a turned or tilted element jumps). Without GL, `change()` simply runs.
|
|
452
|
-
- **Next to GSAP's Flip plugin:** that one animates the DOM itself, and Umber already follows any element it moves, so GL stays on it with no extra code. Use `
|
|
453
|
-
- **`plane.lift()`** resolves with the plane's rect, `{ x, y, width, height }` in viewport px, that you move with anything (GSAP, your own loop); it stays put on screen while the page scrolls. `plane.land({ duration })` flies it home to its element:
|
|
483
|
+
- **Next to GSAP's Flip plugin:** that one animates the DOM itself, and Umber already follows any element it moves, so GL stays on it with no extra code. Use `umber.flip()` when only the GL copy should move (the card's DOM can jump), and never both on the same element.
|
|
484
|
+
- **`plane.lift()`** resolves with the plane's rect, `{ x, y, width, height }` in viewport px (or `null` when `chunks/flip.js` can't load or the plane is gone), that you move with anything (GSAP, your own loop); it stays put on screen while the page scrolls. `plane.land({ duration })` flies it home to its element:
|
|
454
485
|
|
|
455
486
|
```js
|
|
456
|
-
const plane =
|
|
457
|
-
const r = await plane
|
|
458
|
-
await gsap.to(r, { x: 0, y: 0, width: innerWidth, height: innerHeight, duration: 0.7 });
|
|
487
|
+
const plane = umber.plane(card.querySelector("[data-umber]"));
|
|
488
|
+
const r = await plane?.lift();
|
|
489
|
+
if (r) await gsap.to(r, { x: 0, y: 0, width: innerWidth, height: innerHeight, duration: 0.7 });
|
|
459
490
|
// ... later
|
|
460
|
-
await plane
|
|
491
|
+
await plane?.land({ duration: 0.6 });
|
|
461
492
|
```
|
|
462
493
|
|
|
463
|
-
`
|
|
494
|
+
`umber.flip()`, `lift()` and `land()` are `chunks/flip.js`, fetched on the first call (the planes stay where they were meanwhile). Working page: `examples/transitions/renderer.html`.
|
|
464
495
|
|
|
465
|
-
###
|
|
496
|
+
### createUmber({ busy }): no hook at all
|
|
466
497
|
|
|
467
|
-
Many routers mark `<html>` while a page changes. Give Umber that selector and it acts as inside `
|
|
498
|
+
Many routers mark `<html>` while a page changes. Give Umber that selector and it acts as inside `umber.transition()` while `<html>` matches:
|
|
468
499
|
|
|
469
500
|
```js
|
|
470
|
-
Umber.
|
|
471
|
-
Umber.
|
|
472
|
-
Umber.
|
|
501
|
+
Umber.createUmber({ busy: "html.is-changing" }); // Swup
|
|
502
|
+
Umber.createUmber({ busy: 'html[aria-busy="true"]' }); // Turbo
|
|
503
|
+
Umber.createUmber({ busy: "html[data-astro-transition]" }); // Astro's client router
|
|
473
504
|
```
|
|
474
505
|
|
|
475
506
|
Off by default: a site that leaves such a flag on (a spinner's `aria-busy`) would keep Umber measuring every frame and holding reveals. So it also ends by itself after 8 s, and starts again only once `<html>` stopped matching in between.
|
|
476
507
|
|
|
477
508
|
### View Transitions
|
|
478
509
|
|
|
479
|
-
A plain root cross-fade (Astro's default, Turbo 8's `<meta name="view-transition">`, `@view-transition`) needs nothing: the canvas is part of the page's snapshot. An element **with a `view-transition-name`** is snapshotted on its own: while a page change runs (`
|
|
510
|
+
A plain root cross-fade (Astro's default, Turbo 8's `<meta name="view-transition">`, `@view-transition`) needs nothing: the canvas is part of the page's snapshot. An element **with a `view-transition-name`** is snapshotted on its own: while a page change runs (`umber.transition()` or `busy`), a GL element with a name shows its own DOM and GL leaves it out, so the browser's snapshot of it is the image (drawn by GL it would be an empty box, and its GL pixels would stay behind at the old place). The browser flies it; Umber does not fly it too. GL takes it back with the usual handshake at `end()`: pass the transition's `finished` (`end(vt.finished)`) to wait for the browser's animation. Call `umber.transition()` before `startViewTransition()`, so the old snapshot is taken after Umber stepped aside.
|
|
480
511
|
|
|
481
512
|
A flight between two separate documents (a multi-page site with no router), the canvas over cross-document View Transitions and a cover pass: the handoff module, next section. Not yet: a flight to an element the router scrolls onto the first screen only after the swap.
|
|
482
513
|
|
|
@@ -484,52 +515,52 @@ A flight between two separate documents (a multi-page site with no router), the
|
|
|
484
515
|
|
|
485
516
|
## Across full page loads (module: `modules/handoff.js`): multi-page sites with no router
|
|
486
517
|
|
|
487
|
-
A site with no router (Webflow, plain HTML, any server-rendered site) loads a whole new document on every link. The handoff module makes a `data-
|
|
518
|
+
A site with no router (Webflow, plain HTML, any server-rendered site) loads a whole new document on every link. The handoff module makes a `data-umber-id` image fly across that load, the same flight as with a router: the old page writes where each image was, the new page flies it from there to its place. Load it on every page:
|
|
488
519
|
|
|
489
520
|
```html
|
|
490
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
521
|
+
<script src="https://umber.occluze.com/umber@0.3.0/modules/handoff.js"></script> <!-- after or before umber.js -->
|
|
491
522
|
```
|
|
492
523
|
```js
|
|
493
524
|
import { Handoff } from "@occluze/umber/handoff"; // npm
|
|
494
|
-
|
|
495
|
-
// script build: options right after
|
|
496
|
-
|
|
525
|
+
umber.use(Handoff, { cover: "ink" }); // or createUmber({ modules: [Handoff] })
|
|
526
|
+
// script build: options right after createUmber()
|
|
527
|
+
umber.handoff.options.cover = "ink";
|
|
497
528
|
```
|
|
498
529
|
|
|
499
530
|
And paste this into `<head>` on every page (Webflow: Site settings, Custom code, "Inside `<head>` tag"), before anything else that renders:
|
|
500
531
|
|
|
501
532
|
```html
|
|
502
|
-
<script>(function(w,d){try{var r=JSON.parse(sessionStorage.getItem("umber:handoff")),n=performance.getEntriesByType("navigation")[0],h=d.documentElement,s=
|
|
533
|
+
<script>(function(w,d){try{var r=JSON.parse(sessionStorage.getItem("umber:handoff")),n=performance.getEntriesByType("navigation")[0],h=d.documentElement,s,a="adoptedStyleSheets";if(!r||!(Date.now()-r.at<3e3)||n&&n.type=="reload"||r.to!=location.href.split("#")[0])return;s=w.__umberHide=new CSSStyleSheet;s.replaceSync((r.items.length?r.items.map(function(i){var k='[data-umber-id="'+i.id.replace(/["\\]/g,"\\$&")+'"]';return k+':is(img,video),'+k+' :is(img,video)'}).join()+"{opacity:0!important}":"")+"::view-transition-group(umber-gl){animation:none}::view-transition-old(umber-gl),::view-transition-new(umber-gl){mix-blend-mode:normal}::view-transition-new(umber-gl){animation:none}");d[a]=d[a].concat(s);setTimeout(function(){h.hasAttribute("data-umber-handoff")||(d[a]=d[a].filter(function(x){return x!=s}))},1500);w.addEventListener("pagereveal",function(e){var v=w.__umberReveal=e.viewTransition||null,g=d.querySelector("[data-umber-host]");if(v&&r.over){if(!g){g=d.createElement("div");g.setAttribute("data-umber-host","");g.style.zIndex=1;(d.body||h).prepend(g)}g.style.viewTransitionName="umber-gl"}})}catch(e){}})(window,document)</script>
|
|
503
534
|
```
|
|
504
535
|
|
|
505
536
|
It runs before the first paint, which a script at the end of `<body>` cannot promise. On a page opened through a link with a flying image it hides exactly that image until Umber flies it (so the first paint never shows it at its new place), keeps the cross-document View Transition for the module, and lifts the canvas above it in time. If Umber has not taken over after 1.5 s, the image shows. Without the snippet everything still works; the first frame may show the image at its new place before it flies. The same string is `Handoff.headSnippet` in code.
|
|
506
537
|
|
|
507
|
-
Elements: nothing new. The same `data-
|
|
538
|
+
Elements: nothing new. The same `data-umber-id` on the image on both pages, as with a router:
|
|
508
539
|
|
|
509
540
|
```html
|
|
510
|
-
<!-- work.html --> <a href="dunes.html"><div data-
|
|
511
|
-
<!-- dunes.html --> <div data-
|
|
541
|
+
<!-- work.html --> <a href="dunes.html"><div data-umber="image" data-umber-id="dunes"><img src="dunes.jpg" alt="Dunes"></div></a>
|
|
542
|
+
<!-- dunes.html --> <div data-umber="image" data-umber-id="dunes" data-umber-morph-duration="1.2"><img src="dunes.jpg" alt="Dunes"></div>
|
|
512
543
|
```
|
|
513
544
|
|
|
514
545
|
### What happens
|
|
515
546
|
|
|
516
|
-
- **Leaving.** On the browser's `pageswap` (Chrome and Edge 124+, Safari 18.2+), or on `pagehide` after a same-origin link click where there is no `pageswap`, the page writes one sessionStorage record (`umber:handoff`): the URL it goes to, the click, and each `data-
|
|
517
|
-
- **Arriving.** The next page reads the record once (then it is gone). It counts only for that URL (the `#hash` aside), for 3 s (`maxAge`), and never on a reload. Each image whose `data-
|
|
547
|
+
- **Leaving.** On the browser's `pageswap` (Chrome and Edge 124+, Safari 18.2+), or on `pagehide` after a same-origin link click where there is no `pageswap`, the page writes one sessionStorage record (`umber:handoff`): the URL it goes to, the click, and each `data-umber-id` image GL draws on screen (its last measured rect, its picture, its corners). No layout is read. Umber never stops the link or delays the load.
|
|
548
|
+
- **Arriving.** The next page reads the record once (then it is gone). It counts only for that URL (the `#hash` aside), for 3 s (`maxAge`), and never on a reload. Each image whose `data-umber-id` is on the new page's **first screen** gets a stand-in at the old rect: a plain `<img>` of the old picture (from the browser cache: the old page showed it) that the browser paints at once, and a GL plane. Once GL draws it, it flies to its target with the usual flight (`data-umber-morph-duration`, `data-umber-morph-ease`, corners, the target's sharper texture), and the target takes over.
|
|
518
549
|
- **Fails open.** No GL on this device: the stand-in flies in the DOM (an animation of its box), then the target shows. A stand-in that does not draw within 1.5 s, a target below the first screen, `prefers-reduced-motion`, a window of another width: no flight, the page shows as it loaded.
|
|
519
550
|
- **Back** (a history step to an earlier page) waits for the browser's own scroll restore (the `load` event, 1 s at most) before looking for targets. A forward step does not, except in a browser without the Navigation API, where any back/forward load counts as back. A page restored from the back/forward cache is the old page as it was; nothing flies.
|
|
520
551
|
- **Prerendered pages** (speculation rules) read the record when they are shown, not when they are prerendered. With prerender the target's texture is ready before the click, so the flight starts on the first frame.
|
|
521
552
|
|
|
522
553
|
### Cross-document View Transitions
|
|
523
554
|
|
|
524
|
-
With `@view-transition { navigation: auto; }` in both pages' CSS, the browser cross-fades the two documents. With the module, the canvas is lifted out of the pages' snapshots (`view-transition-name: umber-gl`) and stays live and fully opaque on top, so the image flies, and the cover plays, during the browser's cross-fade. The old page's canvas picture fades out with its page (its GL images keep their effects; no empty boxes). It needs `layer: "over"` (the default); with `layer: "under"` the canvas cross-fades with the page and Umber warns once (`
|
|
555
|
+
With `@view-transition { navigation: auto; }` in both pages' CSS, the browser cross-fades the two documents. With the module, the canvas is lifted out of the pages' snapshots (`view-transition-name: umber-gl`) and stays live and fully opaque on top, so the image flies, and the cover plays, during the browser's cross-fade. The old page's canvas picture fades out with its page (its GL images keep their effects; no empty boxes). It needs `layer: "over"` (the default); with `layer: "under"` the canvas cross-fades with the page and Umber warns once (`umber.use(Handoff, { vt: false })` silences it). `umber.handoff.viewTransition` is the browser's transition object on the new page (await its `finished`). To time the canvas's own fade:
|
|
525
556
|
|
|
526
557
|
```css
|
|
527
558
|
::view-transition-old(umber-gl) { animation-duration: 0.4s; }
|
|
528
559
|
```
|
|
529
560
|
|
|
530
|
-
### The cover pass: `
|
|
561
|
+
### The cover pass: `umber.handoff.cover(shader, { phase })`
|
|
531
562
|
|
|
532
|
-
A full-screen pass of **your own shader** over the page while it changes. Umber ships no look: it puts one fixed, full-screen `data-
|
|
563
|
+
A full-screen pass of **your own shader** over the page while it changes. Umber ships no look: it puts one fixed, full-screen `data-umber="shader"` element over the page and moves its uniforms.
|
|
533
564
|
|
|
534
565
|
| Uniform | |
|
|
535
566
|
|---|---|
|
|
@@ -539,7 +570,7 @@ A full-screen pass of **your own shader** over the page while it changes. Umber
|
|
|
539
570
|
|
|
540
571
|
```js
|
|
541
572
|
import { Handoff } from "@occluze/umber/handoff"; // npm
|
|
542
|
-
|
|
573
|
+
umber.shader("ink", {
|
|
543
574
|
uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 },
|
|
544
575
|
fragment: `
|
|
545
576
|
float d = distance(vUv * uViewport / uViewport.y, uOrigin * uViewport / uViewport.y);
|
|
@@ -547,12 +578,12 @@ gl.shader("ink", {
|
|
|
547
578
|
color = vec4(0.08, 0.08, 0.08, 1.0 - smoothstep(edge - 0.05, edge, d));
|
|
548
579
|
`,
|
|
549
580
|
});
|
|
550
|
-
|
|
551
|
-
// script build:
|
|
581
|
+
umber.use(Handoff, { cover: "ink", coverDuration: 0.8 }); // plays "reveal" on every page reached through a link
|
|
582
|
+
// script build: umber.handoff.options.cover = "ink"; umber.handoff.options.coverDuration = 0.8;
|
|
552
583
|
```
|
|
553
584
|
|
|
554
|
-
- Without a router the leaving page cannot wait, so the **next page plays the reveal half**, from the old page's click. With a router, play both halves yourself: `
|
|
555
|
-
- Give `[data-
|
|
585
|
+
- Without a router the leaving page cannot wait, so the **next page plays the reveal half**, from the old page's click. With a router, play both halves yourself: `umber.handoff.cover("ink", { phase: "cover" })` where the change starts (await it before the swap if the cover should close first), `{ phase: "reveal" }` once the new page is in.
|
|
586
|
+
- Give `[data-umber-cover]` a background in your CSS (`[data-umber-cover] { background: #141414; }`): the page is covered by it until GL draws the shader, and without GL it fades instead.
|
|
556
587
|
- Declare the uniforms the shader reads; only `uCover` is required (Umber warns once without it). Flying images draw over the cover.
|
|
557
588
|
- Options: `duration`, `ease`, `origin` (viewport px), `direction`. Reduced motion: nothing plays.
|
|
558
589
|
|
|
@@ -560,21 +591,21 @@ gl.use(Handoff, { cover: "ink", coverDuration: 0.8 }); // plays "reveal" on ev
|
|
|
560
591
|
|
|
561
592
|
- Nothing the module draws is focusable or read out: the stand-ins are `aria-hidden` (with an empty `alt`), the cover is `aria-hidden` and `inert`; the real `<img alt>` stays in the page.
|
|
562
593
|
- **Focus.** When the old page was left from the keyboard (Enter on a link), focus moves to the new page's first `h1` (option `focus`: any selector, or `false` for the browser's own), without scrolling.
|
|
563
|
-
- **Announcement.** A full page load is announced by the screen reader itself, so it is off by default (`announce: true` turns it on). With a router, call `
|
|
594
|
+
- **Announcement.** A full page load is announced by the screen reader itself, so it is off by default (`announce: true` turns it on). With a router, call `umber.handoff.announce()` (the new `document.title`, or a text) and `umber.handoff.focus()` at the end of each swap.
|
|
564
595
|
- **Scroll.** A back step waits for the browser's scroll restore before anything flies. Umber never sets `history.scrollRestoration`.
|
|
565
596
|
|
|
566
597
|
| Option | Default | |
|
|
567
598
|
|---|---|---|
|
|
568
599
|
| `maxAge` | `3000` | ms a record stays good. The head snippet always uses 3 s: with a longer `maxAge`, an older record still flies, but its image may show at its new place on the first paint. |
|
|
569
600
|
| `vt` | `true` | Lift the canvas over a cross-document View Transition. |
|
|
570
|
-
| `cover` | `null` | A `
|
|
601
|
+
| `cover` | `null` | A `umber.shader()` name played (`"reveal"`) on arrival. |
|
|
571
602
|
| `coverDuration` / `coverEase` | `0.8` / `"umber"` | That reveal's seconds and ease. |
|
|
572
603
|
| `focus` | `"h1"` | Where focus goes after a keyboard navigation; `false`: the browser's own. |
|
|
573
604
|
| `announce` | `false` | Say the new title on arrival. |
|
|
574
605
|
|
|
575
|
-
`
|
|
606
|
+
`umber.handoff`: `arrived` (the record, or null), `origin` (the click, viewport px), `direction` (1 or -1), `viewTransition`, `options`, `cover()`, `announce()`, `focus()`.
|
|
576
607
|
|
|
577
|
-
- Same origin only (sessionStorage is per tab and per origin). Images only: a `data-
|
|
608
|
+
- Same origin only (sessionStorage is per tab and per origin). Images only: a `data-umber-id` video, text or layer loads anew on the next page.
|
|
578
609
|
- Working pages: `examples/transitions/mpa-list.html` and `mpa-detail.html` (plain links, no router).
|
|
579
610
|
|
|
580
611
|
---
|
|
@@ -583,60 +614,63 @@ gl.use(Handoff, { cover: "ink", coverDuration: 0.8 }); // plays "reveal" on ev
|
|
|
583
614
|
|
|
584
615
|
An optional module that changes pages without a full page load, with transitions of your own or ready-made presets, so a site needs no separate page-transition router. `umber.js` never carries it. A site that keeps its own router (Barba, Swup, Taxi...) leaves this module out and works exactly as before: never load both (with Barba, Swup, Turbo, htmx `hx-boost`, Astro's or WordPress's router on the page, this one stays off and says so once in the console).
|
|
585
616
|
|
|
586
|
-
**Which page transitions to use.** Most sites: this router. A multi-page site that should stay plain page loads: `modules/handoff.js` (the `data-
|
|
617
|
+
**Which page transitions to use.** Most sites: this router. A multi-page site that should stay plain page loads: `modules/handoff.js` (the `data-umber-id` image flies across the full load, with a cover). A site that already runs Barba, Swup or another router: keep it (the "Any router" recipes); never load two.
|
|
587
618
|
|
|
588
|
-
It does what a full page load would do, without the white flash: the address and history, the title and meta, the page's own stylesheets and scripts, scroll, focus and a screen-reader announcement. Umber's own parts come along by themselves: plays (reveals) wait for the transition, the new page's GL elements come up as it comes in, and a `data-
|
|
619
|
+
It does what a full page load would do, without the white flash: the address and history, the title and meta, the page's own stylesheets and scripts, scroll, focus and a screen-reader announcement. Umber's own parts come along by themselves: plays (reveals) wait for the transition, the new page's GL elements come up as it comes in, and a `data-umber-id` image flies between the pages with any transition.
|
|
589
620
|
|
|
590
621
|
### Set up: attributes only (Webflow, plain HTML)
|
|
591
622
|
|
|
592
623
|
```html
|
|
593
|
-
<!-- Footer code, every page
|
|
594
|
-
|
|
595
|
-
dist/modules/router.js (and router-swap.js next to it). -->
|
|
596
|
-
<script src="https://umber.occluze.com/umber@0.2.1/modules/router.js"></script>
|
|
624
|
+
<!-- Footer code, every page: router named on the umber.js tag (it loads at once, before the first click). -->
|
|
625
|
+
<script src="https://umber.occluze.com/umber@0.3.0/umber.js" data-umber-key="YOUR_KEY" data-umber-modules="scroll router"></script>
|
|
597
626
|
|
|
598
627
|
<!-- Custom attributes (Webflow: the element's settings, Custom attributes). A div around
|
|
599
628
|
what changes, on every page; the nav can stay outside it. The wrapper's
|
|
600
|
-
data-
|
|
601
|
-
<div data-
|
|
602
|
-
<main data-
|
|
629
|
+
data-umber-transition is the site's default. -->
|
|
630
|
+
<div data-umber="wrapper" data-umber-transition="fade">
|
|
631
|
+
<main data-umber="container" data-umber-page="home">The page's content</main>
|
|
603
632
|
</div>
|
|
604
633
|
|
|
605
634
|
<!-- One link with its own transition and options: -->
|
|
606
|
-
<a href="/about" data-
|
|
635
|
+
<a href="/about" data-umber-transition="curtain" data-umber-transition-color="#111">About</a>
|
|
607
636
|
|
|
608
637
|
<!-- A link the router leaves alone (a full page load): -->
|
|
609
|
-
<a href="/shop" data-
|
|
638
|
+
<a href="/shop" data-umber="skip">Shop</a>
|
|
610
639
|
```
|
|
611
640
|
|
|
612
|
-
Only the container is required; the wrapper is optional (its `data-
|
|
641
|
+
Only the container is required; the wrapper is optional (its `data-umber-transition` is the site's default, else `fade`). Presets by attribute: `none`, `fade`, `slide`, `zoom`, `curtain`, `wipe`, `cover`, `dissolve`, `native` (table below). `cover` by attribute alone is a disc of `data-umber-transition-color` growing from the click; name a `umber.shader()` with `data-umber-transition-shader` for anything else.
|
|
613
642
|
|
|
614
|
-
`
|
|
643
|
+
`createUmber()` stays as it is; the module registers itself. With npm: `import { Router } from "@occluze/umber/router"` and `createUmber({ modules: [Router] })` (or `umber.use(Router, { transition: "slide" })`). Options with the script build go on `umber.router.options` right after `createUmber()`:
|
|
615
644
|
|
|
616
645
|
```js
|
|
617
|
-
const
|
|
618
|
-
|
|
619
|
-
|
|
646
|
+
const umber = Umber.createUmber();
|
|
647
|
+
umber.router.options.transition = "curtain"; // the default when nothing else picks one
|
|
648
|
+
umber.router.options.prefetch = "viewport"; // also fetch links as they scroll into view
|
|
620
649
|
```
|
|
621
650
|
|
|
622
|
-
The module is two files: `modules/router.js` (links, history, fetching;
|
|
651
|
+
The module is two files: `modules/router.js` (links, forms, history, fetching; 7.5 KB brotli) and `modules/router-swap.js` (which transition, the steps, the head, the scripts, the swap and the presets; 7.8 KB brotli), which the first one loads by itself from the same folder when the browser is idle, or at the first click. Nothing to add for it. With npm your bundler splits it off.
|
|
623
652
|
|
|
624
|
-
**With Umber's scroll module** (`modules/scroll.js`, smooth scrolling), load both; they work as a pair with nothing to wire: the router stops the scroll module when a transition starts, carries the new page's `<body>` / `<html>` attributes (`data-
|
|
653
|
+
**With Umber's scroll module** (`modules/scroll.js`, smooth scrolling), load both; they work as a pair with nothing to wire: the router stops the scroll module when a transition starts, carries the new page's `<body>` / `<html>` attributes (`data-umber-scroll`, `data-umber-scroll-offset`, `data-umber-scroll-lerp`...) before it measures the new page (`resize()`), lands it at once at the top, the `#hash` (with the same `data-umber-scroll-offset` chain as the module: the link's, the target's, the page's) or where that history entry was, measures again when the transition ends, and starts it. The module's own in-page `#links` stay its own; back and forward between them land where each was.
|
|
625
654
|
|
|
626
655
|
### Attributes
|
|
627
656
|
|
|
628
657
|
| Attribute | On | What it does |
|
|
629
658
|
|---|---|---|
|
|
630
|
-
| `data-
|
|
631
|
-
| `data-
|
|
632
|
-
| `data-
|
|
633
|
-
| `data-
|
|
634
|
-
| `data-
|
|
635
|
-
| `data-
|
|
636
|
-
| `data-
|
|
637
|
-
| `data-
|
|
638
|
-
|
|
639
|
-
|
|
659
|
+
| `data-umber="container"` | the part of each page that changes | Required. The router swaps it for the next page's. A page without one is never changed in place: its links load normally, and a link to such a page loads it in full. |
|
|
660
|
+
| `data-umber="wrapper"` | an element around the container | Optional. The container is looked for inside it, and its `data-umber-transition` is the site's default. |
|
|
661
|
+
| `data-umber-page="work"` | the container | The page's name, for transitions `from` / `to` it. |
|
|
662
|
+
| `data-umber-transition="slide"` | a link (or a parent of links), a container, the wrapper | A preset or a transition you registered by `name`. On a link: for that link. On a container: for arriving on that page. On the wrapper: the site's default. |
|
|
663
|
+
| `data-umber-transition-duration="0.6"`, `-ease`, `-color`, `-shader`, `-above` | the element with `data-umber-transition` | The preset's options: seconds, a CSS easing, a CSS colour, a `umber.shader()` name, `above` (cover, dissolve: over a fixed nav too). |
|
|
664
|
+
| `data-umber="skip"` | a link or any parent; a `<script>` | The router leaves that link to the browser (a full page load) and never fetches it ahead, or never runs that script. |
|
|
665
|
+
| `data-umber-router-prefetch="false"` | a link or any parent | Changed in place when clicked, never fetched ahead (a link a GET may act on, a heavy page). |
|
|
666
|
+
| `data-umber-router-form` | a `<form>` or any parent | The router sends that form: a GET as a page change to its URL with its fields, a POST with `fetch` (never cached), its answer shown like any page (after a redirect at the answer's URL, else at the address shown). A POST whose answer the router can't show (not HTML, no container, a failure before it is in) is sent again by the browser itself, so mark only forms that may be sent twice. Without it every form is the browser's. |
|
|
667
|
+
| `data-umber-router-history="replace"` | a link or form, or any parent | The new page takes the place of the history entry shown (`go(url, { history: "replace" })` from code). |
|
|
668
|
+
| `data-umber-router-persist="player"` | an element inside the container, on both pages | The next page keeps this page's element as it is (a playing video, a form being filled, a GL element and its plane) in place of its own of that name. |
|
|
669
|
+
| `data-umber-router-update="cart"` | an element outside the container (a cart's count, a sidebar), on both pages | Replaced by the next page's element of that name at the swap (its scripts run), removed when the next page has none. |
|
|
670
|
+
| `data-umber-router-scroll="list"` | an element that scrolls on its own | Back and forward put it back where that entry had it, by its name. |
|
|
671
|
+
| `data-umber-router-track` | an element in `<head>` (your site's script or stylesheet, with its version in the URL) | When it differs on the next page (a new build of the site), that change is a full page load, so the new code starts clean. |
|
|
672
|
+
|
|
673
|
+
Links the router never takes, whatever the attributes: with a modifier key or another mouse button, `target` other than `_self`, `download`, `rel="external"`, another origin or protocol (`mailto:`, `tel:`), a file (`.pdf`, `.zip`, images, video...), a `#hash` of the page you are on (the browser scrolls), a click a handler already `preventDefault()`ed, and anything `options.prevent(link, event)` returns true for. A form only with `data-umber-router-form` (never a dialog form, one with another `target`, one to another site, or `text/plain`).
|
|
640
674
|
|
|
641
675
|
### Presets
|
|
642
676
|
|
|
@@ -648,13 +682,14 @@ Links the router never takes, whatever the attributes: with a modifier key or an
|
|
|
648
682
|
| `zoom` | The old page sinks back (scales down a little) and fades; the new one settles in from a little larger. | `duration` 0.5 / 0.7, `ease` |
|
|
649
683
|
| `curtain` | A panel rises over the page, the new page comes in under it, the panel goes on up (back: down). | `color` #111, `duration` 0.65, `ease` |
|
|
650
684
|
| `wipe` | The same panel, wiped in from the left and out to the right (back: mirrored). | `color` #111, `duration` 0.65, `ease` |
|
|
651
|
-
| `cover` | A full-screen shader drawn by Umber: your `shader` (a `
|
|
685
|
+
| `cover` | A full-screen shader drawn by Umber: your `shader` (a `umber.shader()` with a `uCover` uniform, 0 page, 1 covered; `uOrigin` and `uDirection` too if it declares them) or a disc of `color` that grows from the click and shrinks back into it. Without GL: the panel fades. | `shader`, `color` #111, `duration` 0.8, `ease` (any Umber ease), `above` |
|
|
686
|
+
| `native` | The browser's own View Transition (`document.startViewTransition`): a cross-fade of the whole page by default, anything you write with `::view-transition-*` CSS and `view-transition-name`. Where the browser has none: `fade`. Umber's canvas is part of the browser's pictures; an element with a `view-transition-name` shows its DOM for the change. | your CSS |
|
|
652
687
|
| `dissolve` | A full-screen shader: the page dissolves into `color` in soft noise, then the new page out of it (the edge runs down the screen; back: up). Without GL: the panel fades. | `color` #111, `duration` 0.8, `ease`, `above` |
|
|
653
688
|
|
|
654
|
-
Every preset is a few lines of Web Animations on the containers or one panel, so nothing in the page needs a class. Under `prefers-reduced-motion` every preset is a 0.2 s cross-fade of the pages: no movement, no panel (your own transitions get `reducedMotion` and decide). A `data-
|
|
689
|
+
Every preset is a few lines of Web Animations on the containers or one panel, so nothing in the page needs a class. They run on Umber's clock, as the GL ones do (`cover`, `dissolve`, `umber.leave()`, a flying `data-umber-id` image) and the scroll module: a site that drives Umber from its own loop (`createUmber({ loop: false })`, `umber.render(t)`) drives them too, and a DOM fade and a GL wipe never drift apart. Under `prefers-reduced-motion` every preset is a 0.2 s cross-fade of the pages (0.1 s out, 0.1 s in): no movement, no panel (your own transitions get `reducedMotion` and decide). A back or forward the browser animated itself (a swipe on iOS Safari or Chrome on Android) swaps at once, so the change never plays twice. A `data-umber-id` image flies between the pages with each of them. The `cover` shader is the same kind as the handoff module's cover, so one shader serves both:
|
|
655
690
|
|
|
656
691
|
```js
|
|
657
|
-
|
|
692
|
+
umber.shader("ink", {
|
|
658
693
|
animate: false,
|
|
659
694
|
uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 },
|
|
660
695
|
fragment: `
|
|
@@ -665,13 +700,13 @@ gl.shader("ink", {
|
|
|
665
700
|
});
|
|
666
701
|
```
|
|
667
702
|
|
|
668
|
-
`cover` and `dissolve` are drawn on Umber's canvas: an element above the canvas (`data-
|
|
703
|
+
`cover` and `dissolve` are drawn on Umber's canvas: an element above the canvas (`data-umber="above"`, a fixed nav with a higher `z-index`) stays above them. With `above` (`data-umber-transition-above` on the link, or `above: true`) the canvas is lifted over everything for the transition, so they cover the nav too; while it is lifted, the page's own GL images also draw over the nav. The panel presets (`curtain`, `wipe`) are DOM and cover everything.
|
|
669
704
|
|
|
670
705
|
### Your own transitions
|
|
671
706
|
|
|
672
707
|
```js
|
|
673
|
-
// Your own transition into every page named "work" (data-
|
|
674
|
-
|
|
708
|
+
// Your own transition into every page named "work" (data-umber-page="work").
|
|
709
|
+
umber.router.transition({
|
|
675
710
|
name: "into-work",
|
|
676
711
|
to: "work",
|
|
677
712
|
// The old page goes; Umber waits for the promise.
|
|
@@ -688,25 +723,25 @@ gl.router.transition({
|
|
|
688
723
|
});
|
|
689
724
|
|
|
690
725
|
// A preset with your options, for links in the case-study grid.
|
|
691
|
-
|
|
726
|
+
umber.router.transition({ preset: "cover", links: ".case a", shader: "ink", duration: 0.8 });
|
|
692
727
|
|
|
693
728
|
// Every page change: analytics, your own components.
|
|
694
|
-
|
|
729
|
+
umber.router.on("after", ({ next }) => {
|
|
695
730
|
console.log("now on", next.page, next.url);
|
|
696
731
|
});
|
|
697
732
|
```
|
|
698
733
|
|
|
699
|
-
`
|
|
734
|
+
`umber.router.transition(def)` registers one and returns its remover. Every step (and every hook) may return what the change waits for, by one rule: a promise or any thenable (followed once), an `async` function, a GSAP tween or timeline (done once it has finished or was killed; a `gsap.set()` is done at once, also with GSAP 3.12, whose `then()` never resolves for one), a Web Animation (its `finished`; cancelled counts as done), or a list of these. Anything else is done at once. A step that takes longer than `timeout` fails the change, and the warning names it: `leave of transition 'into-work' took over 6000 ms`, or `the "afterLeave" hooks took over 6000 ms`.
|
|
700
735
|
|
|
701
|
-
- **Steps**, in order: `beforeLeave`, `leave`, `afterLeave`, then the new page goes in, `beforeEnter`, `enter`, `afterEnter`. Without `sync` the old container is gone before the new one is in. With `sync: true` both are in the page together: the new one goes in first (its `beforeEnter`), then `leave` and `enter` run at once, and the old container goes when both are done. The old one is pinned where it shows (`position: fixed` at its place, also under a transformed parent), so the new page starts at the top and your CSS needs nothing.
|
|
702
|
-
- **`sync` and GL.** The new page is on top, for Umber's pictures too: Umber draws every GL element on one canvas above the page, so for the change the new container is lifted above the canvas (`data-
|
|
736
|
+
- **Steps**, in order: `beforeLeave`, `leave`, `afterLeave`, then the new page goes in, `beforeEnter`, `enter`, `afterEnter`. Without `sync` the old container is gone before the new one is in. The leave starts at the click, while the next page loads, so the page answers at once on any network: `next.container` and `next.document` are `null` until the page is in (the same `data` object gets them then). It waits for the next page instead when the transition depends on it (a `to` by page name, a `custom`, a `sync` or `native` one), with `wait: true` on a transition (a leave of your own that reads the next page), or with the `wait` option for all of them. A container's own `data-umber-transition` is known once a page of the site with one was fetched; before that, the first change to a page whose container names another transition undoes the leave that began and plays that one. With `sync: true` both are in the page together: the new one goes in first (its `beforeEnter`), then `leave` and `enter` run at once, and the old container goes when both are done. The old one is pinned where it shows (`position: fixed` at its place, also under a transformed parent), so the new page starts at the top and your CSS needs nothing.
|
|
737
|
+
- **`sync` and GL.** The new page is on top, for Umber's pictures too: Umber draws every GL element on one canvas above the page, so for the change the new container is lifted above the canvas (`data-umber="above"`: its text over the old page's GL pictures, its own seen through it) or, when it has a background of its own, cuts the GL under it (`data-umber-occlude`). Both come off when the old page is gone. Its pictures start loading as it goes in, also while it is still off screen to the side.
|
|
703
738
|
- **`beforeEnter`** runs right as the new container is in the page, before its scripts run and before Webflow starts again: set the new page's first frame there (hidden, moved), so nothing flashes.
|
|
704
739
|
- **`once`**: the first page load (an intro). It goes to the best match that has one; `from` never matches then. Plays wait for it, for `timeout` at most: an intro that never ends is ended by the router, which says so (`once of transition 'intro' took over 6000 ms`). A transition with only `once` (no other step, no preset) is for that and never takes a page change.
|
|
705
740
|
- **GSAP**: a step may return a timeline or a tween (`leave: ({ current }) => gsap.to(current.container, { opacity: 0 })`, `beforeEnter: ({ next }) => gsap.set(...)`); the rule above says when it is done.
|
|
706
|
-
- **What each step gets**: `{ current, next, trigger, direction, origin, reducedMotion, transition }`. `current` and `next` are `{ container, page, url, document? }` (`next.document` is the parsed next page); `trigger` is the link clicked, `"popstate"` (back / forward), `"load"` (once) or go()'s trigger; `direction` is `"forward"` or `"back"`; `origin` is where the click was (viewport px; `null` from the keyboard or history).
|
|
741
|
+
- **What each step gets**: `{ current, next, trigger, direction, origin, reducedMotion, keyboard, transition }`. `current` and `next` are `{ container, page, url, document? }` (`next.document` is the parsed next page); `trigger` is the link clicked, `"popstate"` (back / forward), `"load"` (once) or go()'s trigger; `direction` is `"forward"` or `"back"`; `origin` is where the click was (viewport px; `null` from the keyboard or history).
|
|
707
742
|
- **`preset`** starts from a preset: its steps and your options (`duration`, `ease`, `color`, `shader`); your own steps replace its.
|
|
708
743
|
|
|
709
|
-
**Which one runs**, for each page change: the link's `data-
|
|
744
|
+
**Which one runs**, for each page change: the link's `data-umber-transition` (or `go(url, { transition })`); else the most specific registered transition whose conditions all hold; else the next page's container's `data-umber-transition`; else the wrapper's; else `options.transition`. The conditions:
|
|
710
745
|
|
|
711
746
|
| Condition | Matches | Weight |
|
|
712
747
|
|---|---|---|
|
|
@@ -715,40 +750,40 @@ gl.router.on("after", ({ next }) => {
|
|
|
715
750
|
| `links` | the link clicked: a selector (`".case a"`) or a function of the link | 4 |
|
|
716
751
|
| `custom` | a function of the change's data | 8 |
|
|
717
752
|
|
|
718
|
-
The highest total wins (`from` + `to` is 3, more than `to` alone); a tie goes to the one registered last. A transition with no condition matches every change: the site's default. `from` and `to` take a page name (`"work"`), a path (`"/work/*"`, `*` is anything; `"/work/dunes"`), a RegExp tested on the path, a function of `{ page, url, container }`, or a list of these. A container's `data-
|
|
753
|
+
The highest total wins (`from` + `to` is 3, more than `to` alone); a tie goes to the one registered last. A transition with no condition matches every change: the site's default. `from` and `to` take a page name (`"work"`), a path (`"/work/*"`, `*` is anything; `"/work/dunes"`), a RegExp tested on the path, a function of `{ page, url, container }`, or a list of these. A container's `data-umber-transition` counts as a `to` (2): a registered `to` for that page wins.
|
|
719
754
|
|
|
720
755
|
### Hooks for every page change
|
|
721
756
|
|
|
722
757
|
```js
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
758
|
+
umber.router.on("before", (d) => {}); // the click: the next page is not fetched yet (d.next.container is null)
|
|
759
|
+
umber.router.on("beforeLeave", (d) => {}); // each step of the transition has hooks of its name, run with it:
|
|
760
|
+
umber.router.on("leave", (d) => {}); // beforeLeave, leave, afterLeave, beforeEnter, enter, afterEnter
|
|
761
|
+
umber.router.on("afterLeave", (d) => {});
|
|
762
|
+
umber.router.on("beforeEnter", (d) => {}); // the new container is in, its scripts have not run
|
|
763
|
+
umber.router.on("enter", (d) => {});
|
|
764
|
+
umber.router.on("afterEnter", (d) => {});
|
|
765
|
+
umber.router.on("after", (d) => {}); // all done: the new page is in, measured, its transition finished
|
|
766
|
+
umber.router.on("error", ({ error, url }) => {}); // the router gave up: url loads in full now
|
|
732
767
|
```
|
|
733
768
|
|
|
734
|
-
Every hook but `after` may return what the change waits for (the rule above). Each `on()` returns its remover. An `after` hook that throws is logged; the page is in already.
|
|
769
|
+
Every hook but `after` may return what the change waits for (the rule above). Each `on()` returns its remover. Options: `umber.router.on("after", fn, { once: true })` runs once; `{ order: -1 }` starts before the hooks of order 0 of that moment (lower first, 0 by default; a tie keeps the order they were added in). An `after` hook that throws is logged; the page is in already.
|
|
735
770
|
|
|
736
771
|
### Per-page code: views (init and destroy)
|
|
737
772
|
|
|
738
|
-
`
|
|
773
|
+
`umber.router.view(page, { beforeEnter, afterEnter, beforeLeave, afterLeave })` is one page's own code, for its `data-umber-page`: set it up as the page comes in (the first load too, as Barba's views do), take it down as it goes. It returns its remover. The pattern for GSAP ScrollTrigger, `gsap.context()` and Umber's `umber.scope()`: make everything of the page inside them on enter, revert them on leave, refresh once the page is in.
|
|
739
774
|
|
|
740
775
|
```js
|
|
741
776
|
gsap.registerPlugin(ScrollTrigger);
|
|
742
|
-
const pages = {}; // the page shown: its gsap.context and
|
|
777
|
+
const pages = {}; // the page shown: its gsap.context and umber.scope
|
|
743
778
|
|
|
744
779
|
function enter(name, setup) {
|
|
745
|
-
|
|
780
|
+
umber.router.view(name, {
|
|
746
781
|
// The page is in and measured (the first load too): make its ScrollTriggers, pins, GL views.
|
|
747
782
|
afterEnter({ next }) {
|
|
748
783
|
const root = next.container;
|
|
749
784
|
let ctx;
|
|
750
|
-
//
|
|
751
|
-
const scope =
|
|
785
|
+
// umber.scope: what Umber makes in setup (umber.attach views, umber.add planes); gsap.context: its tweens and ScrollTriggers.
|
|
786
|
+
const scope = umber.scope(() => (ctx = gsap.context(() => setup(root), root)), root);
|
|
752
787
|
pages[name] = { ctx, scope };
|
|
753
788
|
ScrollTrigger.refresh(); // measure with the new page (pins, starts)
|
|
754
789
|
},
|
|
@@ -776,47 +811,48 @@ enter("work", (root) => {
|
|
|
776
811
|
**Analytics.** Send the page view in `after`, once the new title is set. With GA4 (`gtag.js`), turn off Enhanced measurement's "Page changes based on browser history events" in the data stream (it would count the page at `pushState`, with the old title, and twice with this):
|
|
777
812
|
|
|
778
813
|
```js
|
|
779
|
-
|
|
814
|
+
umber.router.on("after", ({ next }) => {
|
|
780
815
|
gtag("event", "page_view", { page_location: next.url, page_title: document.title });
|
|
781
816
|
});
|
|
782
817
|
```
|
|
783
818
|
|
|
784
819
|
### What a page change does
|
|
785
820
|
|
|
786
|
-
1. **The click.** `<html>` gets `data-
|
|
787
|
-
2. **The fetch.** Often done already: the router fetches a page as the pointer rests on its link (65 ms), a touch starts or it gets focus (`prefetch: "hover"`, the default), and with `prefetch: "viewport"` also when a link scrolls into view and the browser is idle (
|
|
788
|
-
3. **The
|
|
789
|
-
4. **
|
|
790
|
-
5. **Scroll**: to the top, to the `#hash` (the element with that id; its `scroll-margin-top` and `data-
|
|
791
|
-
6. **Scripts**: every `<script>` in the new container runs, in page order (an external one is waited for, 3 s at most, unless `async`). Outside the container (`<head>`, the end of `<body>`), only a script the page you came from did not have: a file loads once per visit, never twice (jQuery, `webflow.js`, `umber.js`), and a page's own inline code runs again each time you come back to it from a page without it. JSON-LD and other non-script types never run; `data-
|
|
821
|
+
1. **The click.** `<html>` gets `data-umber-router-busy` and `aria-busy="true"` in the click itself, before anything else (and `umber.router.busy` is true), until the change is done. The leave starts in that same task, before the next frame, while the next page loads (see Steps), and Umber's `umber.transition()` with it: plays wait, every plane is measured every frame, a `data-umber-id` image freezes; the scroll module is stopped. The address stays this page's until the next page is in. With `wait` the page stays as it is while it loads. A loading cue in CSS: `html[data-umber-router-busy] { cursor: progress; }`, or a bar that shows only when it takes a while: `html[data-umber-router-busy] .loader { opacity: 1; transition: opacity 0.2s 0.3s; }`.
|
|
822
|
+
2. **The fetch.** Often done already: the router fetches a page as the pointer rests on its link (65 ms), the main button goes down on it (the click comes at its release), a touch starts or it gets focus (`prefetch: "hover"`, the default), and with `prefetch: "viewport"` also when a link scrolls into view and the browser is idle (four requests at a time, at most as many pages per page as `cache` keeps). Nothing is fetched ahead with Save-Data or on a 2G connection. A page fetched on hover, by `umber.router.prefetch()` or by the click gets its GL ready too (`umber.preload()`): its images decoded and on the GPU, its programs compiled, so they draw from their first frame in the page. Never ahead, by one rule (a GET must not act; Turbo's prefetch uses the same markers): the page shown, a link marked as an action (`data-method` other than get, `data-confirm`, `data-remote`), `data-umber-router-prefetch="false"` on it or a parent, a URL with a `?query` (`?action=logout`, `?add-to-cart=12`) or a sign-out path; those are fetched on click only. The last 10 pages stay in memory (`cache`); a page sent with `Cache-Control: no-store` is not kept. A click aborts other requests still running. Only an HTML page of this site counts: a redirect to another site, a download, a 204 or anything not HTML is the browser's (step 9).
|
|
823
|
+
3. **The page is in.** The URL goes into history (`pushState`, after a redirect the page's real URL; the page you leave keeps its scroll in its entry, sideways and its `data-umber-router-scroll` elements too). Umber's `umber.transition()` gets the next page.
|
|
824
|
+
4. **The leave** ends (or runs now, when it waited), then the swap, by one rule for everything outside the container: what a page's own HTML has is that page's, and is replaced by what the next page's HTML has; anything a script added (a font loader's stylesheet, `has-umber`, a menu's class, Umber's own) stays. So: every `<head>` element but scripts (title, meta, links, `<base>`...) is matched by its markup: the next page's go in, the old page's own that it lacks go, and an element the next page puts in the same place (one description, one canonical) replaces the old one. Stylesheets follow the same rule, timed: the next page's were fetched while the old page left, they go in now and the new container waits until they have loaded (3 s at most), so it never shows unstyled; the old page's own go once it is gone. `<html>` and `<body>` attributes and classes (`lang`, Webflow's `data-wf-page`, `data-umber-scroll`, a theme's `data-*`) are merged three ways: what changes between the two pages' HTML is applied, what both have is left as scripts made it (a `no-js` class a script turned into `js` stays `js`). The first page's own HTML is fetched once, at the first change (from the cache mostly; it is also what "back" to it shows); until it is in, nothing of the first page is removed but what the next page replaces. Fonts the new page starts using are waited for (1 s at most).
|
|
825
|
+
5. **Scroll**: to the top, to the `#hash` (the element with that id; its `scroll-margin-top` and `data-umber-scroll-offset` count), or for back / forward to where that entry was.
|
|
826
|
+
6. **Scripts**: every `<script>` in the new container runs, in page order (an external one is waited for, 3 s at most, unless `async`). Outside the container (`<head>`, the end of `<body>`), only a script the page you came from did not have: a file loads once per visit, never twice (jQuery, `webflow.js`, `umber.js`), and a page's own inline code runs again each time you come back to it from a page without it. JSON-LD and other non-script types never run; `data-umber="skip"` opts one out. One rule for a classic script this document ran before (inline code, or a file in the container, as when you come back to a page): it runs inside `{ }`, so a top-level `const` / `let` / `class` does not throw "already declared" (its names are then its own: read shared values from `window`), and a custom element it defines again keeps its first definition. A file is read for that from the HTTP cache (with its `integrity`) and runs inline, so `document.currentScript.src` is empty in that run; a file the browser cannot read that way (no CORS) goes in as it is. A first run is exactly the page's. Modules are the browser's: a module file runs once a visit.
|
|
792
827
|
7. **Webflow**, where `window.Webflow` is: `Webflow.destroy()`, `Webflow.ready()`, `Webflow.require("ix2").init()` and a `readystatechange` event, so interactions, forms and tabs start on the new page; links outside the container get `w--current` (and every site gets `aria-current="page"` on them).
|
|
793
|
-
8. **Enter**, then the new title is **announced** in a polite live region. For a visitor who navigates by keys (a keyboard, or a screen reader activating the link), **focus** moves to the new container's `<h1>` (`focus` option; without one, the container itself), without scrolling (it is focusable only until focus moves on), as a full page load would put them at the start of the page. After a mouse, touch or pen click, or `
|
|
794
|
-
9. **After**: `
|
|
828
|
+
8. **Enter**, then the new title is **announced** in a polite live region. For a visitor who navigates by keys (a keyboard, or a screen reader activating the link), **focus** moves to the new container's `<h1>` (`focus` option; without one, the container itself), without scrolling (it is focusable only until focus moves on), as a full page load would put them at the start of the page. After a mouse, touch or pen click, or `umber.router.go()` on its own, focus stays where it was: no focus ring appears that the visitor didn't ask for (nor in a video recorded of the site). `data.keyboard` tells a transition which it was.
|
|
829
|
+
9. **After**: `umber.transition()` ends (plays start, the flying image lands; a change longer than 7 s ends it then and holds plays on until the end), the scroll module is measured again and starts, `after` hooks run, `go()` resolves.
|
|
795
830
|
|
|
796
831
|
A link to the page shown (a logo) scrolls back to the top. Back and forward between `#hash` entries of one page land where each was, else at the target.
|
|
797
832
|
|
|
798
833
|
Back and forward run the same with `direction: "back"` / `"forward"`. The router sets `history.scrollRestoration` to `"manual"` while the page lives (it restores scroll itself) and back to `"auto"` when the page is hidden, so a reload or a later visit gets the browser's own. It adds no `unload` listener, so pages stay in the back / forward cache.
|
|
799
834
|
|
|
800
|
-
### On a
|
|
835
|
+
### On a site that isn't licensed
|
|
801
836
|
|
|
802
|
-
The router is part of the Umber licence (no extra cost): on a
|
|
837
|
+
The router is part of the Umber licence (no extra cost): on a site without a key or not yet approved at occluze.com, links and back / forward work the way the browser does without a router, and so does every link before the answer comes in (asked once per page, `umber.licensed()`; the browser keeps a yes for about a week). `localhost`, `*.localhost`, `*.test` and private IP addresses always work.
|
|
803
838
|
|
|
804
839
|
### When something goes wrong: a full page load
|
|
805
840
|
|
|
806
|
-
Any failure loads the URL the way the browser would without a router, with a warning: an answer that is not OK (404, 500), not HTML, a download or a 204, a redirect to another site, a page with no `data-
|
|
841
|
+
Any failure loads the URL the way the browser would without a router, with a warning: an answer that is not OK (404, 500), not HTML, a download or a 204, a redirect to another site, a page with no `data-umber="container"`, changed `data-umber-router-track` elements (a new build), a step or hook that throws, a fetch or step that takes longer than `timeout` (6000 ms), or `router-swap.js` that cannot load. The `error` hooks hear it first. A failure before the next page is in leaves the page as it was: a preset's leave is undone (a download or a 204 keeps you there, and the router keeps working; undo a leave of your own in an `error` hook). One during the swap loads the page in full. One page change runs at a time: a click, back or forward before the next page is in takes the change over (the leave running goes on, and the page that goes in is the last one asked for, with no history entry for the one passed over); one after the next page is in waits and runs after it (its page is fetched at once), and only the last one waits. A page restored from the back / forward cache in the middle of a change reloads.
|
|
807
842
|
|
|
808
843
|
### The API
|
|
809
844
|
|
|
810
845
|
| | |
|
|
811
846
|
|---|---|
|
|
812
|
-
| `
|
|
813
|
-
| `
|
|
814
|
-
| `
|
|
815
|
-
| `
|
|
816
|
-
| `
|
|
817
|
-
| `
|
|
818
|
-
| `
|
|
819
|
-
| `
|
|
847
|
+
| `umber.router.go(url, { transition?, trigger?, history? })` | Change page from code (`history: "replace"`: in place of the entry shown). Resolves once the new page is in and its transition finished; rejects (after starting a full load) when the router can't. A URL that is not http(s) (`javascript:`, `data:`) is rejected and never followed. A link to the page shown resolves at once. |
|
|
848
|
+
| `umber.router.prefetch(url)` | Fetch a page ahead into the cache, its GL ready too. Never rejects. |
|
|
849
|
+
| `umber.router.cache.clear()`, `.delete(url)`, `.has(url)` | The pages kept in memory: forget them after a sign-in or an edit made in the page, so the next visit fetches them again. |
|
|
850
|
+
| `umber.router.transition(def)` | Register a transition; returns its remover. |
|
|
851
|
+
| `umber.router.on(name, fn, { once?, order? })` | A hook (`before`, `beforeLeave`, `leave`, `afterLeave`, `beforeEnter`, `enter`, `afterEnter`, `after`, `error`); returns its remover. |
|
|
852
|
+
| `umber.router.view(page, { beforeEnter, afterEnter, beforeLeave, afterLeave })` | One page's set-up and take-down (its `data-umber-page`), entered on the first load too; returns its remover. |
|
|
853
|
+
| `umber.router.busy` | `true` while a page change runs. |
|
|
854
|
+
| `umber.router.url`, `umber.router.page` | The page shown: its URL (no `#hash`) and its `data-umber-page`. |
|
|
855
|
+
| `umber.router.options` | The options below, live. |
|
|
820
856
|
|
|
821
857
|
Also at `window.__umber.engine.router`, for tools that drive the page (a screen recorder moves between pages with `go()`).
|
|
822
858
|
|
|
@@ -832,32 +868,35 @@ Also at `window.__umber.engine.router`, for tools that drive the page (a screen
|
|
|
832
868
|
| `scripts` | `true` | Run the new page's scripts. |
|
|
833
869
|
| `head` | `true` | Title, meta, stylesheets, `<html>` and `<body>` classes and attributes. |
|
|
834
870
|
| `webflow` | `true` | Start Webflow again after each swap. |
|
|
835
|
-
| `prevent` | `null` | `(link, event) => boolean`: true leaves the link to the browser. |
|
|
871
|
+
| `prevent` | `null` | `(link, event) => boolean`: true leaves the link (or form) to the browser. |
|
|
872
|
+
| `wait` | `false` | Every transition leaves only once the next page is in (as `wait: true` on a transition). |
|
|
873
|
+
| `headers` | `{}` | Headers sent with every page the router fetches, as `{ "X-Requested-With": "umber" }`, so a server can answer with less. |
|
|
836
874
|
|
|
837
875
|
### With Umber
|
|
838
876
|
|
|
839
|
-
- **Plays and planes.** Each change runs inside `
|
|
840
|
-
- **Flying images.** Give the image the same `data-
|
|
841
|
-
- **`
|
|
842
|
-
- **
|
|
877
|
+
- **Plays and planes.** Each change runs inside `umber.transition()`, so you need none of the recipe lines of the "Any router" section. The new container's GL elements are made as it arrives (Umber sees it in the DOM) and drawn where their elements are while a container moves; their reveals start when the change ends.
|
|
878
|
+
- **Flying images.** Give the image the same `data-umber-id` on both pages, inside the container. Without `sync` the old page is gone before the new one is in, so the image flies to its new place on the first screen as the new page comes in. With `sync: true` the old page is pinned out of the flow, so the new one starts on the first screen too.
|
|
879
|
+
- **`umber.leave()`** works as with any router: the old page's GL is copied at the click and drawn over the new page by your GLSL.
|
|
880
|
+
- **One clock.** The presets, the steps' timeouts, the GL transitions and the scroll module all run on Umber's frame time. With Umber driven from your own loop at half speed, a `fade` takes twice as long, as `cover` and `umber.scroll.scrollTo()` do. When Umber draws no frames (a hidden tab), wall time counts, so a change still ends. `umber.loop.pause()` holds a change where it is, its preset animations too, until `umber.loop.play()`; the router's frame callback is named `router` in `umber.loop.profile()`.
|
|
881
|
+
- **Smooth scroll.** Umber's scroll module pairs by itself (see the top of this page). A site that runs its own Lenis instead stops and starts it in hooks: `umber.router.on("leave", () => lenis.stop())`, `umber.router.on("after", () => { lenis.resize(); lenis.start(); })`.
|
|
843
882
|
|
|
844
883
|
### Coming from Barba
|
|
845
884
|
|
|
846
885
|
| Barba | Umber's router |
|
|
847
886
|
|---|---|
|
|
848
|
-
| `data-barba="wrapper"`, `data-barba="container"` | `data-
|
|
849
|
-
| `data-barba-namespace="home"` | `data-
|
|
850
|
-
| `data-barba-prevent` | `data-
|
|
851
|
-
| `barba.init({ transitions: [a, b] })` | `
|
|
887
|
+
| `data-barba="wrapper"`, `data-barba="container"` | `data-umber="wrapper"`, `data-umber="container"` |
|
|
888
|
+
| `data-barba-namespace="home"` | `data-umber-page="home"` |
|
|
889
|
+
| `data-barba-prevent` | `data-umber="skip"` |
|
|
890
|
+
| `barba.init({ transitions: [a, b] })` | `umber.router.transition(a)`, `umber.router.transition(b)` |
|
|
852
891
|
| a rule's `namespace`, `route` or `custom` | `from` / `to` with a page name or a path, `custom` |
|
|
853
|
-
| `barba.hooks.after(fn)`, `barba.hooks.beforeEnter(fn)`... | `
|
|
854
|
-
| `views: [{ namespace: "home", beforeEnter, afterLeave }]` | `
|
|
855
|
-
| `barba.go(url)`, `barba.prefetch(url)` | `
|
|
892
|
+
| `barba.hooks.after(fn)`, `barba.hooks.beforeEnter(fn)`... | `umber.router.on("after", fn)`, `umber.router.on("beforeEnter", fn)`... |
|
|
893
|
+
| `views: [{ namespace: "home", beforeEnter, afterLeave }]` | `umber.router.view("home", { beforeEnter, afterLeave })` |
|
|
894
|
+
| `barba.go(url)`, `barba.prefetch(url)` | `umber.router.go(url)`, `umber.router.prefetch(url)` |
|
|
856
895
|
| `@barba/prefetch` | built in (`prefetch: "hover"` or `"viewport"`) |
|
|
857
896
|
|
|
858
|
-
|
|
897
|
+
In short: a page cache with hover prefetch, `history.scrollRestoration = "manual"` with positions kept per entry, head elements merged by their markup with stylesheets waited for, scripts re-activated by copying them, a full load when a `data-umber-router-track` asset changed, and per-page transitions and hooks on top. It uses the History API, not the Navigation API, which not every browser has yet.
|
|
859
898
|
|
|
860
|
-
Not included, on purpose:
|
|
899
|
+
Not included, on purpose: a plugin system and a logger, rule fields beyond the ones above, and code for old browsers (the router needs what Umber needs: `fetch`, `DOMParser`, Web Animations). Speculation Rules are not used: a page they prefetch goes to the browser's navigation cache, which `fetch()` can't read, so it would only help the full page loads the router falls back to.
|
|
861
900
|
|
|
862
901
|
Working pages: `examples/router/` (`index.html`, `dunes.html`, `about.html`, `site.js`): a transition of the site's own for one page with a flying image, `curtain` and `wipe` by attribute only, the `cover` with the page's own shader, `slide` from code, a page with its own stylesheet and script.
|
|
863
902
|
|
|
@@ -865,140 +904,169 @@ Working pages: `examples/router/` (`index.html`, `dunes.html`, `about.html`, `si
|
|
|
865
904
|
|
|
866
905
|
## Attributes (the DOM is the API)
|
|
867
906
|
|
|
868
|
-
|
|
907
|
+
**An element says what it is, how it behaves, and what it's set to.** What it is and how it behaves are words in one attribute, `data-umber`; what it's set to is an attribute of its own per setting:
|
|
908
|
+
|
|
909
|
+
```html
|
|
910
|
+
<section data-umber="image pin" data-umber-effect="dissolve" data-umber-dissolve-scale="6">
|
|
911
|
+
```
|
|
912
|
+
|
|
913
|
+
- **What it is** (a kind): one word, one per element. Two kinds on one element is a mistake.
|
|
914
|
+
- **How it behaves** (a behaviour): any number of words after it, or on their own (`data-umber="above"`).
|
|
915
|
+
- **What it's set to** (a setting): `data-umber-<setting>="value"`, one attribute each (`data-umber-effect`, `data-umber-<effect>-<option>`, `data-umber-src`...). A behaviour that needs a value is written as its setting instead, and only that way: `data-umber-pin="80px"`, `data-umber-inview="shown"`.
|
|
916
|
+
|
|
917
|
+
These are all the words. A new or niche feature, and an add-on, gets a setting, never a word. On `localhost` Umber warns about a word it doesn't know (and names the closest one), two kinds on one element, a word whose add-on isn't loaded, and a word said two ways.
|
|
918
|
+
|
|
919
|
+
| Word | Type | On | What it does | Needs |
|
|
920
|
+
|---|---|---|---|---|
|
|
921
|
+
| `image` | kind | a wrapper with an `<img>` inside, or the `<img>` itself | Draws the image as a plane. Webflow `srcset` works: Umber uses the candidate the browser picked. | |
|
|
922
|
+
| `video` | kind | a wrapper with a `<video>`, or the `<video>` | Draws the video. A frame is uploaded only when the video has a new one. Muted loop/autoplay videos pause while off screen and play again when back (`data-umber-video-autopause="false"` keeps them playing; videos with `controls` are never touched). | |
|
|
923
|
+
| `text` | kind | any text element | Paints the element's real text into a plane (see Planes: GL text). | |
|
|
924
|
+
| `shader` | kind | any box | With `data-umber-shader="name"`. A surface drawn fully by `umber.shader("name", {...})`. Its own background hides once painted. | |
|
|
925
|
+
| `layer` | kind | any box | With `data-umber-layer="name"`. Your own WebGL from `umber.layer("name", {...})`, on Umber's canvas (see three.js). | |
|
|
926
|
+
| `model` | kind | any box | With `data-umber-src="x.glb"`. A glTF model (Draco, KTX2, meshopt) fitted to the box, drawn by the three module (`modules/three.js`; see three.js). Options `data-umber-model-<option>` / `--umber-model-<option>`: `fit`, `fov`, `zoom`, `rotate`, `turn`, `spin`, `tilt`, `play`, `scrub`, `environment`, `scene`. | `three` |
|
|
927
|
+
| `group` | kind | any box with GL planes inside | Draws the GL planes inside it as one image, through its own `data-umber-effect` (Groups and passes). | |
|
|
928
|
+
| `container` | kind | the part of each page that changes | The router swaps it for the next page's (see Router). | `router` |
|
|
929
|
+
| `wrapper` | kind | an element around the container | The container is looked for inside it; its `data-umber-transition` is the site's default (see Router). | `router` |
|
|
930
|
+
| `scroller` | kind | the element that scrolls instead of the window | Umber follows its scroll instead of the window's; the scroll module smooths it (see Scroll). | |
|
|
931
|
+
| `above` | behaviour | any element | Keeps it above the canvas (`position: relative; z-index: 2`, zero specificity: your own position and z-index win). | |
|
|
932
|
+
| `pin` | behaviour | an element in a taller parent | Sticks while its parent scrolls past; `data-umber-pin="80px"` sticks 80 px down (see Scroll effects). | `scrollfx` |
|
|
933
|
+
| `horizontal` | behaviour | a section whose first child is a wide track | The track slides sideways as the page scrolls down (see Scroll effects). | `scrollfx` |
|
|
934
|
+
| `inview` | behaviour | any element | The class `is-inview` while it is on screen; `data-umber-inview="shown"` names the class (see Scroll effects). | `scrollfx` |
|
|
935
|
+
| `skip` | behaviour | a link or any parent; a `<script>` | The router leaves that link to the browser, or never runs that script (see Router). | `router` |
|
|
936
|
+
| `nested` | behaviour | an element with `overflow: auto` | It scrolls smoothly by itself (see Scroll). | `scroll` |
|
|
937
|
+
|
|
938
|
+
Everything an attribute does, code can do too. Effect options also work as CSS custom properties, which Webflow can set per breakpoint on a class. They are read when the plane is built and again on a window resize or `umber.invalidate(el)`; `plane.set()` changes them from code.
|
|
939
|
+
|
|
940
|
+
The settings:
|
|
869
941
|
|
|
870
942
|
| Attribute | On | What it does |
|
|
871
943
|
|---|---|---|
|
|
872
|
-
| `data-
|
|
873
|
-
| `data-
|
|
874
|
-
| `data-
|
|
875
|
-
| `data-
|
|
876
|
-
| `data-
|
|
877
|
-
| `data-
|
|
878
|
-
| `data-
|
|
879
|
-
| `data-
|
|
880
|
-
| `data-
|
|
881
|
-
| `data-
|
|
882
|
-
| `data-
|
|
883
|
-
| `data-
|
|
884
|
-
| `data-
|
|
885
|
-
| `data-
|
|
886
|
-
| `data-
|
|
887
|
-
| `data-
|
|
888
|
-
| `data-
|
|
889
|
-
| `data-
|
|
890
|
-
| `data-
|
|
891
|
-
| `data-
|
|
892
|
-
| `data-
|
|
893
|
-
| `data-
|
|
894
|
-
| `data-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
| `data-gl-media="(min-width: 900px)"` | `<body>` | Effects only where this CSS media query matches, read when the page loads; elsewhere the plain page shows. Any size or device: `(min-width: 600px)` turns phones off, `(min-width: 1024px)` phones and most tablets, `(hover: hover)` every touch screen. `createGL({ media })` wins over it. |
|
|
898
|
-
| `data-gl-disable` | `<body>` | GL off from this page on, for the rest of the visit (a router's later pages keep their DOM). |
|
|
899
|
-
| `data-gl-scrub` (+ `-start`, `-end`, `-track`, `-smooth`, ...) | a `<video>` plane | Scroll-scrubbed video. Needs the scrub module (see Scrub). |
|
|
900
|
-
|
|
901
|
-
**Written by Umber** (style them, never set them): `html.has-gl`, `data-gl-status="loading | ready | error"`, `data-gl-media` (the `<img>` / `<video>` a plane mirrors), `data-gl-play` (has a playing effect: hidden while GL loads), `data-gl-morphing`, `data-gl-canvas` on the canvas (with `data-engine="umber <version>"`; GL text's hidden paint canvases in the host carry `data-gl-canvas="text"`), and `data-gl-view="loading | ready | off | error | lost"` on `gl.attach()` / `gl.view()` elements. The debug module's panel and overlay carry `data-umber-hud` and `data-umber-debug`.
|
|
944
|
+
| `data-umber-pass="a b"` | `<body>`, `<html>` or a group | Effects run over the whole GL frame, or over the group, in order. Per effect also `-blend`, `-opacity`, `-scale` (Groups and passes). |
|
|
945
|
+
| `data-umber-shader-<option>` / `data-umber-layer-<option>` | a shader or layer plane | One option of its `umber.shader()` / `umber.layer()`. Also `--umber-shader-<option>` / `--umber-layer-<option>` in CSS. A shader's number, boolean, array, colour and image-path options become uniforms `u` + Option (`data-umber-shader-speed` sets `uSpeed`); a layer reads them in `ctx.options`. |
|
|
946
|
+
| `data-umber-effect="a b"` | a plane | Effects from `umber.effect()`, applied in order. |
|
|
947
|
+
| `data-umber-<effect>-<option>="value"` | a plane | One effect option. Also `--umber-<effect>-<option>` in CSS. Numbers, booleans, arrays, CSS colours (a `vec4`) and image paths (a string with a `/`: a `sampler2D`) become uniforms: `data-umber-dissolve-scale="5"` sets `uDissolveScale`. |
|
|
948
|
+
| `data-umber-<effect>-trigger` | a plane | For effects with `play`: `auto` (default: on screen at once, further down on scroll), `scroll`, `load`, `manual` (`umber.plane(el)?.play()`), `hover` (0 to 1 while the pointer is over it or its closest link or button, back on leave). |
|
|
949
|
+
| `data-umber-<effect>-delay` / `-duration` / `-ease` / `-start` | a plane | The play's timing. `start` is `"<element edge> <screen line>"`, default `"top 90%"` (no offsets). |
|
|
950
|
+
| `data-umber-<effect>-repeat` | a plane | `"reverse"`: plays back as the page goes back up past `start`, and again on the way down. `"true"`: set back unseen once off screen, and plays each time it scrolls in. Default: once. |
|
|
951
|
+
| `data-umber-src="url"` | an image plane | Another texture than the `<img>` (for example a larger file). Changing it, or the `<img>`'s `src` / `srcset` (a framework reusing the tag), keeps the old picture drawn until the new one is on the GPU: no flash of the DOM. An effect that reads `uSwap` blends them (see Effects). A `.ktx2` file (Basis Universal) is drawn compressed: see Planes. |
|
|
952
|
+
| `data-umber-swap-duration` / `-ease` | an image plane whose effect reads `uSwap` | How long the old picture takes to give way after a new `src` (seconds, default 0.8; ease default `umber`). Also `--umber-swap-*` in CSS. |
|
|
953
|
+
| `data-umber-placeholder="..."` | an image plane | A tiny blurred preview (about 50 characters, made with `umber.placeholder(src)`) shown under the `<img>` until its file has loaded. See "Getting ready ahead". |
|
|
954
|
+
| `data-umber-fit="cover \| contain \| fill"` | a plane | Overrides the element's `object-fit`. From CSS, GL follows `contain`; everything else (`cover`, the default `fill`, `none`, `scale-down`) draws as `cover`, so an `<img>` with no object-fit is cropped, not stretched. Only `data-umber-fit="fill"` stretches. `object-position` is read from CSS: %, keywords and lengths (`20px 10px`, `1rem 0`; a length resolves once the image has loaded). |
|
|
955
|
+
| `data-umber-order="2"` | a plane | Draw order (lower first). |
|
|
956
|
+
| `data-umber-instances="64"` | a plane | Drawn many times in one draw call: `"64"` copies, `"tiles 24x16"`, `"chars"` / `"words"` / `"lines"` (GL text), `"echo 6"` (a trail), `"points 20000"` (particles spread over it), `"ink 3000"` (particles where it has ink). Its effects get `instance` and the mode's inputs (see Instances). |
|
|
957
|
+
| `data-umber-clip="false"` | a plane | Draw it without its parents' clips (`overflow`, `clip-path`, CSS masks). Its own `clip-path` still cuts it. Parents' clips are followed by default (see Planes). |
|
|
958
|
+
| `data-umber-wrap="x \| y"` | a track holding planes (or a plane) | Its planes wrap around it: when something moves the track (a drag, a tween, a scroll-driven animation), each is drawn moved by whole track lengths (its `offsetWidth`, or `offsetHeight` for `y`) so the track's own place on the page stays filled, an endless gallery with no copies in the DOM. Cards at rest are drawn where their DOM is, so a track below the fold stays below it. The track must be at least one card longer than the screen; give it its trailing gap as padding so the spacing repeats. Its planes load their images at once, hide their DOM once their pixels are ready (GL draws them wherever they wrap to), report `inView`, `"enter"` and `"leave"` where they are drawn, and are measured wherever their DOM went (a drag or a tween moving the track is followed like any moved parent). Flat planes only (a turned one keeps its own place). |
|
|
959
|
+
| `data-umber-live` | a plane | Measure every frame while on screen. Rarely needed: CSS animations and transitions, scroll-driven animations and the Web Animations API are followed by themselves while they run, inline styles (GSAP, Webflow Interactions) by the DOM watch, and sticky, fixed and pinned parents are detected (not a fixed element inside a transformed parent, or a sticky one in a box that never scrolls: the scroll doesn't move those). Use it for an element your own `requestAnimationFrame` loop moves some other way, or a paused animation it scrubs. |
|
|
960
|
+
| `data-umber-id="hero"` | a plane | The same id on two pages: the image flies across on a page change. On the element you go to, `data-umber-morph-duration` (seconds, default 1) and `data-umber-morph-ease` (also `--umber-morph-*` in CSS) time the flight. If the element it lands in sits inside a box that paints an opaque background over the canvas (a fixed next container with a z-index above the canvas's), Umber warns at landing: the image would be hidden under it. The same when another box (a sibling section with a z-index and a background) lies over the spot it lands on: the flight ends hidden there. Fly to an element that shows, or raise the canvas. |
|
|
961
|
+
| `data-umber-host` | one element | Where the canvas goes (else Umber makes a fixed full-screen host). |
|
|
962
|
+
| `data-umber-devices="desktop"` | `<body>` or `<html>` | Effects only on desktops (hover, a fine pointer, at least 768px wide); phones and tablets show the plain page. Effects run on every device by default. Recommended when a page is heavy for phones. `createUmber({ devices })` wins over it. |
|
|
963
|
+
| `data-umber-media="(min-width: 900px)"` | `<body>` | Effects only where this CSS media query matches, read when the page loads; elsewhere the plain page shows. Any size or device: `(min-width: 600px)` turns phones off, `(min-width: 1024px)` phones and most tablets, `(hover: hover)` every touch screen. `createUmber({ media })` wins over it. |
|
|
964
|
+
| `data-umber-software` | `<body>` or `<html>` | Run GL where WebGL draws on the processor (no usable GPU). Normally the DOM shows there (`umber.reason` `"software"`). Same as `createUmber({ software: true })`. |
|
|
965
|
+
| `data-umber-disable` | `<body>` | GL off from this page on, for the rest of the visit (a router's later pages keep their DOM). |
|
|
966
|
+
| `data-umber-scrub` (+ `-start`, `-end`, `-track`, `-smooth`, ...) | a `<video>` plane | Scroll-scrubbed video. Needs the scrub module (see Scrub). |
|
|
967
|
+
|
|
968
|
+
**Written by Umber** (style them, never set them): `html.has-umber`, `data-umber-status="loading | ready | error"`, `data-umber-media` (the `<img>` / `<video>` a plane mirrors), `data-umber-play` (has a playing effect: hidden while GL loads; you may also write it yourself, see below), `data-umber-morphing`, `data-umber-canvas` on the canvas (with `data-engine="umber <version>"`; GL text's hidden paint canvases in the host carry `data-umber-canvas="text"`), and `data-umber-view="loading | ready | off | error | lost"` on `umber.attach()` / `umber.view()` elements. The debug module's panel and overlay carry `data-umber-hud` and `data-umber-overlay`.
|
|
902
969
|
|
|
903
970
|
**Layering.** The canvas sits **over** the page (z-index 1), with `pointer-events: none`, so every click still goes to the DOM. Its host is `<body>`'s first child, so the stacking rule is plain CSS:
|
|
904
971
|
|
|
905
|
-
- **A positioned element with `z-index: 1` or more and a background covers GL inside it.** It comes later in the page at the same or a higher z-index, so it paints over the canvas: the plane is `ready`, its DOM is hidden, and nothing shows. `
|
|
906
|
-
- **A router container made `position: fixed` or transformed during a swap** (a slide or cover transition) becomes its own stacking context; with a z-index it takes its content under or over the canvas for that moment. Give the container no z-index, or hand its planes back to the DOM for the transition (`
|
|
972
|
+
- **A positioned element with `z-index: 1` or more and a background covers GL inside it.** It comes later in the page at the same or a higher z-index, so it paints over the canvas: the plane is `ready`, its DOM is hidden, and nothing shows. `umber.inspect(el)` says so (`... covers Umber's canvas`), and Umber warns once on pages that load `chunks/shapes.js` (anything cut, turned or tilted). Fixes: drop that element's `z-index` (or make it `auto`), move its background to a sibling or a `::before` behind the content, or give the canvas a higher `createUmber({ zIndex })` and lift what must stay above it (navs, buttons) with `data-umber="above"` or a higher z-index.
|
|
973
|
+
- **A router container made `position: fixed` or transformed during a swap** (a slide or cover transition) becomes its own stacking context; with a z-index it takes its content under or over the canvas for that moment. Give the container no z-index, or hand its planes back to the DOM for the transition (`umber.planes(container).forEach((p) => p.destroy())`).
|
|
907
974
|
- **A flight lands where the DOM puts its target.** If that spot is under another section (positioned, z-index 1 or more, a background), the image flies in and then vanishes under it, as its DOM would. Umber warns once at landing and names the section.
|
|
908
|
-
- `data-
|
|
909
|
-
- Text or buttons over a GL image need `data-
|
|
910
|
-
- `data-
|
|
911
|
-
- Never put `data-
|
|
975
|
+
- `data-umber-clip="false"` only stops a parent from cutting the plane; it does not lift GL over a parent that paints over the canvas.
|
|
976
|
+
- Text or buttons over a GL image need `data-umber="above"`.
|
|
977
|
+
- `data-umber="above"` cannot escape a parent that is transformed, faded (opacity < 1) or filtered: the canvas then covers it. Animate the caption itself, or move it out of that wrapper. **Pinned sections** (GSAP ScrollTrigger `pin: true`, a sticky stack) are such a parent: the pin makes the section `position: fixed` and transforms it, so text inside it with `data-umber="above"` stays under the canvas. Give the pinned section itself `position: relative; z-index: 2` (above the canvas's 1; no background on it, or its GL is hidden) instead of lifting what is inside. Umber says so once, naming both elements, when it sees a GL element in such a section.
|
|
978
|
+
- Never put `data-umber="above"` on the element that holds the GL image: its background would cover the drawing.
|
|
912
979
|
- A fixed nav, menus and transition overlays need a z-index above 1 (for example 10).
|
|
913
|
-
- Prefer the canvas behind the page? `
|
|
980
|
+
- Prefer the canvas behind the page? `createUmber({ layer: "under" })`; then sections over GL images need a transparent background.
|
|
914
981
|
|
|
915
|
-
**Hide a playing element from the first paint.** Elements whose effect has `play` stay hidden while GL loads, so a reveal never flashes the plain image first. `
|
|
982
|
+
**Hide a playing element from the first paint.** Elements whose effect has `play` stay hidden while GL loads, so a reveal never flashes the plain image first. `createUmber()` marks the elements already on the page at once, and `umber.effect()` adds `data-umber-play` to the ones using a playing effect as it is defined; write `data-umber-play` in your HTML yourself too, so they stay hidden when the effect is defined later (an async import): GL leaves such an element undrawn until its effect is defined, 3 s at most. If GL is off or its picture is slow (3 s on screen; time the page itself keeps the element hidden, at `opacity: 0` or `visibility: hidden`, does not count), they show; a slow one keeps loading, and GL takes it over once its picture is on the GPU.
|
|
916
983
|
|
|
917
984
|
---
|
|
918
985
|
|
|
919
986
|
## Planes
|
|
920
987
|
|
|
921
|
-
A plane is the GPU copy of one `[data-
|
|
988
|
+
A plane is the GPU copy of one `[data-umber]` element. It follows the element's position, size, border-radius, object-fit (cover or contain; see `data-umber-fit`) and opacity (its own and its parents', up to the one that also holds Umber's canvas: a fade on `<body>` fades the canvas already), and it is cut by whatever cuts the element (below). Its own corners follow too, oval ones as well (`border-radius: 50%` on a box that is not square, `40px / 20px`), wherever the plane is drawn (a flight, a lift, a wrapped track, a group). Every rounded corner must have the same proportion across / down: corners of different shapes (one round, one oval) show its DOM, with a warning. The element stays the source of truth: change it with CSS, GSAP or Webflow Interactions and the plane follows. One exception: an `<img data-umber="image">` hides itself once GL draws it (`opacity: 0 !important`), so of the img's own opacity only an inline one counts (GSAP, Webflow Interactions and Motion set it inline). For a stylesheet fade (a transition, an `@keyframes`, a class), put the opacity on its parent, or wrap it: `<div data-umber="image"><img></div>`. A stylesheet opacity on the `<img data-umber="image">` itself prints one warning on localhost.
|
|
922
989
|
|
|
923
990
|
**What Umber reads, and when.** A scroll over a still layout reads no layout and no styles: each plane is moved by the scroll position alone. Umber measures a plane (its rect, and the styles of it and its parents) only when:
|
|
924
991
|
|
|
925
992
|
- it comes near the screen (a quarter screen ahead, above or below; sideways only once it reaches the screen), once;
|
|
926
993
|
- it or a parent gets a style or class change (a GSAP tween writes `style` every frame it runs). A change on `<html>` or `<body>` (a theme or state class) measures only the planes near the screen; Lenis's own `lenis-scrolling` / `lenis-smooth` classes measure nothing;
|
|
927
994
|
- a CSS transition or animation, or a Web Animation, moves it, while it runs; it is fixed or sticky (every frame near the screen); or a page swap just happened (1.5 s);
|
|
928
|
-
- the window resizes, a stylesheet or font arrives, or you call `
|
|
995
|
+
- the window resizes, a stylesheet or font arrives, or you call `umber.invalidate()`.
|
|
929
996
|
|
|
930
|
-
Elements added or removed without a `[data-
|
|
997
|
+
Elements added or removed without a `[data-umber]` in them (a news ticker, a chat, a counter) wake nothing: a still page stays at 0 frames a second. Far planes are measured when they come near, and when `<html>` itself changes size (the page grew) Umber's ResizeObserver measures again. A shift that doesn't change `<html>`'s size is not seen: an item pushed into a flex row, a list that adds one and drops one, or a page whose `<body>` or `<main>` is the scroller (`height: 100%`). Call `umber.invalidate()` after those. An `<img>` put into an image or video `[data-umber]` is still news (the plane is built again).
|
|
931
998
|
|
|
932
|
-
After a plane was restyled, one look at its opacity a few frames later catches a fade no DOM change reports; then nothing more. `
|
|
999
|
+
After a plane was restyled, one look at its opacity a few frames later catches a fade no DOM change reports; then nothing more. `umber.info.busy` names what keeps the loop running (`dom-watch:<section#hero>`: that element was restyled).
|
|
933
1000
|
|
|
934
1001
|
### What GL draws, and what cuts it
|
|
935
1002
|
|
|
936
|
-
- **The box GL draws** is the `<img>` / `<video>` itself. With `data-
|
|
1003
|
+
- **The box GL draws** is the `<img>` / `<video>` itself. With `data-umber` on a wrapper (a card) that holds the image, GL draws the image's own box, with the image's own corners and `object-fit` (cover or contain; see `data-umber-fit`): a hover zoom on the `<img>` shows in GL, and padding or a caption in the wrapper stays DOM. Text, shaders and layers draw the element's box.
|
|
937
1004
|
- **Parents cut it like the DOM does.** A parent with `overflow: hidden | clip | auto | scroll` (with its rounded corners), `contain: paint`, or a `clip-path` (on the element or any parent) cuts the GL image exactly where it cuts the DOM image: sliders, marquees, rounded cards, line masks, clip-path reveals. The browser's own rules hold: an `absolute` image escapes a static parent's overflow, a `fixed` one escapes everything but a transformed, filtered or `contain: paint` parent, and `clip-path` reaches every child.
|
|
938
1005
|
- **Drawable clip-paths:** `inset()`, `rect()`, `xywh()` (with `round`), `circle()`, `ellipse()`, `polygon()` (one per element, up to 8 points), on any reference box, animated by CSS, a class, GSAP or your own code. Corner radii may be elliptical (`50% / 20px`) when every corner has the same ratio.
|
|
939
1006
|
- **Cost:** straight clips (a slider, a mask, an `inset()` wipe, a rectangle `polygon()`) are a GPU scissor: free per pixel. Rounded and shaped ones are tested per pixel, only on those elements (at most 2 per element). A rounded card that hugs its image is drawn as the image's own corners, as before. A scroll reads nothing for them: clips are measured with their element and moved with the scroll.
|
|
940
1007
|
- **What falls back to the DOM** (the element shows its DOM image or text, with one `[umber]` warning that names the fix, and GL takes it back when the cause goes): `clip-path: path()`, `shape()`, `url()` or `min()` / `max()` / `clamp()` in a shape; a CSS `mask` / `mask-image` on the element or a parent; corners that mix radius ratios; more than 2 rounded or shaped clips on one element, a second polygon, or a nonzero polygon that crosses itself.
|
|
941
|
-
- **`data-
|
|
1008
|
+
- **`data-umber-clip="false"`** (or `umber.add(el, { clip: false })`) draws the element without its parents' clips and masks; its own `clip-path` (and a wrapper's overflow on its own `<img>`) still cut it.
|
|
942
1009
|
- A wrapper with `border-radius` but `overflow: visible` doesn't round its image in the DOM, so not in GL either: put `overflow: hidden` on it, or the radius on the `<img>`.
|
|
943
|
-
- **Opaque panels that slide over GL: `data-
|
|
1010
|
+
- **Opaque panels that slide over GL: `data-umber-occlude`.** Umber draws on one canvas (z-index 1). A panel positioned with a `z-index` of 1 or more and an opaque background paints over the canvas, so GL inside it is hidden (Umber warns). Stacked sticky sections and card decks need that z-index: raise the canvas above them with `createUmber({ zIndex })` (under a fixed header that must stay on top). On one canvas, the earlier panels' GL would now show through the later ones. Put `data-umber-occlude` on each panel that slides over others: every GL element it paints over in the DOM is cut by its box, with its corners. That is every one before it in the page, and every one after it that sits in a lower `z-index` (content scrolling under a sticky bar). Not one that sits higher, like a fixed header's GL logo. GL elements inside the panel are drawn as usual. A `data-umber="shader"` backdrop that holds the panel is cut by it.
|
|
944
1011
|
|
|
945
1012
|
```html
|
|
946
1013
|
<section class="panel" style="position: sticky; top: 0; z-index: 1; background: #111">...</section>
|
|
947
|
-
<section class="panel" data-
|
|
948
|
-
<script>Umber.
|
|
1014
|
+
<section class="panel" data-umber-occlude style="position: sticky; top: 0; z-index: 2; background: #111">...</section>
|
|
1015
|
+
<script>Umber.createUmber({ zIndex: 5 });</script> <!-- the canvas over the panels, under a z-index 10 header -->
|
|
949
1016
|
```
|
|
950
1017
|
|
|
951
|
-
- **`data-
|
|
1018
|
+
- **`data-umber-under="<selector>"`** on a GL element picks its panels instead (any order in the page); `data-umber-under="none"`: never cut. It is read when the element is measured: after changing it, call `umber.invalidate(el)`.
|
|
952
1019
|
- **Cost:** a panel that misses an element costs nothing. One that covers it hides it (not drawn). One that slides over one of its edges, full width, cuts the scissor (free). Otherwise it takes one of the element's 2 per-pixel clip slots. With both taken by rounded parents, a panel spanning it still cuts it straight (wrong only at its rounded corners); one that doesn't is not cut there, with one warning. A three.js layer is only cut straight.
|
|
953
|
-
- A still panel is measured again when the DOM changes (a style or class on it or a parent, GSAP; an element put in it, a dropdown; `aria-expanded`, `open`, `data-state` or `hidden` on it or next to it, a menu's button) and moved by the scroll: no reads while scrolling. Text changed in it (a counter, a clock) and restyles inside it are looked at a quarter second later. A `:hover`, `:focus-within` or `:checked` rule that opens it is caught by the pointer, focus and input events by it. A sticky or fixed one, or one with `data-
|
|
1020
|
+
- A still panel is measured again when the DOM changes (a style or class on it or a parent, GSAP; an element put in it, a dropdown; `aria-expanded`, `open`, `data-state` or `hidden` on it or next to it, a menu's button) and moved by the scroll: no reads while scrolling. Text changed in it (a counter, a clock) and restyles inside it are looked at a quarter second later. A `:hover`, `:focus-within` or `:checked` rule that opens it is caught by the pointer, focus and input events by it. A sticky or fixed one, or one with `data-umber-live`, is read once a frame (its rect) while the loop runs and an element it may cut is near the screen. A CSS animation or transition that moves or fades the panel is followed while it runs (the elements under it are not measured for it).
|
|
954
1021
|
- It needs an opaque background (a colour without transparency, or an image) and no fade: a see-through one cuts a hole where the page shows through it (one warning, still cut). It is its border box (`background-clip` and box shadows are not part of it), or its own `clip-path` when that is an `inset()`, `circle()` or `ellipse()`. What a parent's `overflow: hidden` hides of it cuts nothing (a closed mega menu in a header), and neither does a panel that is unseen: `visibility: hidden`, `opacity: 0`, or inside a closed `<details>` or `hidden="until-found"`.
|
|
955
1022
|
- Panels (like GL elements) are found in the page's own DOM: one inside a shadow root (a web component) is not.
|
|
956
|
-
- It brings in `chunks/shapes.js`. With the canvas under the page (`
|
|
1023
|
+
- It brings in `chunks/shapes.js`. With the canvas under the page (`createUmber({ zIndex: -1 })`) the DOM already covers GL, and `data-umber-occlude` does nothing.
|
|
957
1024
|
- A GL element inside an open modal `<dialog>` or popover (the browser's top layer, painted over the canvas whatever its `z-index`) shows its DOM, with one warning.
|
|
958
1025
|
- A rotated, skewed or tilted parent cuts it through its own turned box (drawn per pixel). A three.js layer can't be cut by a rounded or shaped parent (it draws uncut and warns; straight clips do cut it).
|
|
959
1026
|
- **Its own small file.** What cuts, turns or tilts an element, and following the animations that do, is `chunks/shapes.js` (about 14 KB brotli). The engine downloads it by itself, the first time an element on the page needs it: nothing to add or import. Until it arrives that element shows its DOM, as while its image loads (after 5 s it stays on its DOM with a warning; a late file is still used). What brings it in: any parent with `overflow` other than `visible` (the rounded card, the hover-zoom wrapper, a slider: they are there to cut), a `clip-path`, a CSS `mask`, `contain: paint` or `content-visibility: auto` on a parent, a legacy `clip: rect()`, `offset-path`, an element inside an `<svg>`, a rotation, skew, flip or 3D tilt (also a `translate` with a z or a `perspective`), and an animation that turns, clips or rounds a GL element, or one that is scroll-driven or paused (scrubbed). What does not: moves and positive scales (`translate`, `scale`, `transform: translate…() scale…()`), a fade (`opacity`, `visibility`), a size change, and animations that do only those; and `html, body { overflow-x: hidden }`, as long as the element sits inside `<body>`'s box.
|
|
960
|
-
- **Video has its own small file too.** A GL `<video>`, and an element a module feeds (`data-
|
|
961
|
-
- **
|
|
1027
|
+
- **Video has its own small file too.** A GL `<video>`, and an element a module feeds (`data-umber-scrub`), is drawn with `chunks/video.js` (about 3 KB brotli), downloaded by itself the first time the page has one (next to `chunks/gl.js` when the page already has it). Until it arrives that element shows its DOM.
|
|
1028
|
+
- **KTX2 pictures.** `data-umber-src="/img/dunes.ktx2"` beside the `<img>` (which stays the DOM picture and the fallback) draws a Basis Universal KTX2 file (ETC1S or UASTC, encoded with `basisu` or any KTX2 tool) compressed on the GPU: ASTC, BC7, ETC2 or BC1/BC3, whichever the device has, a quarter to an eighth of the memory of the same JPEG decoded, with the file's own mip levels. Only the levels the element needs go up; a bigger element gets the larger ones. Its transcoder (`chunks/basis.js` with `basis_transcoder.js` and `.wasm`, about 215 KB brotli, in a worker) loads on the first `.ktx2` only. Under a Content Security Policy it needs `worker-src blob:` and `script-src 'wasm-unsafe-eval'` (Hosting); the asset tool's pictures need none of them. Give the file sides that are a multiple of 4 (a file without is drawn uncompressed); one that can't be read draws the `<img>`'s own file.
|
|
1029
|
+
- **One texture per image.** Elements that show the same image (the same `src`, or `data-umber-src`: a marquee's repeated slides, a thumbnail and its large view) share one GPU texture: it is fetched, decoded and uploaded once, and a later element with that image draws at once. It is freed when the last element showing it goes (or is far from the screen when GPU memory is full).
|
|
962
1030
|
|
|
963
1031
|
### Turned, tilted and moving
|
|
964
1032
|
|
|
965
1033
|
- **Transforms are drawn like the DOM:** `rotate`, `skew`, mirrors (`scaleX(-1)`), the individual `rotate` / `scale` / `translate` properties, `transform-origin`, and 3D: `rotateX/Y`, `perspective()`, a parent's `perspective` and `perspective-origin`, `preserve-3d` and `backface-visibility: hidden` (a flip card draws only the face towards you), on the element or any parent. GL text inside them stays crisp: it is painted flat and turned by the GPU. Flat elements (no transform, or only translate and scale) take the same fast path as before, and a scroll still reads nothing for them: a turned element's matrix is measured once and only moved by the scroll.
|
|
966
|
-
- **Animations are followed by themselves.** Umber asks the browser which animations run (`document.getAnimations()`: CSS animations and transitions, `element.animate()`, scroll-driven `animation-timeline`) and measures only the elements they move, only while they run, once more when they end. An infinite one (a marquee) is followed while it is on screen, not once it scrolled away. A scroll-driven one is measured on the frames the page scrolls. Inline styles (GSAP, Webflow Interactions) are caught by the DOM watch, and drawn in the frame they are written: when your own `requestAnimationFrame` loop (or `gsap.ticker`) runs after Umber's and styles a GL element, Umber moves its next frame behind that loop, once, the way it follows Lenis, so only the first frame after it started shows the old value. A still page still draws 0 frames a second. `data-
|
|
967
|
-
- `element.animate()` fires no event, and neither do an animation's own controls, so Umber wraps the browser's `Element.prototype.animate` and `Animation.prototype` `play()`, `pause()`, `finish()`, `reverse()`, `cancel()`, `updatePlaybackRate()` and the `currentTime` / `startTime` / `playbackRate` setters while it runs: your call goes through untouched and returns the same thing; Umber only notes the animation and looks at it on the next frame. A Web Animation started from a timer, an `IntersectionObserver` or a library like Motion is followed from its first frame, also on a page that was asleep, and so is one built paused and started, finished, reversed or seeked later (a preloader done, a `setTimeout` intro). CSS animations and transitions share these methods. `
|
|
1034
|
+
- **Animations are followed by themselves.** Umber asks the browser which animations run (`document.getAnimations()`: CSS animations and transitions, `element.animate()`, scroll-driven `animation-timeline`) and measures only the elements they move, only while they run, once more when they end. An infinite one (a marquee) is followed while it is on screen, not once it scrolled away. A scroll-driven one is measured on the frames the page scrolls. Inline styles (GSAP, Webflow Interactions) are caught by the DOM watch, and drawn in the frame they are written: when your own `requestAnimationFrame` loop (or `gsap.ticker`) runs after Umber's and styles a GL element, Umber moves its next frame behind that loop, once, the way it follows Lenis, so only the first frame after it started shows the old value. A still page still draws 0 frames a second. `data-umber-live` is only for elements your own `requestAnimationFrame` loop moves.
|
|
1035
|
+
- `element.animate()` fires no event, and neither do an animation's own controls, so Umber wraps the browser's `Element.prototype.animate` and `Animation.prototype` `play()`, `pause()`, `finish()`, `reverse()`, `cancel()`, `updatePlaybackRate()` and the `currentTime` / `startTime` / `playbackRate` setters while it runs: your call goes through untouched and returns the same thing; Umber only notes the animation and looks at it on the next frame. A Web Animation started from a timer, an `IntersectionObserver` or a library like Motion is followed from its first frame, also on a page that was asleep, and so is one built paused and started, finished, reversed or seeked later (a preloader done, a `setTimeout` intro). CSS animations and transitions share these methods. `umber.destroy()` puts the originals back.
|
|
968
1036
|
- **Scrubbed animations:** a paused Web Animation whose time you set (`anim.pause(); anim.currentTime = x`, the usual way to scrub one from the scroll or a slider) is followed on the frame after each new time, from the scroll, an `input` event, a timer or your own `requestAnimationFrame` loop; one seen for the first time is measured once where it holds its element (built paused and seeked in one step).
|
|
969
|
-
- **Stylesheets are followed too:** a `<style>` added, removed or rewritten (a dev server, CSS-in-JS writing text), a `<link rel="stylesheet">` that loads late, or a stylesheet's `media` or `disabled` attribute changing measures every plane again. Rules added through the CSSOM (`sheet.insertRule()`, `adoptedStyleSheets`, what some CSS-in-JS libraries do in production) and a sheet turned off by script (`sheet.disabled = true`, `styleEl.disabled = true`) leave no trace in the DOM: call `
|
|
1037
|
+
- **Stylesheets are followed too:** a `<style>` added, removed or rewritten (a dev server, CSS-in-JS writing text), a `<link rel="stylesheet">` that loads late, or a stylesheet's `media` or `disabled` attribute changing measures every plane again. Rules added through the CSSOM (`sheet.insertRule()`, `adoptedStyleSheets`, what some CSS-in-JS libraries do in production) and a sheet turned off by script (`sheet.disabled = true`, `styleEl.disabled = true`) leave no trace in the DOM: call `umber.invalidate()` after them.
|
|
970
1038
|
- Worth knowing: a scroll-driven animation in Chromium updates one frame after a `scrollTo()` made inside `requestAnimationFrame` (Lenis), so those elements trail by a frame there; Firefox has no scroll-driven animations (they don't run in the DOM either).
|
|
971
1039
|
- **3D in Safari:** turned, skewed and masked elements match the DOM in Chromium, Firefox and WebKit. 3D tilts (`rotateX/Y` under `perspective`, flip cards, `preserve-3d`) match pixel by pixel in Chromium, Firefox and in what WebKit's compositor shows (99.96 % or more); WebKit's screenshots paint 3D without its perspective, so don't judge them from a WebKit screenshot. Not yet looked at by eye in real Safari (macOS and iOS): compare GL on against `?umber=off` there before you rely on 3D cards.
|
|
972
|
-
- **What falls back to the DOM** (with a warning that names the fix; GL takes it back when the cause goes): a tilt so strong that part of the element is behind the viewer (until it turns back); in WebKit browsers only (Safari, every iOS browser), a tilt whose `perspective` parent also cuts with `overflow` and `border-radius` (WebKit draws it flat: put the perspective on an inner element, or round the corners with `clip-path: inset(0 round …)`; seen in Playwright's WebKit build, not yet confirmed in real Safari); several GL elements facing you in one `preserve-3d` scene (a cube of GL images: GL can't depth-sort them; a flip card with hidden back faces is fine); `offset-path`; an element inside an `<svg>`; `zoom` on a turned element's parent (use `transform: scale()`); a box that doesn't match its transforms (seen almost edge-on). A three.js layer under a rotation is drawn upright in its box, with a warning (turn the camera instead). CSS `filter` on a parent is not drawn by GL (`
|
|
1040
|
+
- **What falls back to the DOM** (with a warning that names the fix; GL takes it back when the cause goes): a tilt so strong that part of the element is behind the viewer (until it turns back); in WebKit browsers only (Safari, every iOS browser), a tilt whose `perspective` parent also cuts with `overflow` and `border-radius` (WebKit draws it flat: put the perspective on an inner element, or round the corners with `clip-path: inset(0 round …)`; seen in Playwright's WebKit build, not yet confirmed in real Safari); several GL elements facing you in one `preserve-3d` scene (a cube of GL images: GL can't depth-sort them; a flip card with hidden back faces is fine); `offset-path`; an element inside an `<svg>`; `zoom` on a turned element's parent (use `transform: scale()`); a box that doesn't match its transforms (seen almost edge-on). A three.js layer under a rotation is drawn upright in its box, with a warning (turn the camera instead). CSS `filter` on a parent is not drawn by GL (`umber.inspect()` notes it).
|
|
973
1041
|
- **The canvas itself:** Umber's canvas is `position: fixed`. A `transform`, `filter`, `perspective`, `contain`, `will-change: transform` or `backdrop-filter` on `<body>` or `<html>` would make the canvas scroll or turn with the page, so GL turns off (the DOM shows) with a warning that names the property, until it goes: put it on a wrapper element inside `<body>` instead. A `filter` or `backdrop-filter` on `<html>` is fine (CSS exempts the root: a dark mode's `html { filter: invert(1) }` filters GL with the page). `zoom` on `<body>` is fine (the canvas moves out of `<body>`); on `<html>` it turns GL off too.
|
|
974
1042
|
|
|
975
1043
|
```js
|
|
976
|
-
const plane = await
|
|
1044
|
+
const plane = await umber.add(el, { type: "image", effects: ["dissolve"], options: { dissolve: { scale: 6 } } });
|
|
977
1045
|
// a plane from code (resolves null with GL off); see below
|
|
978
|
-
const plane =
|
|
979
|
-
|
|
980
|
-
|
|
1046
|
+
const plane = umber.plane(el); // the element's plane, or null (GL off, not created yet)
|
|
1047
|
+
umber.planes(); // every plane
|
|
1048
|
+
umber.planes(container); // the planes inside an element (a Barba container)
|
|
981
1049
|
|
|
982
1050
|
plane.uniforms.uShow.value = 0.5; // a plain { value }: GSAP, Motion, your own code
|
|
983
1051
|
plane.set("uShow", 0.5); // the same
|
|
984
1052
|
plane.tween("uShow", { value: 1, duration: 1.2, delay: 0, ease: "expo.out" }); // Umber's own tween; await it
|
|
985
1053
|
plane.play(); // run its effect's `play` uniform to 1, with that effect's options
|
|
986
1054
|
plane.play({ value: 0, duration: 0.6 }); // ...or back to 0
|
|
987
|
-
plane.rect; // Float32Array [x, y, width, height]
|
|
988
|
-
// GL text: the padded quad its glyphs are painted in (descenders, italics: tens of px per side on large type), not the element's box: use el.getBoundingClientRect() or
|
|
989
|
-
plane.inView; plane.progress; // on screen (the real screen, like
|
|
1055
|
+
plane.rect; // Float32s<4>, a Float32Array of 4: [x, y, width, height], this frame's viewport rect, CSS px (plane.rect[2] is the width, typed as a number).
|
|
1056
|
+
// GL text: the padded quad its glyphs are painted in (descenders, italics: tens of px per side on large type), not the element's box: use el.getBoundingClientRect() or umber.track(el) for that
|
|
1057
|
+
plane.inView; plane.progress; // on screen (the real screen, like umber.track()); 0 as its top enters at the bottom, 1 as its bottom leaves at the top
|
|
990
1058
|
plane.status; // "loading" | "ready" | "error" (also "error" while a clip GL can't draw shows its DOM)
|
|
991
1059
|
plane.effects; // [{ name, options }]
|
|
992
1060
|
plane.kind; // "image" | "video" | "text" | "shader" | "layer" | "group"
|
|
993
1061
|
plane.get("uShow"); // a uniform's value
|
|
994
1062
|
plane.wake(); // draw at least one more frame (after changing an array uniform in place)
|
|
995
1063
|
const off = plane.on("enter", (p) => {}); // also "ready", "leave", "resize", "error", "destroy", "text"; or plane.off(name, fn)
|
|
996
|
-
plane.text; // data-
|
|
997
|
-
plane.destroy(); // the element shows as plain DOM again;
|
|
1064
|
+
plane.text; // data-umber="text" only, once chunks/text.js is here: { lines, words, chars, version, progress() } (see GL text)
|
|
1065
|
+
plane.destroy(); // the element shows as plain DOM again; umber.scan(el) brings it back
|
|
998
1066
|
```
|
|
999
1067
|
|
|
1000
|
-
- **`
|
|
1001
|
-
- `
|
|
1068
|
+
- **`umber.add(el, options)` writes the attributes** its options stand for (`type` -> `data-umber`, `effects` -> `data-umber-effect`, `options: { dissolve: { scale: 6 } }` -> `data-umber-dissolve-scale="6"`, plus `shader`, `layer`, `src`, `fit`, `order`, `live`, `clip` and `instances`) and builds the plane right away when GL is loaded. Same contract, written for you: the CSS handshake and the DOM watch key on those attributes. An element that has `data-umber` already resolves with its own plane. Inside `umber.scope()`, `revert()` removes the plane and puts the element's attributes back as they were.
|
|
1069
|
+
- `umber.plane(el)` works once `await umber.ready` resolved (or after the element's plane event `ready`). Before that, or with GL off, it is `null`: always write `umber.plane(el)?.play()`.
|
|
1002
1070
|
- `plane.set("uX", v)` on a name no effect of that plane declares warns once (with the closest name it does have): nothing would read it.
|
|
1003
1071
|
- A tween returns a promise-like `Tween` (`await`, `.pause()`, `.play()`, `.kill()`). A new tween on the same uniform replaces the old one, so two triggers never fight.
|
|
1004
1072
|
|
|
@@ -1008,29 +1076,30 @@ An effect that names `play: "uShow"` gets the shared play options, set per eleme
|
|
|
1008
1076
|
|
|
1009
1077
|
| Option | Default | Meaning |
|
|
1010
1078
|
|---|---|---|
|
|
1011
|
-
| `trigger` | `"auto"` | `auto`: on screen when the plane is made, it plays at once; further down, when scrolled into view. `scroll`: always waits for the scroll. `load`: at once, wherever it is. `manual`: only `
|
|
1079
|
+
| `trigger` | `"auto"` | `auto`: on screen when the plane is made, it plays at once; further down, when scrolled into view. `scroll`: always waits for the scroll. `load`: at once, wherever it is. `manual`: only `umber.plane(el)?.play()`. `hover`: 0 to 1 while the pointer is over the element (or its closest `a` or `button`), back to 0 when it leaves; `delay` counts on enter, reduced motion jumps without the tween. |
|
|
1012
1080
|
| `delay` | `0` | Seconds, counted from the moment it may play. |
|
|
1013
1081
|
| `duration` | `1.4` | Seconds (the effect's own `options.duration` overrides it). |
|
|
1014
1082
|
| `ease` | `"umber"` | Any ease (below). |
|
|
1015
|
-
| `start` | `"top 90%"` | For scroll: `"<element edge> <screen line>"`. Edge: `top`, `center`, `bottom`. Line: `top`, `center`, `bottom`, `80%`, `600px`. A `center` or `bottom` edge works on elements taller than the screen too, and one already past the line plays at once. No offsets (`top+=100`): those are for `
|
|
1083
|
+
| `start` | `"top 90%"` | For scroll: `"<element edge> <screen line>"`. Edge: `top`, `center`, `bottom`. Line: `top`, `center`, `bottom`, `80%`, `600px`. A `center` or `bottom` edge works on elements taller than the screen too, and one already past the line plays at once. No offsets (`top+=100`): those are for `umber.progress()` and scrub. |
|
|
1084
|
+
| `repeat` | `""` (once) | `"reverse"`: it plays back to 0 when the page goes back up past its `start` line, and again as it comes down past it. `"true"`: once it has left the screen it is set back to 0, unseen, and plays again the next time it scrolls in, from either side. For `auto`, `scroll` and `load`. |
|
|
1016
1085
|
|
|
1017
1086
|
```html
|
|
1018
|
-
<div data-
|
|
1019
|
-
data-
|
|
1087
|
+
<div data-umber="image" data-umber-effect="dissolve" data-umber-dissolve-trigger="scroll"
|
|
1088
|
+
data-umber-dissolve-delay="0.2" data-umber-dissolve-start="top 75%"><img src="a.jpg" alt=""></div>
|
|
1020
1089
|
```
|
|
1021
1090
|
|
|
1022
|
-
- `
|
|
1091
|
+
- `umber.hold()` holds every play back until you release it (a transition overlay still covers the page). Under reduced motion, plays show at once.
|
|
1023
1092
|
- **Eases** (plays, `plane.tween`, morphs): `"umber"` (the default, `cubic-bezier(0.625, 0.05, 0, 1)`), `"linear"`, the CSS keywords (`"ease-out"`...), `"cubic-bezier(a, b, c, d)"`, CSS `"linear(0, 0.6 40%, 1)"` (paste any spring or bounce exported for CSS), `"spring"` / `"spring(0.3)"`, `"<family>.in | .out | .inOut"` with `quad cubic quart quint sine expo circ` or `power1`..`power4`, or a function `(t) => number`.
|
|
1024
1093
|
- **Springs:** `"spring(bounce)"`, bounce 0 (no overshoot) to 0.95, default 0.2; the duration is the time it takes to settle. In `plane.tween` and plays it runs as a real spring: it starts with the speed the value already had, so a hover reversed half-way turns round smoothly, and it ends (no more frames) once at rest: `el.onmouseleave = () => plane.tween("uHover", { value: 0, duration: 0.6, ease: "spring(0.3)" })`.
|
|
1025
1094
|
|
|
1026
|
-
### GL text (`data-
|
|
1095
|
+
### GL text (`data-umber="text"`)
|
|
1027
1096
|
|
|
1028
|
-
The real text stays in the DOM: selectable, crawlable, read aloud, found by find-in-page. Umber asks the browser where it placed every glyph,
|
|
1097
|
+
The real text stays in the DOM: selectable, crawlable, read aloud, found by find-in-page. Umber asks the browser where it placed every glyph, draws them at those spots from one glyph atlas that every GL text on the page shares (each word painted once, so forty headings cost about what their words do, not forty textures), and once the GPU drew them the DOM text turns transparent. Any effect then works on text.
|
|
1029
1098
|
|
|
1030
|
-
The text painter is its own small file (`chunks/text.js`). The engine downloads it by itself, next to `chunks/gl.js`, only on pages with a `data-
|
|
1099
|
+
The text painter is its own small file (`chunks/text.js`). The engine downloads it by itself, next to `chunks/gl.js`, only on pages with a `data-umber="text"` element: there is nothing to add or import for it, and until it arrives the DOM text simply shows.
|
|
1031
1100
|
|
|
1032
|
-
- **Supported:** any loaded font, weight, style, size, a colour and an opacity per span (hover and theme changes to the colour, opacity, font, weight or spacing repaint), letter-spacing, text-transform (upper case in the text's `lang`: Turkish i becomes İ), small caps and condensed faces, several lines, inline children, emoji, right-to-left text, the hyphen the browser draws under `hyphens: auto` or at a soft hyphen (in every engine), and `-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale` on macOS (GL paints the same weight as the DOM: the
|
|
1033
|
-
- **Not supported** (Umber notices, marks it `error` and the DOM text stays): gradient or `background-clip` text, text strokes, `font-feature-settings` that changes glyphs (`kern`, `liga`, `clig` and `calt` are fine), `font-variation-settings`, `font-variant-numeric` and the other `font-variant-*` values, a `font-stretch` between the keyword widths (`80%`), underlines and other text decorations (line-through, overline), scripts that need letter shaping (Arabic, Indic, Thai), vertical `writing-mode`, `text-overflow: ellipsis` and line-clamp, `::before` / `::after` content and list markers, a styled `::first-letter` or `::first-line` (a drop cap, also on a paragraph inside the element), `text-shadow`, a `-webkit-text-fill-color` other than its `color`, discretionary or historical ligatures, `font-size-adjust`, `text-transform: full-width` or `full-size-kana`, and text that runs past its element's box (a `nowrap` line wider than it: let it wrap, or put `data-
|
|
1101
|
+
- **Supported:** any loaded font, weight, style, size, a colour and an opacity per span (hover and theme changes to the colour, opacity, font, weight or spacing repaint), letter-spacing, text-transform (upper case in the text's `lang`: Turkish i becomes İ), small caps and condensed faces, several lines, inline children, emoji, right-to-left text, the hyphen the browser draws under `hyphens: auto` or at a soft hyphen (in every engine), and `-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale` on macOS (GL paints the same weight as the DOM: the words are painted in one hidden canvas inside Umber's host, `data-umber-canvas="text"`, which takes the element's font smoothing). Each line's baseline sits on the device-pixel grid, as the browser puts it. Words for `glyph()` come from the browser's word segmenter, so Japanese and Chinese have real words, not one word per line.
|
|
1102
|
+
- **Not supported** (Umber notices, marks it `error` and the DOM text stays): gradient or `background-clip` text, text strokes, `font-feature-settings` that changes glyphs (`kern`, `liga`, `clig` and `calt` are fine), `font-variation-settings`, `font-variant-numeric` and the other `font-variant-*` values, a `font-stretch` between the keyword widths (`80%`), underlines and other text decorations (line-through, overline), scripts that need letter shaping (Arabic, Indic, Thai), vertical `writing-mode`, `text-overflow: ellipsis` and line-clamp, `::before` / `::after` content and list markers, a styled `::first-letter` or `::first-line` (a drop cap, also on a paragraph inside the element), `text-shadow`, a `-webkit-text-fill-color` other than its `color`, discretionary or historical ligatures, `font-size-adjust`, `text-transform: full-width` or `full-size-kana`, and text that runs past its element's box (a `nowrap` line wider than it: let it wrap, or put `data-umber="text"` on an element as wide as its text; or lines below a box too short for them). Inside rotated, skewed or tilted parents it works (each glyph is placed back through the element's matrix).
|
|
1034
1103
|
- **Inside the text element:** transforms are undone (a split unit pushed down, scaled or turned by a reveal is painted where the layout puts it, see Splitting text); 3D transforms are painted as drawn, with a warning. Clips (a line mask) are not painted: masks are free in GL, per line or word with `glyph()`, no wrapper elements needed. Screen-reader-only text (absolute, 1 x 1 px, overflow cut) is never painted. An inline `<svg>` icon is not text: it stays DOM and does not move with a GL effect.
|
|
1035
1104
|
- **Text changes** (a split, a re-split on resize) repaint once the text was quiet for 100 ms and the size for 150 ms; the old texture shows until then. Text that is cleared draws nothing in GL (and `plane.text` is empty) until it comes back.
|
|
1036
1105
|
- **Per line, word and character: `glyph(uv)`.** A text plane is one rectangle with one texture, so to tell lines apart an effect asks `glyph(vUv)` (see Writing effects). When an effect on a text plane calls it, Umber also paints a small glyph index while it paints the text (which line, word and character owns each pixel, and their boxes); text planes whose effects never call it pay nothing. `examples/text/lines.html` reveals one heading line by line and one paragraph word by word.
|
|
@@ -1041,40 +1110,44 @@ The text painter is its own small file (`chunks/text.js`). The engine downloads
|
|
|
1041
1110
|
Every text plane hands its units to JS (no extra layout read: they come from the paint):
|
|
1042
1111
|
|
|
1043
1112
|
```js
|
|
1044
|
-
const plane =
|
|
1045
|
-
const
|
|
1113
|
+
const plane = umber.plane(h1); // data-umber="text"
|
|
1114
|
+
const text = plane?.text; // undefined until chunks/text.js arrived
|
|
1115
|
+
const { lines, words, chars } = text ?? { lines: [], words: [], chars: [] }; // [] until the first paint
|
|
1046
1116
|
lines[1].text; // "second line" (white space collapsed)
|
|
1047
1117
|
lines[1].box; // { x, y, w, h }: element CSS px at rest, from its top-left
|
|
1048
1118
|
lines[1].words; lines[1].chars; // [first, last] word and character
|
|
1049
1119
|
words[3].line; chars[9].word; // which line / word they are in
|
|
1050
|
-
|
|
1051
|
-
plane
|
|
1120
|
+
text?.version; // +1 per paint that changed them
|
|
1121
|
+
plane?.on("text", (p) => {}); // after a paint that changed them (a rewrap, new text); not after a colour-only repaint
|
|
1052
1122
|
```
|
|
1053
1123
|
|
|
1054
1124
|
- **Numbering:** the same as `glyph()` in GLSL, so `lines[i]` in JS is `g.line == i` in a shader. Where the site split its own lines (`[data-line]` elements), those are the lines.
|
|
1055
1125
|
- **Four numbers per unit, `t`, `x`, `y`, `z`** (0 at first): plain properties, so GSAP, Motion or your own loop tween them (`gsap.to(plane.text.lines, { t: 1, stagger: 0.08 })`), or Umber's own: `lines[i].tween("t", { value: 1, delay: i * 0.08 })`. They mean whatever your code makes of them; Umber reads none itself. They are kept by index when the text rewraps (listen to `"text"` to start again on new lines). On planes whose effects call `glyph()` they also travel to the GPU with the glyph index: a shader reads them as `g.lineValue`, `g.wordValue` and `g.charValue` (`vec4(t, x, y, z)`; a write wakes one frame; a page that writes none stays idle).
|
|
1056
|
-
- **Scroll per line or word:** `plane.text.progress("lines" | "words", { start, end })` makes one `
|
|
1057
|
-
- **CSS counts:** the element gets `--
|
|
1126
|
+
- **Scroll per line or word:** `plane.text.progress("lines" | "words", { start, end })` makes one `umber.progress()` per unit, with `start` / `end` measured from that unit's own edges (`"top 80%"`: this line's top at 80 % of the screen). Not for characters (thousands of trackers): use their word's. They are measured once like any `umber.progress()`; make them again after a `"text"` event.
|
|
1127
|
+
- **CSS counts:** the element gets `--umber-lines`, `--umber-words` and `--umber-chars` (in a rule of Umber's own stylesheet, not its style attribute), for a DOM fallback that sizes things by them: `.reveal { --step: calc(1s / var(--umber-lines, 1)); }`.
|
|
1058
1128
|
|
|
1059
1129
|
```js
|
|
1060
1130
|
// Each line's `t` follows that line's own scroll from 85 % to 55 % of the screen.
|
|
1061
|
-
const
|
|
1062
|
-
|
|
1131
|
+
const text = plane?.text;
|
|
1132
|
+
if (text) {
|
|
1133
|
+
const { lines } = text;
|
|
1134
|
+
text.progress("lines", { start: "top 85%", end: "top 55%" }).forEach((p, i) => p.on("change", () => (lines[i].t = p.value)));
|
|
1135
|
+
}
|
|
1063
1136
|
```
|
|
1064
1137
|
|
|
1065
1138
|
### Splitting text (your own spans, or GSAP's Split Text plugin)
|
|
1066
1139
|
|
|
1067
|
-
A site may split the text of a `data-
|
|
1140
|
+
A site may split the text of a `data-umber="text"` element into lines, words or characters itself, with its own spans or GSAP's Split Text plugin. It keeps working:
|
|
1068
1141
|
|
|
1069
1142
|
- **GL paints the rest pose.** If the reveal sets its first pose in the same task as the split (lines at `yPercent: 100`, characters at `scale: 0`), Umber undoes those transforms while painting, so the texture never bakes in a hidden pose. Opacity is painted as the page has it (a word at `opacity: 0` is painted transparent).
|
|
1070
|
-
- **A DOM tween on the units shows.** While a tween writes the units' inline styles (GSAP fading or raising words), or a CSS animation or transition moves or fades one, GL can't follow it frame by frame: the element shows its DOM (`data-
|
|
1143
|
+
- **A DOM tween on the units shows.** While a tween writes the units' inline styles (GSAP fading or raising words), or a CSS animation or transition moves or fades one, GL can't follow it frame by frame: the element shows its DOM (`data-umber-status="error"`, `umber.inspect()` says why; no warning and no `error` event: nothing failed), and GL takes it back, painted as the units ended, once they held still for 150 ms (its `ready` event comes again). GL effects on that element pause meanwhile. An animation that never ends (a blinking caret), one that runs with the scroll, or one on a `::before` / `::after` is not waited for: GL paints the units as they stand. Writing only custom properties on the units (`--line`) is not an animation. A class that only changes a unit's colour repaints instead.
|
|
1071
1144
|
- **One repaint per split**, not one per mutation or per resize frame (see above). A split heading's characters that only inherit their colour are not watched for hover colour changes; the element itself, links and elements with their own colour are.
|
|
1072
|
-
- **Who animates what:** GL on and the plane `ready`: Umber (a `glyph()` effect). GL off (`html:not(.has-
|
|
1145
|
+
- **Who animates what:** GL on and the plane `ready`: Umber (a `glyph()` effect). GL off (`html:not(.has-umber)`) or the plane `error`: the site's DOM reveal. GL still loading: nobody yet (hold the reveal with `umber.hold()` or a `trigger`).
|
|
1073
1146
|
|
|
1074
1147
|
The recipe: split for the DOM fallback only, let GL animate when it runs.
|
|
1075
1148
|
|
|
1076
1149
|
```html
|
|
1077
|
-
<h2 class="reveal" data-
|
|
1150
|
+
<h2 class="reveal" data-umber="text" data-umber-effect="lines" data-umber-lines-trigger="manual">Real, crawlable text</h2>
|
|
1078
1151
|
```
|
|
1079
1152
|
|
|
1080
1153
|
```js
|
|
@@ -1085,13 +1158,13 @@ const el = document.querySelector(".reveal");
|
|
|
1085
1158
|
split(el).lines.forEach((line, i) => line.style.setProperty("--line", i));
|
|
1086
1159
|
|
|
1087
1160
|
// 2. GL animates when it runs; CSS animates the split when it doesn't.
|
|
1088
|
-
|
|
1161
|
+
umber.ready.then(() => umber.plane(el)?.play());
|
|
1089
1162
|
```
|
|
1090
1163
|
|
|
1091
1164
|
```css
|
|
1092
1165
|
/* DOM fallback only: GL is off, or this element fell back */
|
|
1093
|
-
html:not(.has-
|
|
1094
|
-
.reveal[data-
|
|
1166
|
+
html:not(.has-umber) .reveal .line,
|
|
1167
|
+
.reveal[data-umber-status="error"] .line {
|
|
1095
1168
|
animation: rise 0.9s cubic-bezier(0.23, 1, 0.32, 1) both;
|
|
1096
1169
|
animation-delay: calc(var(--line) * 80ms);
|
|
1097
1170
|
}
|
|
@@ -1104,62 +1177,65 @@ html:not(.has-gl) .reveal .line,
|
|
|
1104
1177
|
|
|
1105
1178
|
| Call | What it does |
|
|
1106
1179
|
|---|---|
|
|
1107
|
-
| `
|
|
1108
|
-
| `
|
|
1109
|
-
| `
|
|
1110
|
-
| `
|
|
1111
|
-
| `
|
|
1112
|
-
| `
|
|
1113
|
-
| `
|
|
1114
|
-
| `
|
|
1115
|
-
| `
|
|
1116
|
-
| `
|
|
1180
|
+
| `umber.scan(root?)` | Look for `[data-umber]` now (normally automatic). |
|
|
1181
|
+
| `umber.prune()` | Destroy planes whose element left the page (normally automatic). |
|
|
1182
|
+
| `umber.destroy(el)` | Destroy one element's plane (the element stays and shows). `umber.destroy()` ends the whole engine; `umber.destroy(null)` (a selector that found nothing) ends nothing and warns. |
|
|
1183
|
+
| `umber.invalidate(el?)` | Measure every plane (or one) again on the next frame, and read its effect options again (after a CSSOM change: `insertRule()`, `adoptedStyleSheets`, or a `data-umber-<effect>-<option>` your code changed). |
|
|
1184
|
+
| `umber.live(true \| false \| seconds)` | Measure every visible plane every frame. |
|
|
1185
|
+
| `umber.wake(frames?)` | Draw at least that many more frames. |
|
|
1186
|
+
| `umber.pause()` / `umber.resume()` | Stop drawing and show the DOM, then draw again. A `pause()` before GL is ready holds too: it starts paused. |
|
|
1187
|
+
| `umber.info` | Numbers: state, planes, visible, draws, textures, `textureMB` (image, video and text textures on the GPU), `targetMB` (render targets: groups, passes, sims, `umber.leave` copies, your `umber.target`s; there once `chunks/fx.js` is), `gpuMB` (everything that counts against the device's GPU memory budget: textures, render targets, cached video frames and the canvas itself), programs, fps, renders per second, dpr, scale, `busy` (why it keeps drawing), `tier` (`high` / `mid` / `low`) and `gpu` (the GPU tier: `level` 0 to 5, `reason`, `renderer`...: `docs/ai/debug.md`). |
|
|
1188
|
+
| `umber.canvas`, `umber.context` | The canvas and its WebGL2 context (null when GL is off). |
|
|
1189
|
+
| `umber.version`, `umber.destroyed`, `umber.off(name, fn)` | The engine's version; `true` after `umber.destroy()`; the other way to remove an `on()` listener. |
|
|
1117
1190
|
|
|
1118
1191
|
---
|
|
1119
1192
|
|
|
1120
1193
|
## Writing effects (the heart of "an engine, not a library")
|
|
1121
1194
|
|
|
1122
|
-
An effect is a few lines of GLSL that Umber puts into named slots of its own shader. You never write a whole shader. You list uniforms as plain values and Umber writes their GLSL declarations. Register it once, any time after `
|
|
1195
|
+
An effect is a few lines of GLSL that Umber puts into named slots of its own shader. You never write a whole shader. You list uniforms as plain values and Umber writes their GLSL declarations. Register it once, any time after `createUmber()` (before or after GL has loaded), and use it on any plane:
|
|
1123
1196
|
|
|
1124
1197
|
```js
|
|
1125
|
-
|
|
1198
|
+
umber.effect("tint", {
|
|
1126
1199
|
uniforms: { uTint: [1, 0.4, 0.2] }, // vec3, declared for you
|
|
1127
1200
|
fragment: { color: "color.rgb *= uTint;" },
|
|
1128
1201
|
});
|
|
1129
1202
|
```
|
|
1130
1203
|
```html
|
|
1131
|
-
<div data-
|
|
1204
|
+
<div data-umber="image" data-umber-effect="tint"><img src="a.jpg" alt=""></div>
|
|
1132
1205
|
```
|
|
1133
1206
|
|
|
1134
|
-
A plane waiting for an effect that is not defined yet is built again when it arrives. A typo warns: `data-
|
|
1207
|
+
A plane waiting for an effect that is not defined yet is built again when it arrives. A typo warns: `data-umber-effect="tnit" on <div.card>: no effect with that name (did you mean "tint"?)`.
|
|
1135
1208
|
|
|
1136
1209
|
### The shape
|
|
1137
1210
|
|
|
1138
1211
|
```js
|
|
1139
|
-
|
|
1212
|
+
umber.effect("name", {
|
|
1140
1213
|
uniforms: { uShow: 0, uColor: [1, 1, 1], uNoise: "/noise.png" }, // number -> float, [..] -> vec2..4 (9 -> mat3, 16 -> mat4), URL -> sampler2D
|
|
1141
|
-
// ...or a Signal, followed live: { uStory:
|
|
1142
|
-
// ...or a live texture from the input module: { uMask:
|
|
1143
|
-
options: { strength: 1, duration: 1.2 }, // per element: data-
|
|
1214
|
+
// ...or a Signal, followed live: { uStory: umber.progress(".story"), uPointer: umber.pointer } (see Utilities)
|
|
1215
|
+
// ...or a live texture from the input module: { uMask: umber.texture(canvas), uTouch: umber.touch() } (see Inputs)
|
|
1216
|
+
options: { strength: 1, duration: 1.2 }, // per element: data-umber-name-strength > --umber-name-strength > this
|
|
1144
1217
|
reduced: { uWave: 0 }, // optional: these values instead, when the visitor prefers reduced motion
|
|
1145
1218
|
play: "uShow", // optional: Umber plays it 0 -> 1 (trigger, delay, duration, ease, start)
|
|
1146
1219
|
segments: 1, // > 1 when vertex.main bends the plane (24 is plenty)
|
|
1147
1220
|
vertex: { head, main }, // main: change `pos` (vec3, px offset in its own axes) using `uv` (0..1)
|
|
1148
1221
|
fragment: { head, uv, color, alpha }, // uv: before sampling · color: vec4 · alpha: float
|
|
1149
|
-
setup(ctx) { /* once per plane; return a cleanup */ },
|
|
1222
|
+
setup(ctx) { /* once per plane; return a cleanup, or nothing */ },
|
|
1150
1223
|
update(ctx) { /* every drawn frame while on screen (ctx.frame is set) */ },
|
|
1151
1224
|
});
|
|
1152
1225
|
```
|
|
1153
1226
|
|
|
1154
|
-
- **
|
|
1155
|
-
|
|
1156
|
-
- **
|
|
1157
|
-
- **
|
|
1158
|
-
-
|
|
1159
|
-
- **
|
|
1227
|
+
- **In TypeScript, `ctx.options` is typed from `options`:** with `options: { strength: 1, label: "a" }`, `ctx.options.strength` is a `number` and `ctx.options.label` a `string` (a list default also reads an attribute's words, `string[]`); a name with no default is an error. `ctx.plane` is the plane (`Plane`) and `ctx.engine` the engine (`Umber`).
|
|
1228
|
+
|
|
1229
|
+
- **Options become uniforms.** Every number, boolean (0 or 1) or array option is also a uniform named `u` + Effect + Option: effect `dissolve`, option `scale` → `uDissolveScale`. Set it per element with `data-umber-dissolve-scale="6"` or per breakpoint with `--umber-dissolve-scale: 6`. Options are read when the plane is built and again when the window resizes (a new breakpoint) or you call `umber.invalidate(el)` (after your code changed a `data-umber-<effect>-<option>` or a class): only an option that changed reaches its uniform, so a value you set with `plane.set()` stays until then.
|
|
1230
|
+
- **Colours.** A CSS colour string, as a uniform, an option, an attribute, a `--umber-*` variable or in `plane.set()`, becomes a `vec4` [r, g, b, a] in sRGB (the page's own space): `uniforms: { uTint: "#ff3300" }`, `options: { color: "#fff" }` with `data-umber-tint-color="oklch(70% 0.15 30)"` or `data-umber-tint-color="var(--brand)"`. The browser converts it the way it converts the DOM's colours, so every CSS colour works (hex, rgb, hsl, oklch, `color(display-p3 ...)`, names); wide-gamut colours land where an sRGB screen shows them. `var()` is read from each element once, when the plane is built (or at `plane.set`), never per frame; `var(--brand, #0f0)` takes its fallback where `--brand` is not set. A `var()` that is not set and has no fallback is transparent, with a warning. A `uniform vec3` you declare yourself takes r, g, b. Give a colour option a colour default, so every element has the `vec4`.
|
|
1231
|
+
- **Uniforms you declare yourself** can be `float`, `vec2..4`, `mat2`, `mat3`, `mat4`, the non-square `mat2x3`..`mat4x3`, `int`, `ivec2..4`, `bool`, `bvec2..4`, `uint` or `uvec2..4`, and arrays of them: `uniform ivec2 uCell;` takes `[2, 3]`, `uniform float uWeights[5];` takes 5 numbers, `uniform mat3x2 uWarp;` takes 6 (a plain array or a `Float32Array`, column by column). Numbers that fit no type Umber declares (not 2, 3, 4, 9 or 16 of them) and that your GLSL reads without declaring warn: declare them, or make them a texture with `umber.texture()`. More numbers than a phone's uniforms hold (over 896) are data: Umber warns and names `umber.texture()`.
|
|
1232
|
+
- **Per-element images (maps).** A string option with a `/` in it is an image path, and its uniform a `sampler2D`: effect `depth`, `options: { map: "/img/blank.webp" }`, `data-umber-depth-map="/img/hero-depth.webp"` → `uDepthMap`. Sample it with the image's own crop, `texture(uDepthMap, fitUv(uv))`, and it stays in line with the image whatever `object-fit` and `object-position` do. Every element with the effect needs a path (give the option a default image), or its program has no `uDepthMap` and the element shows its DOM.
|
|
1233
|
+
- **`bleed`: drawing past the element.** An option named `bleed` (px) makes the plane's quad that much larger on every side (the largest `bleed` of its effects): glows, shadows, sparks. `uv` and `vUv` still run 0..1 on the element itself and go below 0 and above 1 in the bleed, where `sampleImage()` repeats the edge pixels: your effect decides what draws there (`alpha *= step(0.0, uv.x) * step(uv.x, 1.0) * ...` keeps only the box). Set it per element: `data-umber-glow-bleed="60"`. It is drawn while the element itself is on screen, and parents that clip still cut it (`data-umber-clip="false"` lifts that).
|
|
1234
|
+
- **`zoom`: drawing the picture bigger.** An option named `zoom` (a scale) says how much bigger the effect's vertex code draws the picture at most (a hover that scales it 2.5x: `options: { zoom: 2.5 }`): its texture is decoded that sharp ahead, so it stays sharp through the zoom. A CSS scale needs none: Umber decodes again, sharper, as the element grows.
|
|
1235
|
+
- **Reduced motion, per effect.** `reduced: { uniform: value }` replaces those uniforms when the visitor prefers reduced motion (and `createUmber({ reducedMotion })` is `"static"`, the default): keep a fade or a colour change, set a wave or a parallax to 0. `ctx.reducedMotion` says the same in `setup` and `update`. Plays still show at once under reduced motion.
|
|
1160
1236
|
- **Slots run in their own `{ }` block**, so local names never clash between effects. To share a value between two slots of your effect, declare a global in `head`: `head: "float linesMask = 1.0;"`.
|
|
1161
1237
|
- **Two effects may write a helper of the same name.** When two effects on one plane (or an effect and the shader) both declare the same name at the top of their `head` (a function, a `const`, a global, a `#define`), each effect's own is renamed (`e0_wave`, `e1_wave`) in all of that effect's code, so they stack without a compile error. A name only one of them declares stays as it is, so an effect may still call a helper another one declares. Function bodies, parameters and GLSL keywords are never renamed.
|
|
1162
|
-
- **Order matters:** `data-
|
|
1238
|
+
- **Order matters:** `data-umber-effect="a b"` runs `a`'s uv slot, then `b`'s; then `a`'s color slot, then `b`'s; and so on.
|
|
1163
1239
|
|
|
1164
1240
|
### What your GLSL can use (a fixed contract: only ever added to)
|
|
1165
1241
|
|
|
@@ -1171,12 +1247,12 @@ gl.effect("name", {
|
|
|
1171
1247
|
| | `uPlaneMatrix` | `mat3`: the element's own px (0..`uSize`) to viewport px. A translation for a flat element; rotation, skew and perspective for a turned one (below). |
|
|
1172
1248
|
| | `uMouse` | The pointer inside the element, 0..1 along its own edges (needs `ctx.trackMouse(true)`). |
|
|
1173
1249
|
| | `uTime` | Seconds (only advances on drawn frames; stands still under reduced motion with `reducedMotion: "static"`). An effect reads it to move by itself: it draws every frame only while something asks (a play, `ctx.busy(true)`, a hover play that is on: below). |
|
|
1174
|
-
| | `uScrollVelocity` | Smoothed scroll speed: px per second / 3600, clamped to -1..1, so `
|
|
1250
|
+
| | `uScrollVelocity` | Smoothed scroll speed: px per second / 3600, clamped to -1..1, so `umber.scroll.velocity / 60` (that is px per 60 Hz frame). A brisk wheel gives about 0.1 to 0.3, a fling 1. Multiply it in GLSL to taste (`uScrollVelocity * 4.0`). 0 under reduced motion. |
|
|
1175
1251
|
| | `uProgress` | 0 as the element's top enters at the bottom of the screen, 1 as its bottom leaves at the top. |
|
|
1176
1252
|
| | `uAlpha`, `uDpr` | The element's opacity (with its parents'), device px per CSS px. Fragment only. |
|
|
1177
|
-
| | `uImage`, `uImageSize` | The texture and its pixel size. Fragment only. |
|
|
1178
|
-
| | `uCanvas` | The size of what this draw goes into, device px: the canvas, or the texture of a group or `
|
|
1179
|
-
| | `uSurface` | Where this draw goes, viewport CSS px: `vec4(x, y, width, height)`. On the canvas it is `(0, 0, uViewport)`. Inside a group's texture or a `
|
|
1253
|
+
| | `uImage`, `uImageSize` | The texture (premultiplied alpha: `sampleImage()` gives it straight) and its pixel size. Fragment only. |
|
|
1254
|
+
| | `uCanvas` | The size of what this draw goes into, device px: the canvas, or the texture of a group or `umber.snapshot()`. Fragment only. |
|
|
1255
|
+
| | `uSurface` | Where this draw goes, viewport CSS px: `vec4(x, y, width, height)`. On the canvas it is `(0, 0, uViewport)`. Inside a group's texture or a `umber.snapshot()` it is that window, with a negative height (the target's rows run up). Positions map through it, so `uViewport` keeps meaning the viewport whatever Umber draws into. |
|
|
1180
1256
|
| | `uBleed` | Px the quad reaches past the element on every side (the `bleed` option; 0 without). |
|
|
1181
1257
|
| | `uScreen` | `vec2`: the element's centre on the viewport, -1..1 on both axes (y down): 0, 0 in the middle of the screen. Rotating galleries, depth by distance from the centre. |
|
|
1182
1258
|
| | `PI` | 3.14159... |
|
|
@@ -1188,18 +1264,18 @@ gl.effect("name", {
|
|
|
1188
1264
|
| | `fbm(vec2)` | Four octaves of noise, 0..1 (clouds, dissolves). Added when called. |
|
|
1189
1265
|
| | `rotate2d(angle)` | A `mat2` that turns a `vec2`. Added when called. |
|
|
1190
1266
|
| | `umberHash(vec2)`, `umberHash(vec3)` | A random-looking 0..1 per point (what `noise` is built on). Added when called. |
|
|
1191
|
-
| | `screenPx()` | This pixel's position on screen, viewport CSS px (y down), whatever turns or tilts the element. Fragment only. Added when called. Use it, not `uRect.xy + vUv * uRect.zw`, to compare with page positions like `
|
|
1192
|
-
| | `screenUv()` | This pixel on screen, 0..1 over the viewport, (0, 0) top-left: `screenPx() / uViewport`. Fragment only. Added when called. For effects that need screen-space coordinates (a screen-sized pattern, a texture the size of the screen such as `uFlow` or `
|
|
1193
|
-
| A new picture | `samplePrev(uv)` | The picture an image plane showed before its `src` changed (`data-
|
|
1194
|
-
| | `uSwap` | 0 -> 1 after a new picture is on the GPU (`data-
|
|
1267
|
+
| | `screenPx()` | This pixel's position on screen, viewport CSS px (y down), whatever turns or tilts the element. Fragment only. Added when called. Use it, not `uRect.xy + vUv * uRect.zw`, to compare with page positions like `umber.pointer`. Also right on a group's members, in a snapshot and in a `data-umber-pass` (there: this pixel of the pass's surface). |
|
|
1268
|
+
| | `screenUv()` | This pixel on screen, 0..1 over the viewport, (0, 0) top-left: `screenPx() / uViewport`. Fragment only. Added when called. For effects that need screen-space coordinates (a screen-sized pattern, a texture the size of the screen such as `uFlow` or `umber.touch()`). Also right on a group's members, in a snapshot and in a `data-umber-pass`. |
|
|
1269
|
+
| A new picture | `samplePrev(uv)` | The picture an image plane showed before its `src` changed (`data-umber-src`, or the `<img>`'s `src` / `srcset`), object-fit applied like `sampleImage`. Fragment only. Added when called. |
|
|
1270
|
+
| | `uSwap` | 0 -> 1 after a new picture is on the GPU (`data-umber-swap-duration`, default 0.8 s); 1 the rest of the time. `uPrev` / `uPrevSize` are the old texture and its size (`samplePrev` reads them). |
|
|
1195
1271
|
| GL text | `glyph(uv)` | Which line, word and character `uv` is in: a `Glyph` (below). Added when called. |
|
|
1196
|
-
| Scrub planes | `uScrubProgress`, `uScrubVelocity` | Only on `data-
|
|
1272
|
+
| Scrub planes | `uScrubProgress`, `uScrubVelocity` | Only on `data-umber-scrub` videos (see Scrub). |
|
|
1197
1273
|
|
|
1198
1274
|
**Rotated, skewed, mirrored or 3D-tilted elements** (by themselves or a parent) are drawn as their own quad, and your effect works in the element's own space: `vUv` runs along its own edges (perspective-correct), `pos` in `vertex.main` is a px offset along its own axes (a bend follows the tilt), `uMouse` is the pointer along its own edges. `uSize` is its layout size at its on-screen scale (for a rotation or a uniform scale: exactly its size along its edges; under a skew or a tilt, the layout's proportions, so `object-fit` and corners match the DOM), and `uRect` is its centre - `uSize` / 2 with `uSize`. A flat element (no transform, or only translate and scale) gets exactly what it got before: `uRect` is its rect and `uPlaneMatrix` a translation. `pos.z` still only feeds depth.
|
|
1199
1275
|
|
|
1200
1276
|
`vertex.main` sees `uViewport`, `uRect`, `uSize`, `uPlaneMatrix`, `uTime`, `uScrollVelocity`, `uMouse`, `uProgress`, the on-demand helpers and your own uniforms except textures (an instanced plane also declares the textures its vertex code names: see Instances). The ones marked "fragment only" are not declared there: using them in `vertex.main` is a compile error and the plane shows its DOM.
|
|
1201
1277
|
|
|
1202
|
-
**`glyph(uv)` on `data-
|
|
1278
|
+
**`glyph(uv)` on `data-umber="text"` planes.** It returns a struct; boxes are `vec4(x, y, width, height)` in the plane's uv (0..1, y down), so you compare them with `vUv`:
|
|
1203
1279
|
|
|
1204
1280
|
```glsl
|
|
1205
1281
|
struct Glyph {
|
|
@@ -1217,7 +1293,7 @@ struct Glyph {
|
|
|
1217
1293
|
- On any other plane, and on text before its index arrived, it answers "one line, one word, one character covering the whole element" (and warns once on non-text planes).
|
|
1218
1294
|
|
|
1219
1295
|
```js
|
|
1220
|
-
|
|
1296
|
+
umber.effect("lines", { // examples/effects/lines.js
|
|
1221
1297
|
play: "uShow", uniforms: { uShow: 0 }, options: { duration: 1.8, ease: "linear", stagger: 0.5 },
|
|
1222
1298
|
fragment: {
|
|
1223
1299
|
head: "float linesT = 1.0; float linesMask = 1.0;",
|
|
@@ -1235,10 +1311,10 @@ Helpers you define yourself win: if your `head` has its own `float noise(vec2 p)
|
|
|
1235
1311
|
|
|
1236
1312
|
### A new `src`: the old picture gives way
|
|
1237
1313
|
|
|
1238
|
-
A plane whose picture changes (a slideshow writing `img.src`, a framework reusing the `<img>`, `data-
|
|
1314
|
+
A plane whose picture changes (a slideshow writing `img.src`, a framework reusing the `<img>`, `data-umber-src` set from code) keeps drawing the old one until the new one is decoded and on the GPU, so the DOM never shows through. With no effect that asks, the new picture then replaces it. An effect that reads `uSwap` decides how the two meet (the tween is in `chunks/flip.js`, fetched with that effect's first plane; a swap before it is there, or under reduced motion, happens at once):
|
|
1239
1315
|
|
|
1240
1316
|
```js
|
|
1241
|
-
|
|
1317
|
+
umber.effect("crossfade", {
|
|
1242
1318
|
fragment: { color: "color = mix(samplePrev(uv), color, uSwap);" },
|
|
1243
1319
|
});
|
|
1244
1320
|
// a wipe, left to right with a soft edge:
|
|
@@ -1246,22 +1322,22 @@ gl.effect("crossfade", {
|
|
|
1246
1322
|
```
|
|
1247
1323
|
|
|
1248
1324
|
```html
|
|
1249
|
-
<div data-
|
|
1250
|
-
<script>document.querySelector("[data-
|
|
1325
|
+
<div data-umber="image" data-umber-effect="crossfade" data-umber-swap-duration="0.9"><img src="a.jpg" alt=""></div>
|
|
1326
|
+
<script>document.querySelector("[data-umber] img").src = "b.jpg";</script>
|
|
1251
1327
|
```
|
|
1252
1328
|
|
|
1253
1329
|
`color` is the new picture (`sampleImage`), `samplePrev(uv)` the old one with its own crop (the two may have different sizes). Both are straight alpha. Under reduced motion the new one simply replaces the old one. A second `src` while one blends: the old picture stays until the newest one is ready, then blends from there. Images only: a `<video>`'s new `src` shows its new frames as they come.
|
|
1254
1330
|
|
|
1255
|
-
### Shared GLSL: `
|
|
1331
|
+
### Shared GLSL: `umber.chunk()`
|
|
1256
1332
|
|
|
1257
1333
|
A chunk is a named piece of GLSL that any effect pulls in with a line of its own, in any slot (usually `head`):
|
|
1258
1334
|
|
|
1259
1335
|
```js
|
|
1260
|
-
|
|
1336
|
+
umber.chunk("sdf", `
|
|
1261
1337
|
float sdCircle(vec2 p, float r) { return length(p) - r; }
|
|
1262
1338
|
float sdBox(vec2 p, vec2 b) { vec2 d = abs(p) - b; return length(max(d, 0.0)) + min(max(d.x, d.y), 0.0); }
|
|
1263
1339
|
`);
|
|
1264
|
-
|
|
1340
|
+
umber.effect("ring", {
|
|
1265
1341
|
fragment: {
|
|
1266
1342
|
head: '#include "sdf"',
|
|
1267
1343
|
alpha: "alpha *= 1.0 - smoothstep(0.0, 0.01, abs(sdCircle(uv - 0.5, 0.4)) - 0.02);",
|
|
@@ -1271,14 +1347,14 @@ gl.effect("ring", {
|
|
|
1271
1347
|
|
|
1272
1348
|
- **Only included chunks are compiled**, once per program, however many effects include them: after Umber's helpers, before the effects' `head`s. A chunk may `#include` other chunks; they come first. Vertex code gets the chunks its vertex slots include, fragment code those of its fragment slots.
|
|
1273
1349
|
- **A chunk is never renamed**, so every effect that includes it calls the same functions. It may call Umber's helpers (`noise`, `fbm`...).
|
|
1274
|
-
- **Any time, any order.** An element whose effect includes a chunk that is not defined yet shows its DOM (one warning: `#include "sdf": no chunk has that name... Define it with
|
|
1350
|
+
- **Any time, any order.** An element whose effect includes a chunk that is not defined yet shows its DOM (one warning: `#include "sdf": no chunk has that name... Define it with umber.chunk("sdf", glsl).`) and is built again when `umber.chunk()` defines it. Defining a chunk again rebuilds the planes that use it.
|
|
1275
1351
|
- Includes, helper renaming and the helpers added when called (`noise`, `fbm`, `rotate2d`, `umberHash`, `screenPx`, `screenUv`, `uScreen`, `samplePrev`) come with `chunks/glsl.js`, fetched the first time a plane needs it (an `#include`, a helper call, or two effects with a `head` on one plane). That plane shows its DOM until then; pages that need none of it never download it. `glyph()` comes with `chunks/text.js` the same way. When your `alpha` slot runs, `alpha` already holds the element's opacity and its corners (CSS border-radius): multiply it (`alpha *= ...`), don't overwrite it. The output is premultiplied for you.
|
|
1276
1352
|
|
|
1277
1353
|
**After your `alpha` slot, Umber cuts the plane where its parents cut it in the DOM** (a rounded `overflow: hidden`, a `clip-path`; straight clips are a scissor). Whatever your effects do, nothing shows outside those clips, a bend in `vertex.main` included. Names starting with `uUmber` or `umber` are Umber's own: don't name your uniforms or functions that way.
|
|
1278
1354
|
|
|
1279
1355
|
### The helper pack (eases, noise, shapes, blend, dither, Oklab)
|
|
1280
1356
|
|
|
1281
|
-
More helpers, in the same contract: call one and it is there, with what it needs, once. They live in their own file (`chunks/glsl.js`, about 4.6 KB brotli): it downloads the first time an effect's code calls one, and a program carries only the helpers its code calls. A function of the same name in your own `head` wins. Each is also a `
|
|
1357
|
+
More helpers, in the same contract: call one and it is there, with what it needs, once. They live in their own file (`chunks/glsl.js`, about 4.6 KB brotli): it downloads the first time an effect's code calls one, and a program carries only the helpers its code calls. A function of the same name in your own `head` wins. Each is also a `umber.chunk()` under its own name, so `#include "snoise"` works too (what it needs comes first, once); a `umber.chunk("snoise", ...)` of your own keeps that name for your code.
|
|
1282
1358
|
|
|
1283
1359
|
| Group | Helpers | What they give |
|
|
1284
1360
|
|---|---|---|
|
|
@@ -1298,10 +1374,10 @@ More helpers, in the same contract: call one and it is there, with what it needs
|
|
|
1298
1374
|
| | `srgbToLinear(c)`, `linearToSrgb(c)`, `linearToOklab(c)`, `oklabToLinear(c)` | The conversions behind it. |
|
|
1299
1375
|
|
|
1300
1376
|
```js
|
|
1301
|
-
|
|
1377
|
+
umber.effect("poster", { // 4 levels per channel, blue-noise dithered
|
|
1302
1378
|
fragment: { color: "color.rgb = dither(color.rgb, blueNoise(gl_FragCoord.xy), 4.0);" },
|
|
1303
1379
|
});
|
|
1304
|
-
|
|
1380
|
+
umber.effect("words-in", { // each word eases in on its own
|
|
1305
1381
|
play: "uShow", uniforms: { uShow: 0 }, options: { duration: 1.4, ease: "linear" },
|
|
1306
1382
|
fragment: { alpha: "Glyph g = glyph(vUv); alpha *= expoOut(stagger(uShow, g.word, g.words, 0.7));" },
|
|
1307
1383
|
});
|
|
@@ -1322,7 +1398,7 @@ Names starting with `umber` in the pack (`umberRand3`, `umberHash3u`...) are its
|
|
|
1322
1398
|
| `listen(target, { type: fn })` | `addEventListener` for each type; returns one cleanup, and runs it when the plane goes. |
|
|
1323
1399
|
|
|
1324
1400
|
```js
|
|
1325
|
-
|
|
1401
|
+
umber.effect("lens", {
|
|
1326
1402
|
uniforms: { uOn: 0 },
|
|
1327
1403
|
fragment: { uv: "vec2 d = uv - uMouse; uv -= d * exp(-dot(d, d) * 12.0) * 0.15 * uOn;" },
|
|
1328
1404
|
setup(ctx) {
|
|
@@ -1335,16 +1411,16 @@ gl.effect("lens", {
|
|
|
1335
1411
|
The hover part alone needs no JavaScript: name the uniform as `play` and give it the `hover` trigger. Umber tweens it to 1 on `pointerenter` (on the element, or its closest link or button) and back to 0 on `pointerleave`, with the play's `duration` and `ease`. Its `delay` counts on enter only. An effect whose GLSL also reads `uTime` (a ripple that keeps moving under the pointer) draws every frame while that hover play is above 0, and stops once it is back at 0: no `ctx.busy(true)` needed for that.
|
|
1336
1412
|
|
|
1337
1413
|
```js
|
|
1338
|
-
|
|
1414
|
+
umber.effect("lift", { uniforms: { uOn: 0 }, play: "uOn", options: { trigger: "hover", duration: 0.6 }, fragment: { color: "color.rgb *= 1.0 + 0.2 * uOn;" } });
|
|
1339
1415
|
```
|
|
1340
1416
|
|
|
1341
1417
|
### Timing, three ways
|
|
1342
1418
|
|
|
1343
1419
|
```js
|
|
1344
|
-
|
|
1345
|
-
const u =
|
|
1420
|
+
umber.plane(el)?.tween("uShow", { value: 1, duration: 1 }); // 1. Umber's own tween
|
|
1421
|
+
const u = umber.plane(el)?.uniforms.uShow; // 2. GSAP (null with GL off)
|
|
1346
1422
|
if (u) gsap.to(u, { value: 1, scrollTrigger: { trigger: el, scrub: true } });
|
|
1347
|
-
|
|
1423
|
+
umber.effect("x", { play: "uShow", ... }); // 3. Umber plays it on scroll
|
|
1348
1424
|
```
|
|
1349
1425
|
|
|
1350
1426
|
### A scroll-velocity effect
|
|
@@ -1352,9 +1428,9 @@ gl.effect("x", { play: "uShow", ... });
|
|
|
1352
1428
|
`uScrollVelocity` is already smoothed and redraws the plane while the page moves: no JavaScript. A brisk wheel is about 0.2, so scale it up and clamp it:
|
|
1353
1429
|
|
|
1354
1430
|
```js
|
|
1355
|
-
|
|
1431
|
+
umber.effect("stretch", {
|
|
1356
1432
|
segments: 24, // a bendable mesh for the vertex part
|
|
1357
|
-
options: { strength: 1 }, // data-
|
|
1433
|
+
options: { strength: 1 }, // data-umber-stretch-strength="1.6" per element (uStretchStrength)
|
|
1358
1434
|
vertex: {
|
|
1359
1435
|
main: "pos.y += sin(uv.x * PI) * clamp(uScrollVelocity * 4.0, -1.0, 1.0) * uStretchStrength * 40.0;",
|
|
1360
1436
|
},
|
|
@@ -1368,44 +1444,44 @@ gl.effect("stretch", {
|
|
|
1368
1444
|
});
|
|
1369
1445
|
```
|
|
1370
1446
|
|
|
1371
|
-
The same speed in JavaScript: `
|
|
1447
|
+
The same speed in JavaScript: `umber.velocity.value` (this one), or `umber.scroll.velocity` (px per 60 Hz frame, unsmoothed, from the scroll module) divided by 60.
|
|
1372
1448
|
|
|
1373
|
-
### Full custom surfaces (`
|
|
1449
|
+
### Full custom surfaces (`umber.shader`)
|
|
1374
1450
|
|
|
1375
1451
|
```js
|
|
1376
|
-
|
|
1377
|
-
options: { speed: 0.2 }, // per element: data-
|
|
1452
|
+
umber.shader("sky", {
|
|
1453
|
+
options: { speed: 0.2 }, // per element: data-umber-shader-speed > --umber-shader-speed > this; the uniform uSpeed
|
|
1378
1454
|
fragment: "color = vec4(0.5 + 0.5 * cos(uTime * uSpeed + uv.xyx + vec3(0, 2, 4)), 1.0);",
|
|
1379
1455
|
animate: true, // default: draw every frame while on screen (uses uTime; not under reduced motion "static": uTime stands still). false: only on change
|
|
1380
1456
|
});
|
|
1381
1457
|
```
|
|
1382
1458
|
```html
|
|
1383
|
-
<div data-
|
|
1459
|
+
<div data-umber="shader" data-umber-shader="sky" data-umber-shader-speed="0.5" style="height: 60vh"></div>
|
|
1384
1460
|
```
|
|
1385
1461
|
|
|
1386
1462
|
The fragment sets `color` (vec4) from `uv`. `head` holds functions. `uniforms` work as for effects. Number, boolean and array `options` become uniforms named `u` + Option, with no shader name in it (`speed` → `uSpeed`), since one element has one shader. Effects stack on shader surfaces too.
|
|
1387
1463
|
|
|
1388
1464
|
### Examples to read
|
|
1389
1465
|
|
|
1390
|
-
Umber ships no effects. The examples gallery writes the ones it shows as plain example code: one definition per file in `examples/effects/`, which the page hands to `
|
|
1466
|
+
Umber ships no effects. The examples gallery writes the ones it shows as plain example code: one definition per file in `examples/effects/`, which the page hands to `umber.effect()` (only `duotone` is written in its page, `examples/video/loop.html`). Read them, copy them, change them.
|
|
1391
1467
|
|
|
1392
1468
|
| Page | Effect | What it shows |
|
|
1393
1469
|
|---|---|---|
|
|
1394
1470
|
| `examples/text/reveal.html` | `rise` | GL text rising out of its own box with `play` (whole elements, staggered with `delay`). |
|
|
1395
1471
|
| `examples/text/lines.html` | `lines`, `words` | One heading revealed line by line, one paragraph word by word, with `glyph()`. |
|
|
1396
|
-
| `examples/images/progress.html` | `reel` | A sticky reel of images wiping through, driven by `
|
|
1397
|
-
| `examples/images/pointer.html` | `field` | Every image bending towards one page pointer, `
|
|
1398
|
-
| `examples/images/drag.html` | `swing` | A strip dragged and thrown with `
|
|
1399
|
-
| `examples/scope/mount.html` | `dissolve`, `rise` | A component mounted from code with `
|
|
1472
|
+
| `examples/images/progress.html` | `reel` | A sticky reel of images wiping through, driven by `umber.progress()` as a uniform (no JS per frame, with Lenis). |
|
|
1473
|
+
| `examples/images/pointer.html` | `field` | Every image bending towards one page pointer, `umber.pointer` and its velocity as uniforms. |
|
|
1474
|
+
| `examples/images/drag.html` | `swing` | A strip dragged and thrown with `umber.drag()` (the input module); its velocity bends the planes as a uniform. |
|
|
1475
|
+
| `examples/scope/mount.html` | `dissolve`, `rise` | A component mounted from code with `umber.add()` in a `umber.scope()`, unmounted with one `revert()`. |
|
|
1400
1476
|
| `examples/images/dissolve.html` | `dissolve`, `wipe` | A noise dissolve with a glowing edge (`fbm`), and a soft wipe with a slight zoom-out. |
|
|
1401
1477
|
| `examples/images/hover.html` | `lens` | A liquid lens under the pointer with an RGB split (`setup`, `trackMouse`, `listen`). |
|
|
1402
1478
|
| `examples/images/scroll.html` | `bend`, `drift` | The plane bending with scroll speed (vertex slot, `segments`), the image drifting in its frame (`uProgress`). |
|
|
1403
1479
|
| `examples/video/loop.html` | `duotone` (in the page) | Two colours by brightness, its `uMix` tweened from buttons. |
|
|
1404
1480
|
| `examples/video/scrub.html` | `grain` | Film grain on a scrubbed video, stronger while scrubbing fast (`uScrubVelocity`). |
|
|
1405
1481
|
| `examples/transitions/barba.html` | `dissolve` | Planes taking part in a plain Barba transition (`transitions/transition.js`). |
|
|
1406
|
-
| `examples/three/behind-text.html` | | A three.js scene behind DOM text with `
|
|
1482
|
+
| `examples/three/behind-text.html` | | A three.js scene behind DOM text with `umber.attach()`. |
|
|
1407
1483
|
|
|
1408
|
-
A fade is one line: `
|
|
1484
|
+
A fade is one line: `umber.effect("fade", { play: "uShow", uniforms: { uShow: 0 }, fragment: { alpha: "alpha *= uShow;" } })`.
|
|
1409
1485
|
|
|
1410
1486
|
---
|
|
1411
1487
|
|
|
@@ -1419,7 +1495,54 @@ three.js is the only library Umber works **with**, and only the copy your site b
|
|
|
1419
1495
|
- cleanup when the element leaves the page (a Barba swap included);
|
|
1420
1496
|
- the maths between DOM pixels and 3D units.
|
|
1421
1497
|
|
|
1422
|
-
|
|
1498
|
+
**One canvas is the default.** Umber's point is one WebGL canvas linked to the whole DOM: every tagged element, every effect and every three.js scene draws there, in step with the page, and any effect can go on any element. So a new scene goes on Umber's canvas with `umber.renderer(THREE)` + `umber.view()` (below). Umber's canvas has depth and stencil buffers, so masks and depth sorting work there. `umber.attach()` (a second canvas with its own renderer) is only for porting an existing scene quickly, a scene that must keep renderer settings of its own, or one that must run where the site keeps Umber's canvas off (phones, with `devices: "desktop"`); never make a canvas per effect.
|
|
1499
|
+
|
|
1500
|
+
### The three module: glTF models and scenes tied to the DOM (start here)
|
|
1501
|
+
|
|
1502
|
+
`modules/three.js` (npm: `@occluze/umber/three`) puts glTF models and three.js scenes on Umber's one canvas with no renderer code: the visit's one `THREE.WebGLRenderer` on Umber's context (`umber.renderer()`, below), drawn in Umber's frame, on Umber's clock, under the page's passes, asleep at rest.
|
|
1503
|
+
|
|
1504
|
+
```html
|
|
1505
|
+
<div data-umber="model" data-umber-src="/models/chair.glb" data-umber-model-turn="0.5">
|
|
1506
|
+
<img src="/models/chair.jpg" alt="An oak chair"> <!-- shown until the model draws, and when GL is off -->
|
|
1507
|
+
</div>
|
|
1508
|
+
```
|
|
1509
|
+
|
|
1510
|
+
- The model loads when its element comes near (1.5 screens), is centred, sized to the box (its bounding sphere: it can turn without leaving it) and drawn there. It follows scroll and resize like any plane, fades with its element and goes when the element leaves.
|
|
1511
|
+
- Draco (`KHR_draco_mesh_compression`), KTX2 / Basis (`KHR_texture_basisu`) and meshopt (`EXT_meshopt_compression`) files work: the file is read first and only the decoders it uses are imported. Their wasm comes from jsDelivr for the three.js version on the page, or from `umber.use(Three, { decoders: { draco: "/draco/", basis: "/basis/" } })`.
|
|
1512
|
+
- Options, as `data-umber-model-<option>` or `--umber-model-<option>` in CSS: `fit` (`contain` | `cover`), `fov` (30), `zoom` (1), `rotate` (start turn, degrees: `"10 30 0"`), `turn` (turns around y as the element crosses the screen), `spin` (turns per second), `tilt` (radians at 1000 px/s of scroll, easing back), `play` (a glTF animation's name, or `all`), `scrub` (the animation follows the scroll's progress), `environment` (`room` | `none`), `scene` (`box`: its own scene, clipped to the box; `page`: the page scene, unclipped, so it can reach past its box).
|
|
1513
|
+
- It draws when the page moves and sleeps at rest; only `spin`, `play`, a `tilt` easing back or an `onFrame()` returning `true` keep frames coming, and none of those run under reduced motion (`turn` and `scrub` follow the scroll, so they still do).
|
|
1514
|
+
- Two elements with the same file: one download, one parse, shared geometry, materials and textures. When the last one leaves the page, the model stays parsed and on the GPU for 10 s (`keep`), so a router's next page showing it costs nothing; then it is freed.
|
|
1515
|
+
- Without the module, `data-umber="model"` keeps its DOM and says how to add it.
|
|
1516
|
+
|
|
1517
|
+
```js
|
|
1518
|
+
import { Three } from "@occluze/umber/three";
|
|
1519
|
+
umber.use(Three); // three.js: import("three"), the first time a page needs it
|
|
1520
|
+
|
|
1521
|
+
const chair = umber.three.model(".chair"); // a handle at once; the model once it is here:
|
|
1522
|
+
await chair.ready;
|
|
1523
|
+
chair.object.traverse((o) => { o.castShadow = true; }); // the file's scene (this element's copy)
|
|
1524
|
+
chair.onFrame((f) => { chair.pivot.position.y = Math.sin(f.progress * Math.PI) * 0.1; }); // f: dt, time, progress, velocity
|
|
1525
|
+
// also: chair.scene, chair.camera, chair.gltf, chair.mixer (when the file has animations), chair.progress, chair.velocity, chair.wake()
|
|
1526
|
+
|
|
1527
|
+
const s = await umber.three.scene(".hero"); // a scene in .hero's box: 1 world unit = 1 CSS px at z = 0, centred
|
|
1528
|
+
s.scene.add(new THREE.Mesh(new THREE.TorusKnotGeometry(80, 24), new THREE.MeshStandardMaterial()));
|
|
1529
|
+
// options: { scene, camera, fov, environment: "room" | "none" | texture, animate(f), dispose, scissor, followOpacity, dpr, passes }
|
|
1530
|
+
|
|
1531
|
+
const page = await umber.three.page(); // one scene over the viewport, on a fixed element at the end of <body>
|
|
1532
|
+
page.pin(mesh, "#figure-2", { fit: "contain" }); // mesh follows #figure-2's box every frame (fit: "none" keeps its size in px)
|
|
1533
|
+
page.onFrame((f) => { mesh.rotation.y = f.time; return true; });
|
|
1534
|
+
umber.three.lights(s.scene); // key, fill and sky lights, for materials the room light leaves dark
|
|
1535
|
+
```
|
|
1536
|
+
|
|
1537
|
+
- **Router pages:** a model or an element scene goes with its element (an element scene frees its geometries, materials and textures unless you passed your own `scene`, or `dispose: false`). The page scene lives on its own element at the end of `<body>`, so a router that swaps a container keeps it; each pin goes with its element. A router that replaces `<body>` takes it along: call `umber.three.page()` again on the new page.
|
|
1538
|
+
- **Passes:** a `data-umber-pass` on `<body>` covers models and the module's scenes like the images around them (each is drawn alone and copied into the frame in its place: one copy of its box per frame). `passes: false` on a scene draws it straight to the canvas.
|
|
1539
|
+
- **Bundling three.js:** the module never bundles three.js; three.js loads only on pages that use it.
|
|
1540
|
+
- *Peer dependency* (the default): `npm install three`. The module `import()`s `"three"` and `"three/addons/..."` by name the first time a page has a model or calls `umber.three.*`, so your bundler (Vite, webpack, Astro, Next) puts three.js in a chunk of its own that pages without 3D never load, and your own code shares the same copy. From the CDN (`<script src=".../modules/three.js">`), an import map names it: `<script type="importmap">{ "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.178.0/build/three.module.js", "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.178.0/examples/jsm/" } }</script>`.
|
|
1541
|
+
- *Bundled with your code:* pass what you imported, and nothing is imported by name: `umber.use(Three, { three: THREE, addons: { GLTFLoader, DRACOLoader, KTX2Loader, MeshoptDecoder, RoomEnvironment, clone } })` (any add-on left out is still imported by name when needed). `three` may also be a function: `{ three: () => import("three") }` keeps it lazy in a bundler that needs the import in your own code.
|
|
1542
|
+
- Any three.js from r160 works (`peerDependencies`, optional: a site without 3D installs nothing).
|
|
1543
|
+
- **Content Security Policy:** Draco and KTX2 decoding runs in workers made from `blob:` URLs and compiles WebAssembly: `worker-src blob:` and `script-src 'wasm-unsafe-eval'`, plus the decoders' origin (jsDelivr by default) in `script-src` / `connect-src`.
|
|
1544
|
+
|
|
1545
|
+
### umber.attach(): your renderer, your canvas (porting an existing scene)
|
|
1423
1546
|
|
|
1424
1547
|
```js
|
|
1425
1548
|
import * as THREE from "three";
|
|
@@ -1433,7 +1556,7 @@ try {
|
|
|
1433
1556
|
const scene = new THREE.Scene();
|
|
1434
1557
|
const camera = new THREE.PerspectiveCamera(35, 1, 0.1, 100);
|
|
1435
1558
|
|
|
1436
|
-
if (renderer)
|
|
1559
|
+
if (renderer) umber.attach(".hero-gl", {
|
|
1437
1560
|
renderer, scene, camera,
|
|
1438
1561
|
devices: "all", // this scene runs on phones even if the site keeps planes to desktops
|
|
1439
1562
|
dpr: [1, 2], // optional, default: the engine's dpr
|
|
@@ -1447,34 +1570,34 @@ if (renderer) gl.attach(".hero-gl", {
|
|
|
1447
1570
|
});
|
|
1448
1571
|
```
|
|
1449
1572
|
|
|
1450
|
-
- **No WebGL at all:** `new THREE.WebGLRenderer()` throws before Umber is asked anything, so make it in a `try` as above (Umber's own `
|
|
1573
|
+
- **No WebGL at all:** `new THREE.WebGLRenderer()` throws before Umber is asked anything, so make it in a `try` as above (Umber's own `umber.enabled` / `umber.reason` are about its planes; a view has its own device rule, below). Put a still image or a CSS background in the element for that case.
|
|
1451
1574
|
- The renderer's canvas goes into the element unless you placed it in the page yourself. It stays a normal DOM child, so CSS opacity, z-index and a `position: fixed` Barba container just work.
|
|
1452
1575
|
- **When it draws:** the first frame, `view.wake()`, `view.busy(reason, true)`, a resize, and every frame `animate()` returns `true`. Scrolling never redraws it: the canvas moves with the page. Under reduced motion `animate()` still runs, but returning `true` no longer loops: call `view.wake()` when what it shows changes (a model that finished loading).
|
|
1453
1576
|
- `f` (the view frame): `time`, `dt`, `ratio`, `frame`, `width`, `height` (CSS px), `dpr`, `rect`, `progress` (0 as the element enters at the bottom, 1 as it leaves at the top), `velocity` (px/s), `reducedMotion`, `renderer`, `scene`, `camera`, `view`.
|
|
1454
|
-
- **The view:** `view.status` (`loading | ready | off | error | lost | destroyed`, also `data-
|
|
1577
|
+
- **The view:** `view.status` (`loading | ready | off | error | lost | destroyed`, also `data-umber-view` on the element), `view.ready` (a promise), `view.enabled`, `view.reason`, `view.rect`, `view.inView`, `view.progress`, `view.width / height / dpr`, `view.wake(frames)`, `view.busy("drag", true)`, `view.on("ready" | "resize" | "enter" | "leave" | "lost" | "restored" | "error" | "destroy", fn)`, `view.rectToWorld(rect, out?)`, `view.worldToRect(point)`, `view.destroy()`.
|
|
1455
1578
|
- `dispose: false` keeps your renderer when the view goes (a pool you reuse). By default Umber calls `renderer.dispose()` and frees the WebGL context.
|
|
1456
1579
|
- More options: `aspect: false` (you set the camera's aspect yourself; by default a `PerspectiveCamera` follows the box), `pixelBudget` (max drawing pixels, default the engine's) and `adaptive` (lower the resolution only while frames are slow, default the engine's).
|
|
1457
|
-
- Views have their **own device rule**: with the engine on `devices: "desktop"` (planes off on phones; the default is `"all"`), `
|
|
1580
|
+
- Views have their **own device rule**: with the engine on `devices: "desktop"` (planes off on phones; the default is `"all"`), `umber.attach(el, { devices: "all" })` still runs the scene on a phone. The engine does not even need `[data-umber]` on the page. GL turned off for the visit on purpose (`devices: false`, `?umber=off`, `data-umber-disable`, `"unlicensed"`, `"licence-unreachable"`, `"save-data"`...) is off for views too (`"software"` only for `umber.view()`: `umber.attach()` brings your own renderer): `view.reason` says which. Umber's own failures to draw (`"context"`, `"load-failed"`, `"load-timeout"`, `"context-lost"`, `"error"`) are not: `umber.attach()` brings your renderer, so it still runs (`umber.view()` draws on Umber's canvas, so it is off with it).
|
|
1458
1581
|
|
|
1459
|
-
###
|
|
1582
|
+
### umber.renderer(THREE) + umber.view(): one canvas for planes and 3D (the default)
|
|
1460
1583
|
|
|
1461
1584
|
```js
|
|
1462
|
-
const renderer = await
|
|
1463
|
-
|
|
1585
|
+
const renderer = await umber.renderer(THREE); // the ONE WebGLRenderer on Umber's own canvas (null when GL is off)
|
|
1586
|
+
umber.view(el, { scene, camera, animate: (f) => { mesh.rotation.y += f.dt; return true; } });
|
|
1464
1587
|
```
|
|
1465
1588
|
|
|
1466
1589
|
- DOM planes and 3D share one context, one canvas and one frame. The renderer lives for the whole visit, so three.js compiles each kind of material once and the next page compiles nothing.
|
|
1467
1590
|
- The view is clipped to its element (`scissor: false` to draw outside it), fades with its opacity (`followOpacity: false` to opt out) and goes when it leaves the page. `aspect: false` works here too.
|
|
1468
1591
|
- Never call `renderer.setSize()` here (Umber owns the canvas size) and use `scene.background` for a fill (`autoClear` is off: Umber clears once per frame).
|
|
1469
1592
|
- Post-processing: size an `EffectComposer` to the box in device px inside `render(f)`: `composer.setSize(f.width * f.dpr, f.height * f.dpr); composer.render();`.
|
|
1470
|
-
- It needs GL on for this device (the engine's `devices`). On a phone with `devices: "desktop"` it warns and suggests `
|
|
1471
|
-
- three.js on Umber's canvas (`
|
|
1593
|
+
- It needs GL on for this device (the engine's `devices`). On a phone with `devices: "desktop"` it warns and suggests `umber.attach()`.
|
|
1594
|
+
- three.js on Umber's canvas (`umber.renderer()`, `umber.view()`, `data-umber="layer"`) is its own small file, `chunks/layers.js`, which the engine downloads by itself on the first of them: `umber.renderer()` resolves once it is there, and a layer element keeps its DOM content until then.
|
|
1472
1595
|
|
|
1473
|
-
`data-
|
|
1596
|
+
`data-umber="layer"` + `umber.layer(name, { setup, render })` is the same shared-canvas idea from markup (for Webflow): `ctx.gl`, `ctx.canvas`, `ctx.rect`, `ctx.px` (device px), `ctx.three(renderer)` (viewport, scissor and state reset before you render), `ctx.state` for your objects. An `<img>` inside is a fallback, hidden once the layer draws.
|
|
1474
1597
|
|
|
1475
1598
|
```js
|
|
1476
|
-
|
|
1477
|
-
options: { speed: 1 }, // per element: data-
|
|
1599
|
+
umber.layer("discs", {
|
|
1600
|
+
options: { speed: 1 }, // per element: data-umber-layer-speed > --umber-layer-speed > this, in ctx.options
|
|
1478
1601
|
async setup(ctx) { /* once, when the element comes near; may return a cleanup */ },
|
|
1479
1602
|
render(ctx) { /* draw; ctx.opacity, ctx.mouse, ctx.time, ctx.dpr are there too */ },
|
|
1480
1603
|
resize(ctx) { /* the element or the screen changed size (before render) */ },
|
|
@@ -1485,6 +1608,15 @@ gl.layer("discs", {
|
|
|
1485
1608
|
});
|
|
1486
1609
|
```
|
|
1487
1610
|
|
|
1611
|
+
### In TypeScript: your three.js types, all the way through
|
|
1612
|
+
|
|
1613
|
+
Umber never imports three.js, so its types only say what Umber itself touches (`ThreeRendererLike`, `SharedRendererLike`, `ViewCameraLike` in `types/umber.d.ts`); everything else is your own objects' types, handed back unchanged:
|
|
1614
|
+
|
|
1615
|
+
- `umber.attach(el, { renderer, scene, camera, ... })` and `umber.view(el, { scene, camera, ... })`: `f.scene`, `f.camera` and `f.renderer` in `animate`, `render`, `resize` (and `setup`'s `ctx`) have the types of the objects you passed (`ViewFrame<Scene, Camera, Renderer>`). In `umber.view()`, `f.renderer` is the shared renderer, `null` until `umber.renderer()` resolved.
|
|
1616
|
+
- `await umber.renderer(THREE)` resolves with three's own `WebGLRenderer` type (or `null` when GL is off).
|
|
1617
|
+
- `animate` returns `true` to draw the next frame too, or nothing; `setup` returns a cleanup (or a promise of one), or nothing.
|
|
1618
|
+
- A layer's `ctx.state` is yours to type: `umber.layer<{ speed: number }, { scene: THREE.Scene }>("discs", { options: { speed: 1 }, setup(ctx) { ctx.state.scene = new THREE.Scene(); }, render(ctx) { ctx.state.scene; } })`: `setup` sees it empty (each member optional), `render` and `resize` filled.
|
|
1619
|
+
|
|
1488
1620
|
### DOM ↔ 3D maths (pure functions, no engine needed)
|
|
1489
1621
|
|
|
1490
1622
|
```js
|
|
@@ -1500,16 +1632,16 @@ On a view, `view.rectToWorld(rect)` and `view.worldToRect(point)` use that view'
|
|
|
1500
1632
|
|
|
1501
1633
|
---
|
|
1502
1634
|
|
|
1503
|
-
## Render targets:
|
|
1635
|
+
## Render targets: umber.target(), umber.snapshot(), uBackdrop
|
|
1504
1636
|
|
|
1505
|
-
Offscreen textures on Umber's own WebGL context. All of it is its own small file, `chunks/fx.js`, which the engine downloads by itself on the first `
|
|
1637
|
+
Offscreen textures on Umber's own WebGL context. All of it is its own small file, `chunks/fx.js`, which the engine downloads by itself on the first `umber.target()`, `umber.snapshot()` or effect that reads `uBackdrop`. A page without them never downloads it, and nothing changes on it.
|
|
1506
1638
|
|
|
1507
1639
|
### uBackdrop: what is drawn behind a plane
|
|
1508
1640
|
|
|
1509
|
-
An effect (or a `
|
|
1641
|
+
An effect (or a `umber.shader()`) that reads `uBackdrop` gets a copy of what the canvas holds behind its plane: the GL planes drawn before it (by `data-umber-order`, then page order). Nothing to declare: Umber sees the name and adds the sampler. Sample it at this pixel on the canvas:
|
|
1510
1642
|
|
|
1511
1643
|
```js
|
|
1512
|
-
|
|
1644
|
+
umber.shader("glass", {
|
|
1513
1645
|
animate: false,
|
|
1514
1646
|
fragment: `
|
|
1515
1647
|
vec4 b = texture(uBackdrop, gl_FragCoord.xy / uCanvas); // premultiplied
|
|
@@ -1518,7 +1650,7 @@ gl.shader("glass", {
|
|
|
1518
1650
|
});
|
|
1519
1651
|
```
|
|
1520
1652
|
```html
|
|
1521
|
-
<div class="glass" data-
|
|
1653
|
+
<div class="glass" data-umber="shader" data-umber-shader="glass" style="border-radius: 18px"></div>
|
|
1522
1654
|
```
|
|
1523
1655
|
|
|
1524
1656
|
- The copy covers the element plus about 32 px around it (plus its `bleed`), so a blur or a refraction can look a little outside. Offset `gl_FragCoord.xy` in device px (`* uDpr`).
|
|
@@ -1526,19 +1658,19 @@ gl.shader("glass", {
|
|
|
1526
1658
|
- One copy per frame per backdrop plane (only the area around it). Planes that don't read `uBackdrop` cost nothing: once none draws (a page change), the canvas-sized copy goes back to the pool.
|
|
1527
1659
|
- Until `chunks/fx.js` is here the plane is not drawn and its DOM shows (give it a CSS `backdrop-filter` as the fallback look).
|
|
1528
1660
|
|
|
1529
|
-
###
|
|
1661
|
+
### umber.target(options): a texture you draw into
|
|
1530
1662
|
|
|
1531
1663
|
```js
|
|
1532
|
-
const t = await
|
|
1533
|
-
t
|
|
1534
|
-
|
|
1664
|
+
const t = await umber.target({ width: 512, height: 512 }); // device px; null when GL is off
|
|
1665
|
+
t?.draw(`vec4 color(vec2 uv) { return vec4(uv, 0.5, 1.0); }`); // one fullscreen pass
|
|
1666
|
+
umber.effect("pattern", {
|
|
1535
1667
|
uniforms: { uPattern: t }, // any effect, any shader
|
|
1536
1668
|
fragment: { color: "color.rgb *= texture(uPattern, uv).rgb;" },
|
|
1537
1669
|
});
|
|
1538
1670
|
```
|
|
1539
1671
|
|
|
1540
1672
|
- **Options:** `width`, `height` (device px, default the canvas size; it never follows the canvas, call `resize()`), `type` (`"half"` default, `"float"`, `"u8"`), `msaa` (samples, 0 = off), `attachments` (1-4, MRT).
|
|
1541
|
-
- **`target.draw(glsl, uniforms?)`** replaces what it held. `glsl` defines `vec4 color(vec2 uv)` (straight alpha: Umber premultiplies), or its own `void main()` that writes `outColor` premultiplied (MRT: `layout(location = 1) out vec4 outNormal;` for the second attachment). Built in: `vUv`, `uSize` (the target in device px), `uTime`. Uniforms are declared for you: numbers, booleans, arrays (vec2..4, mat3, mat4), `{ value }` objects (read on each draw), anything with a `texture` (another target, a sim) as a sampler, and CSS colour strings as a `vec4` (`var()` read from `<html>`, once per string). Image URLs work in effects only. It draws right away (call it from an event or `
|
|
1673
|
+
- **`target.draw(glsl, uniforms?)`** replaces what it held. `glsl` defines `vec4 color(vec2 uv)` (straight alpha: Umber premultiplies), or its own `void main()` that writes `outColor` premultiplied (MRT: `layout(location = 1) out vec4 outNormal;` for the second attachment). Built in: `vUv`, `uSize` (the target in device px), `uTime`. Uniforms are declared for you: numbers, booleans, arrays (vec2..4, mat3, mat4), `{ value }` objects (read on each draw), anything with a `texture` (another target, a sim) as a sampler, and CSS colour strings as a `vec4` (`var()` read from `<html>`, once per string). Image URLs work in effects only. It draws right away (call it from an event or `umber.on("frame")` to animate) and asks for one frame, so the planes that read it redraw.
|
|
1542
1674
|
- **Also:** `target.clear()`, `target.resize(w, h)`, `target.release()`, `target.texture`, `target.textures` (MRT), `target.framebuffer`, `target.width`, `target.height`, `target.type`, `target.msaa`, `target.version`.
|
|
1543
1675
|
|
|
1544
1676
|
**The contract (keep it in mind when you read a target):**
|
|
@@ -1550,75 +1682,77 @@ gl.effect("pattern", {
|
|
|
1550
1682
|
- **Freeing is deferred:** `release()` gives it back to a pool, and its GPU memory is freed after 5 s unused (by a timer, never the frame loop: a still page stays at 0 frames per second). A target released and asked for again with the same size meanwhile is the same memory.
|
|
1551
1683
|
- **Context loss:** targets are made again when the context comes back, with new handles, and draw their last `draw()` (or snapshot) again.
|
|
1552
1684
|
|
|
1553
|
-
###
|
|
1685
|
+
### umber.snapshot(el): a still copy of a plane
|
|
1554
1686
|
|
|
1555
1687
|
```js
|
|
1556
|
-
const still = await
|
|
1557
|
-
|
|
1688
|
+
const still = await umber.snapshot(".hero"); // a target ("u8", device px) or null
|
|
1689
|
+
umber.effect("echo", { uniforms: { uStill: still }, fragment: { color: "vec4 s = texture(uStill, uv); color = vec4(s.rgb / max(s.a, 1e-5), s.a);" } });
|
|
1558
1690
|
```
|
|
1559
1691
|
|
|
1560
|
-
- What the plane draws right now, effects included, its parents' cuts (overflow, clip-path) not. The element or the plane (`
|
|
1692
|
+
- What the plane draws right now, effects included, its parents' cuts (overflow, clip-path) not. The element or the plane (`umber.plane(el)`) both work.
|
|
1561
1693
|
- It waits up to 5 s for the plane to be able to draw (its image loaded, its program compiled); a plane far below the fold starts loading now. Then `null` with a warning.
|
|
1562
1694
|
- A turned or tilted plane is copied with MSAA (smooth edges), inside its bounding box.
|
|
1563
1695
|
|
|
1564
1696
|
### Sharing a target with three.js (same canvas)
|
|
1565
1697
|
|
|
1566
|
-
Only with `
|
|
1567
|
-
|
|
1568
|
-
```js
|
|
1569
|
-
const renderer = await
|
|
1570
|
-
const t = await
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1575
|
-
const
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
|
|
1698
|
+
Only with `umber.renderer(THREE)` (three.js on Umber's own canvas and context): a texture from one WebGL context can't be used in another. Umber never imports three.js; this is your code, and it uses three.js internals (`renderer.properties`), so pin your three.js version.
|
|
1699
|
+
|
|
1700
|
+
```js
|
|
1701
|
+
const renderer = await umber.renderer(THREE);
|
|
1702
|
+
const t = await umber.target({ width: 1024, height: 1024 });
|
|
1703
|
+
if (renderer && t) { // both null when GL is off
|
|
1704
|
+
const map = new THREE.Texture();
|
|
1705
|
+
map.repeat.y = -1; map.offset.y = 1; // three.js reads row 0 as the bottom; a target's row 0 is its top
|
|
1706
|
+
let seen = -1;
|
|
1707
|
+
const adopt = () => { // again whenever t.version changed (resize, restored context)
|
|
1708
|
+
const p = renderer.properties.get(map);
|
|
1709
|
+
p.__webglTexture = t.texture;
|
|
1710
|
+
p.__webglInit = true;
|
|
1711
|
+
seen = t.version;
|
|
1712
|
+
};
|
|
1713
|
+
adopt();
|
|
1714
|
+
umber.view(".scene", { scene, camera, animate: () => { if (t.version !== seen) adopt(); return false; } });
|
|
1579
1715
|
}
|
|
1580
|
-
adopt();
|
|
1581
|
-
gl.view(".scene", { scene, camera, animate: () => { if (t.version !== seen) adopt(); return false; } });
|
|
1582
1716
|
```
|
|
1583
1717
|
|
|
1584
|
-
The other way round, a three.js render target into an Umber effect: any object with a `texture` field is a sampler uniform, so `uniforms: { uScene: { get texture() { return renderer.properties.get(rt.texture).__webglTexture || null; } } }` works after three.js rendered `rt` once (call `
|
|
1718
|
+
The other way round, a three.js render target into an Umber effect: any object with a `texture` field is a sampler uniform, so `uniforms: { uScene: { get texture() { return renderer.properties.get(rt.texture).__webglTexture || null; } } }` works after three.js rendered `rt` once (call `umber.wake()` after each render).
|
|
1585
1719
|
|
|
1586
1720
|
---
|
|
1587
1721
|
|
|
1588
|
-
## Groups and passes: data-
|
|
1722
|
+
## Groups and passes: data-umber="group", data-umber-pass
|
|
1589
1723
|
|
|
1590
|
-
Both are in `chunks/fx.js`, which the engine downloads by itself on the first `data-
|
|
1724
|
+
Both are in `chunks/fx.js`, which the engine downloads by itself on the first `data-umber="group"` or `data-umber-pass`. A page without them never downloads it.
|
|
1591
1725
|
|
|
1592
|
-
**GL content only.** Groups and passes work on what Umber draws (images, video, GL text, shader surfaces, flights). The DOM the page shows itself, text that is not `data-
|
|
1726
|
+
**GL content only.** Groups and passes work on what Umber draws (images, video, GL text, shader surfaces, flights). The DOM the page shows itself, text that is not `data-umber="text"`, CSS backgrounds, buttons, stays as it is, under or over the canvas. A "grain over the whole page" pass grains the GL planes, not the DOM around them; for grain everywhere, use one fixed `data-umber="shader"` plane.
|
|
1593
1727
|
|
|
1594
|
-
### data-
|
|
1728
|
+
### data-umber="group": many planes drawn as one
|
|
1595
1729
|
|
|
1596
1730
|
```html
|
|
1597
|
-
<section data-
|
|
1598
|
-
<h2 data-
|
|
1599
|
-
<div data-
|
|
1600
|
-
<div data-
|
|
1731
|
+
<section data-umber="group" data-umber-effect="wave">
|
|
1732
|
+
<h2 data-umber="text">Three hills</h2>
|
|
1733
|
+
<div data-umber="image"><img src="a.jpg" alt=""></div>
|
|
1734
|
+
<div data-umber="image"><img src="b.jpg" alt=""></div>
|
|
1601
1735
|
</section>
|
|
1602
1736
|
```
|
|
1603
1737
|
```js
|
|
1604
|
-
|
|
1738
|
+
umber.effect("wave", { fragment: { uv: "uv.x += sin(uv.y * 9.0 + uTime) * 0.006;" } });
|
|
1605
1739
|
```
|
|
1606
1740
|
|
|
1607
|
-
- Every GL plane inside the group (the closest group wins) is drawn into the group's own texture first, then the group draws that texture as its image, at its own place in the page's stacking, through its own `data-
|
|
1741
|
+
- Every GL plane inside the group (the closest group wins) is drawn into the group's own texture first, then the group draws that texture as its image, at its own place in the page's stacking, through its own `data-umber-effect`. One effect spans many planes (a wave over a heading and its photos, one blur over a gallery, a gooey merge), and applies to that group only.
|
|
1608
1742
|
- In the group's effects `sampleImage(uv)` is the members, straight alpha like an image; `uv` runs over the group's box. `sampleRaw(uv)` is the same premultiplied: add those up for a blur (as in a pass, below), never `sampleImage()` taps, or every member gets a dark rim. It works in any plane effect. Everything else is a normal plane: options, `play`, `uProgress`, `uMouse`, its parents' clips, its border-radius.
|
|
1609
|
-
- From JS: `
|
|
1743
|
+
- From JS: `umber.add(el, { type: "group", effects: ["wave"] })`.
|
|
1610
1744
|
- **The window.** The texture covers the part of the group on screen (plus 32 px and the effects' `bleed`), not the whole group: a group three screens tall costs one screen. Scrolling never makes a new texture.
|
|
1611
1745
|
- **Members are drawn uncut**: their own parents' `overflow` and `clip-path` inside the group are not applied in the texture. Cut the group instead (it is a plane like any other).
|
|
1612
1746
|
- three.js layers and planes that read `uBackdrop` draw on the canvas as usual, not in their group (said once).
|
|
1613
|
-
- A member moved into another group, or out of every group (a filter, a slider), is drawn where it now is. A `data-
|
|
1614
|
-
- Groups inside groups work (inner first). A member's DOM hides when it is drawn into its group, by its own `data-
|
|
1747
|
+
- A member moved into another group, or out of every group (a filter, a slider), is drawn where it now is. A `data-umber-id` image still landing and an element with a `view-transition-name` during `umber.transition()` are left out of their group, like on the canvas.
|
|
1748
|
+
- Groups inside groups work (inner first). A member's DOM hides when it is drawn into its group, by its own `data-umber-status`; the group itself mirrors no DOM.
|
|
1615
1749
|
- Until `chunks/fx.js` is here, members draw on their own; while the group's program compiles they wait with it (their DOM shows).
|
|
1616
1750
|
|
|
1617
1751
|
**Two textures (scroll-blended sections).** Put two groups in one sticky screen; the second reads the first as `uBackdrop` (what is drawn behind it) and its own members as `sampleImage`:
|
|
1618
1752
|
|
|
1619
1753
|
```js
|
|
1620
|
-
|
|
1621
|
-
uniforms: { uMix:
|
|
1754
|
+
umber.effect("wipe", {
|
|
1755
|
+
uniforms: { uMix: umber.progress(".blend", { start: "top top", end: "bottom bottom" }) },
|
|
1622
1756
|
fragment: { color: `
|
|
1623
1757
|
vec4 from = texture(uBackdrop, gl_FragCoord.xy / uCanvas);
|
|
1624
1758
|
from = vec4(from.rgb / max(from.a, 1e-5), from.a);
|
|
@@ -1627,16 +1761,16 @@ gl.effect("wipe", {
|
|
|
1627
1761
|
});
|
|
1628
1762
|
```
|
|
1629
1763
|
|
|
1630
|
-
### data-
|
|
1764
|
+
### data-umber-pass: effects over the whole frame, or over one group
|
|
1631
1765
|
|
|
1632
1766
|
```html
|
|
1633
|
-
<body data-
|
|
1634
|
-
<div data-
|
|
1767
|
+
<body data-umber-pass="trail grade grain smooth" data-umber-grain-blend="screen" data-umber-grain-opacity="0.5">
|
|
1768
|
+
<div data-umber="group" data-umber-pass="blur" data-umber-blur-scale="0.5">...</div>
|
|
1635
1769
|
```
|
|
1636
1770
|
|
|
1637
|
-
- On `<body>` or `<html>`: the frame's GL planes are drawn into one canvas-sized texture, the listed effects run over it in order, and the result goes onto the canvas. On a group: over its members, before the group's own `data-
|
|
1638
|
-
- **A pass is an effect** (`
|
|
1639
|
-
- In a pass: `uv` / `vUv` run over the surface, (0,0) top-left; `sampleImage(uv)` is the step before (straight alpha); `uSize` is the surface in **device px** (`1.0 / uSize` is one pixel); `uTime`, `uViewport`, `uDpr`, `uCanvas`, `uScrollVelocity`, `uRect` (the surface, viewport px) and `uMouse` (0..1 over the surface; a pass that reads it wakes on pointer moves). `uProgress` is 0: pass `
|
|
1771
|
+
- On `<body>` or `<html>`: the frame's GL planes are drawn into one canvas-sized texture, the listed effects run over it in order, and the result goes onto the canvas. On a group: over its members, before the group's own `data-umber-effect`.
|
|
1772
|
+
- **A pass is an effect** (`umber.effect`): the same slots and options (`data-umber-<effect>-<option>` on the element that lists it). Vertex code is left out (said once).
|
|
1773
|
+
- In a pass: `uv` / `vUv` run over the surface, (0,0) top-left; `sampleImage(uv)` is the step before (straight alpha); `uSize` is the surface in **device px** (`1.0 / uSize` is one pixel); `uTime`, `uViewport`, `uDpr`, `uCanvas`, `uScrollVelocity`, `uRect` (the surface, viewport px) and `uMouse` (0..1 over the surface; a pass that reads it wakes on pointer moves). `uProgress` is 0: pass `umber.progress(el)` as a uniform instead.
|
|
1640
1774
|
- **`previous(uv)`**: what this pass wrote last frame at that point of the page, moved by the scroll (with Lenis or native scroll alike), so a trail stays on the content instead of smearing. Fixed elements leave their trail sliding.
|
|
1641
1775
|
- **`toneMap(rgb)`** rolls light above 1.0 off smoothly; a chain that calls it runs in half float (values above 1 survive between passes).
|
|
1642
1776
|
- **`fxaa(uv)`**: `sampleImage(uv)` with stair-stepped edges smoothed. Passes draw without the canvas's own antialiasing, so a turned plane's edges stair-step without it.
|
|
@@ -1655,46 +1789,46 @@ color.rgb /= max(color.a, 1e-5);
|
|
|
1655
1789
|
|
|
1656
1790
|
**Auto-merge.** Effects in a row share one program (one fetch, one draw), unless one has to read pixels the one before wrote: it has a `uv` slot, it calls `sampleImage()`, `sampleRaw()` or `fxaa()`, it runs at another `scale`, or the one before called `previous()`. Merged or not, the pixels are the same.
|
|
1657
1791
|
|
|
1658
|
-
**Frames.** Passes run only in frames Umber draws anyway: a still page stays at 0 frames per second. A `previous()` pass keeps drawing for 1.5 s after the last frame something else asked for, so a trail can fade, then sleeps too. Change `data-
|
|
1792
|
+
**Frames.** Passes run only in frames Umber draws anyway: a still page stays at 0 frames per second. A `previous()` pass keeps drawing for 1.5 s after the last frame something else asked for, so a trail can fade, then sleeps too. Change `data-umber-pass` from code and call `umber.wake()`. If no element had one when Umber last scanned (at start or at `umber.scan()`), and nothing else has loaded `chunks/fx.js` yet, call `umber.scan()` once so it loads.
|
|
1659
1793
|
|
|
1660
|
-
**Limits.** three.js layers draw straight to the canvas, under the page's passes. A plane that reads `uBackdrop` under page passes gets the frame so far, as without them. Passes add one texture the size of the canvas (two with more than one program, a pair per `previous()` pass): about 20 MB each at 2880 x 1800 in 8-bit, twice that in half float.
|
|
1794
|
+
**Limits.** three.js layers draw straight to the canvas, under the page's passes, unless they ask to be under them: `passes: true` in `umber.layer()` or `umber.view()` (`data-umber="model"` and the three module's scenes do by default), at the cost of one copy of their box per frame. A plane that reads `uBackdrop` under page passes gets the frame so far, as without them. Passes add one texture the size of the canvas (two with more than one program, a pair per `previous()` pass): about 20 MB each at 2880 x 1800 in 8-bit, twice that in half float.
|
|
1661
1795
|
|
|
1662
1796
|
---
|
|
1663
1797
|
|
|
1664
|
-
## Simulations:
|
|
1798
|
+
## Simulations: umber.sim(), umber.brush(), uFlow
|
|
1665
1799
|
|
|
1666
|
-
A simulation is a few textures (fields) that your fragment shaders step forward on the GPU: trails, ripples, a fluid, particle positions. All of it is its own small file, `chunks/sim.js`, which the engine downloads by itself (through `chunks/fx.js`) on the first `
|
|
1800
|
+
A simulation is a few textures (fields) that your fragment shaders step forward on the GPU: trails, ripples, a fluid, particle positions. All of it is its own small file, `chunks/sim.js`, which the engine downloads by itself (through `chunks/fx.js`) on the first `umber.sim()`, `umber.flow()` or effect that reads `uFlow`. A page without them never downloads it.
|
|
1667
1801
|
|
|
1668
1802
|
Two rules make it fit a page that sleeps:
|
|
1669
1803
|
|
|
1670
1804
|
- **Fixed steps per second, on every screen.** A sim steps `hz` times a second (60 by default) whatever the refresh rate: a 144 Hz screen steps on 60 of its 144 frames, a 30 Hz one twice a frame. So `* 0.96` per step means the same on every screen, with no conversion.
|
|
1671
1805
|
- **It sleeps.** A sim steps after an input (a brush stroke, the pointer when its passes read `uPointer`, `sim.set()`, `sim.wake()`) and stops once it says it is settled. Then it asks for no frames, and a still page goes back to 0 frames per second. It starts asleep too, unless it moves by itself: it has an `init`, a pass reads `uTime` or `uStep`, or `settle: false`. A sim whose passes make something out of empty fields without any of those: call `sim.wake()` once.
|
|
1672
|
-
- **It steps only where it is seen.** While every plane that reads it (a uniform holding the sim or one of its fields, or `uFlow`) is far from the screen (more than a quarter screen away), it does not step and asks for no frames, even with `settle: false` or the pointer moving; it goes on when one comes near. A sim no plane reads steps wherever it is, and so does one a pass reads (`data-
|
|
1806
|
+
- **It steps only where it is seen.** While every plane that reads it (a uniform holding the sim or one of its fields, or `uFlow`) is far from the screen (more than a quarter screen away), it does not step and asks for no frames, even with `settle: false` or the pointer moving; it goes on when one comes near. A sim no plane reads steps wherever it is, and so does one a pass reads (`data-umber-pass`, `target.draw()`) or while a layer is on screen (three.js, your own GL: what it samples can't be known), its planes far or not.
|
|
1673
1807
|
|
|
1674
1808
|
### uFlow: the page's pointer flowmap
|
|
1675
1809
|
|
|
1676
1810
|
Any effect that names `uFlow` gets one small screen-shaped texture the pointer pushes around. Nothing to declare; sample it at the pixel's place on screen:
|
|
1677
1811
|
|
|
1678
1812
|
```js
|
|
1679
|
-
|
|
1813
|
+
umber.effect("flow", {
|
|
1680
1814
|
fragment: { uv: "vec4 f = texture(uFlow, screenUv()); uv -= (f.rg * 2.0 - 1.0) * f.a * 0.06;" },
|
|
1681
1815
|
});
|
|
1682
1816
|
```
|
|
1683
1817
|
|
|
1684
|
-
- `rg * 2.0 - 1.0` is the way it was pushed (screen uv, y down), `a` how hard (0..1). It is the same encoding as the input module's `
|
|
1818
|
+
- `rg * 2.0 - 1.0` is the way it was pushed (screen uv, y down), `a` how hard (0..1). It is the same encoding as the input module's `umber.touch()`, so code written for one reads the other.
|
|
1685
1819
|
- One sim for the whole page, however many planes read it. It steps while the pointer moves and fades to exactly 0 about a second after it stops; then it sleeps.
|
|
1686
|
-
- `
|
|
1687
|
-
- **Fallback:** a fade in 8 bits never reaches 0, so the flowmap needs half-float targets. Where the GPU can't render them, `uFlow` is the input module's `
|
|
1820
|
+
- `umber.flow({ size, radius, fade, motion })` changes it (or makes it before any plane reads it) and resolves to its sim. A new `size` makes its fields again, empty. Defaults: `size` `[32, 48, 64, 64, 96, 128]` texels across (one per GPU level), `radius` 8 % of the viewport width (CSS px), `fade` 0.92 per step, `motion` 0.04 per CSS px moved.
|
|
1821
|
+
- **Fallback:** a fade in 8 bits never reaches 0, so the flowmap needs half-float targets. Where the GPU can't render them, `uFlow` is the input module's `umber.touch()` texture (drawn on the CPU), when the input module is loaded; without it `uFlow` stays still and Umber says how to fix it. Until `chunks/sim.js` is here, `uFlow` is transparent (no push).
|
|
1688
1822
|
|
|
1689
|
-
###
|
|
1823
|
+
### umber.sim(options)
|
|
1690
1824
|
|
|
1691
1825
|
```js
|
|
1692
|
-
const trail = await
|
|
1826
|
+
const trail = await umber.sim({
|
|
1693
1827
|
size: 128, // texels across; or one per GPU level 0-5: [64, 64, 96, 128, 128, 192]
|
|
1694
1828
|
next: `vec4 next(vec2 uv) { return texture(state, uv) * 0.95; }`, // one field, "state"
|
|
1695
1829
|
});
|
|
1696
|
-
|
|
1697
|
-
|
|
1830
|
+
umber.brush(trail, { radius: 30, color: [1, 1, 1, 1] }); // paints where the pointer goes
|
|
1831
|
+
umber.effect("ink", { uniforms: { uInk: trail }, fragment: { color: "color.rgb = mix(color.rgb, vec3(0.0), texture(uInk, screenUv()).r);" } });
|
|
1698
1832
|
```
|
|
1699
1833
|
|
|
1700
1834
|
- **`next`** defines `vec4 next(vec2 uv)`: the field's next value at `uv`. The old value is `texture(state, uv)`. It is state, not colour: what you return is stored as it is (no premultiplying, no clamping on half and float).
|
|
@@ -1704,7 +1838,7 @@ gl.effect("ink", { uniforms: { uInk: trail }, fragment: { color: "color.rgb = mi
|
|
|
1704
1838
|
- **Several fields and passes:** each field is a sampler of its own name in every pass; each pass writes one field (`into`) and can read its old value. `iterations` runs a pass several times per step (a pressure solve), one number or one per GPU level. `output` is the field `sim.texture` gives.
|
|
1705
1839
|
|
|
1706
1840
|
```js
|
|
1707
|
-
const sim = await
|
|
1841
|
+
const sim = await umber.sim({
|
|
1708
1842
|
fields: { velocity: {}, dye: { size: [128, 192, 256, 384, 512, 640] }, pressure: {} },
|
|
1709
1843
|
output: "dye",
|
|
1710
1844
|
passes: [
|
|
@@ -1719,14 +1853,14 @@ const sim = await gl.sim({
|
|
|
1719
1853
|
- **Its textures change every step** (each field is two targets, swapped after each pass, never copied). As an effect uniform that is automatic; elsewhere (three.js, your own GL) read `sim.texture` again each frame you draw.
|
|
1720
1854
|
- A context that comes back makes the fields again and starts every sim from its `init`.
|
|
1721
1855
|
|
|
1722
|
-
###
|
|
1856
|
+
### umber.brush(sim, options)
|
|
1723
1857
|
|
|
1724
1858
|
Soft round stamps into one field of a sim, up to 16 a step in one pass.
|
|
1725
1859
|
|
|
1726
1860
|
```js
|
|
1727
|
-
const push =
|
|
1728
|
-
const dye =
|
|
1729
|
-
dye
|
|
1861
|
+
const push = umber.brush(sim, { field: "velocity", radius: 40, color: [0, 0, 0, 0], motion: 8 }); // follows the pointer
|
|
1862
|
+
const dye = umber.brush(sim, { field: "dye", radius: 40, color: [0.07, 0.03, 0.01, 1] });
|
|
1863
|
+
dye?.paint(200, 300); // one stamp at viewport CSS px 200, 300 at the next step (pointer: false brushes only paint here)
|
|
1730
1864
|
```
|
|
1731
1865
|
|
|
1732
1866
|
- `color` is added at the centre with a gaussian falloff of `radius` CSS px (`mode: "add"`, the default), or mixed towards by its alpha (`mode: "mix"`).
|
|
@@ -1735,44 +1869,44 @@ dye.paint(200, 300); // one stamp at viewport CSS px 200, 300 at the next step
|
|
|
1735
1869
|
|
|
1736
1870
|
### Quality per GPU
|
|
1737
1871
|
|
|
1738
|
-
`size` and `iterations` take one value per GPU level, 0 (software) to 5 (`
|
|
1872
|
+
`size` and `iterations` take one value per GPU level, 0 (software) to 5 (`umber.info.gpu.level`, `?umber-gpu=` to try one), so a phone gets a smaller grid and fewer pressure iterations than a desktop. The gallery's fluid (`examples/sim/fluid.js`) shows the pattern: a 48-texel grid with 6 iterations at level 0, 160 with 24 at level 5.
|
|
1739
1873
|
|
|
1740
1874
|
### Particles
|
|
1741
1875
|
|
|
1742
|
-
Positions live in a sim (`shape: "square"`, `type: "float"`): one texel per particle, `xy` its position, `zw` its speed. Umber ships no particle renderer: draw the points yourself in a `data-
|
|
1876
|
+
Positions live in a sim (`shape: "square"`, `type: "float"`): one texel per particle, `xy` its position, `zw` its speed. Umber ships no particle renderer: draw the points yourself in a `data-umber="layer"` (raw WebGL or three.js on Umber's context) reading `sim.texture` with `texelFetch`, and `ctx.wake()` when `sim.steps` changed. `examples/sim/particles.html` does it in a dozen lines.
|
|
1743
1877
|
|
|
1744
1878
|
---
|
|
1745
1879
|
|
|
1746
|
-
## Getting ready ahead:
|
|
1880
|
+
## Getting ready ahead: umber.preload(), umber.warm(), placeholders
|
|
1747
1881
|
|
|
1748
|
-
A GL element shows its DOM until its texture is on the GPU and its program is compiled. On a fast page that is a frame or two; on a page change it can be a blank image, or a hitch on the first frame. These calls do that work earlier. All of it is its own small file, `chunks/warm.js`, which the engine downloads on the first call (or the first `data-
|
|
1882
|
+
A GL element shows its DOM until its texture is on the GPU and its program is compiled. On a fast page that is a frame or two; on a page change it can be a blank image, or a hitch on the first frame. These calls do that work earlier. All of it is its own small file, `chunks/warm.js`, which the engine downloads on the first call (or the first `data-umber-placeholder`); the offscreen draws also bring `chunks/fx.js`. Nothing here ever blocks the page: images decode off the main thread, uploads go in idle moments, and nothing rejects.
|
|
1749
1883
|
|
|
1750
1884
|
Both calls return a promise that is also the progress: `p.value` goes from 0 to 1 and never back (a Signal, so it can even be a uniform), and the optional `fn(v)` hears each step. With GL off they resolve at once with `value` 1: the DOM is the content.
|
|
1751
1885
|
|
|
1752
|
-
###
|
|
1886
|
+
### umber.preload(what): the next page, before it is on the page
|
|
1753
1887
|
|
|
1754
1888
|
```js
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
|
|
1759
|
-
|
|
1889
|
+
umber.preload("/work/dunes"); // a page URL: fetched, read, its [data-umber] elements made ready
|
|
1890
|
+
umber.preload(["/img/a.jpg", "/img/b.jpg"]); // image URLs
|
|
1891
|
+
umber.preload(data.next.container); // a container (detached is fine)
|
|
1892
|
+
umber.preload(doc); // a parsed Document
|
|
1893
|
+
umber.preload(data.next); // Barba's next: { container }, { html } or { url }
|
|
1760
1894
|
```
|
|
1761
1895
|
|
|
1762
|
-
For each `[data-
|
|
1896
|
+
For each `[data-umber]` element it finds, Umber:
|
|
1763
1897
|
|
|
1764
|
-
- fetches and decodes its image and puts it on the GPU, under the key the element will ask for when it arrives: `data-
|
|
1898
|
+
- fetches and decodes its image and puts it on the GPU, under the key the element will ask for when it arrives: `data-umber-src` as written, else the `srcset` candidate the browser will pick at this screen and DPR (from `sizes`; the same pick a `data-umber-id` flight uses). In a `<picture>` with `<source>`s the browser may pick another file, so those are not guessed;
|
|
1765
1899
|
- compiles the program its effects make (when they are defined already), and draws it once into a tiny offscreen target, so the driver finishes its work now and not on the first real frame;
|
|
1766
|
-
- shows its `data-
|
|
1900
|
+
- shows its `data-umber-placeholder` preview right away (below).
|
|
1767
1901
|
|
|
1768
1902
|
When the elements arrive, their planes take the texture and the program that are waiting: no fetch, no upload, no compile on the swap frame. A texture nobody takes is freed after 20 s (it counts in the texture budget meanwhile). A page that is not shown yet has no layout, so an image found ahead is decoded for the screen at this DPR (or for its `<img>`'s `sizes` width, when it has one), not whole; once its plane is measured, a texture much bigger than it draws is decoded again, smaller, in an idle moment.
|
|
1769
1903
|
|
|
1770
1904
|
### Hover intent (opt-in)
|
|
1771
1905
|
|
|
1772
1906
|
```js
|
|
1773
|
-
|
|
1774
|
-
|
|
1775
|
-
|
|
1907
|
+
umber.preload({ hover: true }); // every link to another page of this site
|
|
1908
|
+
umber.preload({ hover: "a.project-link" }); // only these
|
|
1909
|
+
umber.preload({ hover: false }); // off
|
|
1776
1910
|
```
|
|
1777
1911
|
|
|
1778
1912
|
When the pointer slows down over a link (it stays on it about 65 ms without crossing it fast), or a finger or pen touches one, that page is fetched and preloaded, once per URL. Off on Save-Data and 2g connections. Links you only pass over cost nothing.
|
|
@@ -1784,38 +1918,38 @@ The next page's HTML is usually being fetched while the old page leaves. Preload
|
|
|
1784
1918
|
```js
|
|
1785
1919
|
// Barba: the leave animation and the preload run side by side (keep the braces: a hook
|
|
1786
1920
|
// that returns the promise makes Barba wait for it).
|
|
1787
|
-
barba.hooks.leave((data) => {
|
|
1921
|
+
barba.hooks.leave((data) => { umber.preload(data.next.url.href); });
|
|
1788
1922
|
// or, once Barba has the HTML: return the promise, so Barba waits before the swap
|
|
1789
1923
|
// (until its images are downloaded and decoded: a download has no time limit).
|
|
1790
|
-
barba.hooks.beforeEnter((data) =>
|
|
1924
|
+
barba.hooks.beforeEnter((data) => umber.preload(data.next.container));
|
|
1791
1925
|
|
|
1792
1926
|
// Swup 4
|
|
1793
|
-
swup.hooks.on("visit:start", (visit) =>
|
|
1794
|
-
swup.hooks.on("page:load", (visit, { page }) =>
|
|
1927
|
+
swup.hooks.on("visit:start", (visit) => umber.preload(visit.to.url));
|
|
1928
|
+
swup.hooks.on("page:load", (visit, { page }) => umber.preload(page.html ? { html: page.html } : null));
|
|
1795
1929
|
```
|
|
1796
1930
|
|
|
1797
|
-
`
|
|
1931
|
+
`umber.transition()` and `data-umber-id` flights work the same with or without it; a preloaded flight target simply lands on a sharp texture at once.
|
|
1798
1932
|
|
|
1799
|
-
###
|
|
1933
|
+
### umber.warm(root?): this page, with progress (a preloader)
|
|
1800
1934
|
|
|
1801
1935
|
```js
|
|
1802
|
-
const p =
|
|
1936
|
+
const p = umber.warm(null, (v) => (bar.style.scale = `${v} 1`));
|
|
1803
1937
|
await p; // every plane can draw (each waits 5 s at most)
|
|
1804
1938
|
loader.remove();
|
|
1805
1939
|
```
|
|
1806
1940
|
|
|
1807
1941
|
Every plane in `root` (a selector or element; default: the whole page) loads its image or text even when far from the screen, compiles, and is drawn once offscreen. Use it behind a loading screen; without one, the normal "load what comes near" is the better default.
|
|
1808
1942
|
|
|
1809
|
-
### data-
|
|
1943
|
+
### data-umber-placeholder: a blurred preview until the file is there
|
|
1810
1944
|
|
|
1811
1945
|
```html
|
|
1812
|
-
<div data-
|
|
1946
|
+
<div data-umber="image" data-umber-placeholder="UF-rWpqZh3dVQ2..."><img src="dunes.jpg" alt="Dunes" width="1600" height="1000"></div>
|
|
1813
1947
|
```
|
|
1814
1948
|
|
|
1815
1949
|
The attribute holds a tiny picture (about 50 characters: a grid 6 cells on its long side (6 x 4 for a 3:2 picture), 4 bits per colour channel). Umber draws it, smoothly scaled, as the background of the `<img>` until the file has loaded; the image then paints over it. Make the string once, in the browser console of any page with Umber:
|
|
1816
1950
|
|
|
1817
1951
|
```js
|
|
1818
|
-
await
|
|
1952
|
+
await umber.placeholder("/img/dunes.jpg"); // "UF-rWpqZh3dVQ2..."
|
|
1819
1953
|
```
|
|
1820
1954
|
|
|
1821
1955
|
- It shows while GL is on (the preview is decoded by `chunks/warm.js`). With GL off the `<img>` loads as usual.
|
|
@@ -1825,21 +1959,151 @@ await gl.placeholder("/img/dunes.jpg"); // "UF-rWpqZh3dVQ2..."
|
|
|
1825
1959
|
|
|
1826
1960
|
- An image file much bigger than it is drawn is decoded at the drawn size (its box at this DPR, with 25 % room for a zoom), not the file's: a 2400 px still shown at 460 px takes a twentieth of the GPU memory. When half or a quarter of the file is within a tenth below that size, that is taken instead (its mip levels are then the file's own, so a smaller element showing the same file looks as if the whole file were there). When a plane showing it grows past that (a resize, a bigger plane with the same `src`), it is decoded again, bigger, from the HTTP cache; the smaller one shows meanwhile.
|
|
1827
1961
|
- A file bigger than the GPU can take is drawn shrunk, with an `[umber]` warning that names the file and the limit.
|
|
1828
|
-
- One GPU memory budget per device (`
|
|
1829
|
-
- When what is near the screen is still over the budget after that, one `[umber]` warning gives the images' and the targets' and frames' share, and names the largest images. Serve smaller files (`srcset` and `sizes`, or a smaller `data-
|
|
1962
|
+
- One GPU memory budget per device (`umber.info.gpu.textureBudget`) covers image textures, render targets (groups, passes, sims, snapshots, `umber.leave` copies, your `umber.target`s) and cached video frames (`data-umber-scrub`). Over it, Umber frees what it can make again, in this order: render targets released in the last 5 s, image textures far from the screen (their DOM image shows until the visitor scrolls back), then cached frames (a scrubbed video keeps fewer frames around the playhead from then on). Targets in use are never freed: the site made them. `umber.info.gpuMB` is the total.
|
|
1963
|
+
- When what is near the screen is still over the budget after that, one `[umber]` warning gives the images' and the targets' and frames' share, and names the largest images. Serve smaller files (`srcset` and `sizes`, or a smaller `data-umber-src`), and make targets smaller. Render targets alone past the budget have their own warning (`umber.info.targetMB`).
|
|
1830
1964
|
- GL text far from the screen is painted in idle moments too (nearest first), so an anchor jump lands on text that is ready.
|
|
1831
1965
|
|
|
1832
1966
|
---
|
|
1833
1967
|
|
|
1968
|
+
## Preparing pictures at build time: `umber assets`, Vite, Astro
|
|
1969
|
+
|
|
1970
|
+
Umber can do the GPU's work on your pictures when you build the site, not in your visitor's browser. Each picture Umber draws (the `<img>`, `srcset` and `data-umber-src` inside a `[data-umber]` element) is turned into the compressed texture formats GPUs draw directly, with all their mip levels made ahead:
|
|
1971
|
+
|
|
1972
|
+
| File | For | GPU memory |
|
|
1973
|
+
| --- | --- | --- |
|
|
1974
|
+
| `<key>.bc1.ktx2` or `<key>.bc7.ktx2` | desktop GPUs (Windows, Linux, and Macs, Apple Silicon included) | an eighth (BC1, opaque pictures) or a quarter (BC7) of the decoded picture |
|
|
1975
|
+
| `<key>.astc.ktx2` | phones and tablets | a quarter or less (the block size suits the picture) |
|
|
1976
|
+
| `<key>.etc2.ktx2` | Android | an eighth (a quarter with alpha) |
|
|
1977
|
+
| `<key>.avif` | the page's own picture where the browser shows AVIF, and a GPU with none of the three | as before (decoded by the browser) |
|
|
1978
|
+
|
|
1979
|
+
Each picture gets the smallest file that stays at least as close to the original as a quality floor (`quality`, 40 dB by default): BC1 or BC7, the largest ASTC block that holds the floor, and blocks tuned so they compress well. The files are compressed inside (each mip level deflated), so they are small on any host.
|
|
1980
|
+
|
|
1981
|
+
In the browser, Umber asks the GPU once which format it draws, fetches only that file, and only the part of it the picture needs: the file holds the smallest levels first, so a picture shown at 500 px fetches the levels up to 500 px, not the full 1600 px one. The browser unpacks those levels with its own built-in decompressor and they go to the GPU as they are: nothing to decode, no mipmaps to make, no transcoder to download.
|
|
1982
|
+
|
|
1983
|
+
By default (`domImages: "tiny"`), each `<img>` Umber draws gets a small placeholder of its picture, at most 512 px on its longer side, while GL loads, and the full AVIF wherever GL won't draw it:
|
|
1984
|
+
|
|
1985
|
+
```html
|
|
1986
|
+
<picture data-umber-avif>
|
|
1987
|
+
<source type="image/avif" media="(scripting: enabled)" srcset="/_umber/<key>.tiny512q50.avif 0.32x" data-umber-tiny>
|
|
1988
|
+
<source type="image/avif" srcset="/_umber/<key>.avif">
|
|
1989
|
+
<img src="photo.jpg" alt="...">
|
|
1990
|
+
</picture>
|
|
1991
|
+
```
|
|
1992
|
+
|
|
1993
|
+
A visitor whose GPU draws the picture downloads the placeholder (a few KB) and the GPU file, never the full AVIF too: on image pages that is a third to almost half fewer bytes, and the first screen is drawn sooner. The placeholder is described so the `<img>` keeps the full picture's size, so nothing moves when it changes. Wherever GL won't draw the picture, Umber takes the placeholder out and the browser shows the full AVIF in its place once it has loaded: no WebGL2, GL turned off (`?umber=off`, reduced motion with `reducedMotion: "off"`, Save-Data, a `media` that doesn't match, a domain without a licence), a picture that fails, `umber.destroy()`, router pages while GL is off, and printing. With JavaScript off the placeholder never applies (its `media` needs scripting), so the browser shows the full AVIF. If Umber's script never runs at all (blocked, its server down, an error before `createUmber()`), a small script the build adds to the page, a file of your site's own (`/_umber/images.<hash>.js`), shows the full pictures 3 seconds after the page loaded.
|
|
1994
|
+
|
|
1995
|
+
Your `<img>` stays exactly as you wrote it: its `src` is your original file, so search engines index that, and screen readers and browsers without AVIF get it too. A browser that shows AVIF but doesn't know `(scripting: enabled)` (before Chrome 120, Firefox 113, Safari 17) skips the placeholder and shows the full AVIF. An `<img>` already in a `<picture>` gets the sources first in it, unless one of its sources has its own `type` or `media`: then the page already picks and nothing changes. A picture whose AVIF isn't smaller than its file gets no sources at all.
|
|
1996
|
+
|
|
1997
|
+
What it costs:
|
|
1998
|
+
|
|
1999
|
+
- "Save image" on a picture saves the placeholder while GL draws it, not the full picture.
|
|
2000
|
+
- Visitors without GL download the placeholder and then the full AVIF: slightly more bytes, and the full picture shows slightly later.
|
|
2001
|
+
- On a slow connection the first screen shows soft pictures until GL draws them (instead of empty spots).
|
|
2002
|
+
|
|
2003
|
+
To turn it off, set `domImages: "avif"` (`--dom-images avif` on the command line): each `<img>` gets only the full AVIF `<source>`, and the page gets no placeholder and no script. `tinySize` (512) and `tinyQuality` (50) set the placeholder's longer side and its AVIF quality.
|
|
2004
|
+
|
|
2005
|
+
`umber.css` gives the added `<picture>` `display: contents`, so it makes no box and your layout stays as it was. One thing to check: a CSS rule with a child selector (`.card > img`) no longer matches an `<img>` that got wrapped. Write it `.card img`, or set `domImages: "source"` to leave your `<img>`s alone.
|
|
2006
|
+
|
|
2007
|
+
The tool also adds one tag to each page, `<meta name="umber-assets" content="/_umber/assets.<hash>.json">` (with a preload of it), which tells Umber where the prepared files are. You never add anything per picture.
|
|
2008
|
+
|
|
2009
|
+
### Setup
|
|
2010
|
+
|
|
2011
|
+
It ships with `@occluze/umber`; installing the package is enough (npm picks the build for your computer: Windows, macOS and Linux, x64 and arm64). Nothing to install for Rust or anything else.
|
|
2012
|
+
|
|
2013
|
+
```js
|
|
2014
|
+
// Astro: astro.config.mjs
|
|
2015
|
+
import { defineConfig } from "astro/config";
|
|
2016
|
+
import umberAstro from "@occluze/umber/astro";
|
|
2017
|
+
export default defineConfig({ integrations: [umberAstro()] });
|
|
2018
|
+
```
|
|
2019
|
+
|
|
2020
|
+
```js
|
|
2021
|
+
// Vite: vite.config.js
|
|
2022
|
+
import umberAssets from "@occluze/umber/vite";
|
|
2023
|
+
export default { plugins: [umberAssets()] };
|
|
2024
|
+
```
|
|
2025
|
+
|
|
2026
|
+
```bash
|
|
2027
|
+
# Any other build (a static site generator, plain HTML): after it, on the folder it wrote
|
|
2028
|
+
npx umber assets dist
|
|
2029
|
+
npx umber assets dist --base-url /docs/ # the site lives under /docs/
|
|
2030
|
+
```
|
|
2031
|
+
|
|
2032
|
+
If your computer or build server has no build of the tool (it runs on Windows, macOS and glibc Linux, x64 and arm64; not Alpine's musl), or it was installed with `--omit=optional`, your build still finishes: the output says why, and the site keeps its plain images.
|
|
2033
|
+
|
|
2034
|
+
Astro and Vite run it after `astro build` / `vite build`, on the output folder; `astro dev` and `vite dev` are left alone (pictures load as they always do there). Astro's own `<Image />` and `<Picture />` files are prepared like any other picture. With Astro and Vite it also minifies the GLSL of your own effects while it bundles them (the `fragment` and `vertex` parts of `umber.effect()`, and template literals marked `/* glsl */`): comments, indentation and needless spaces go, every line stays where it was. And it puts Umber's chunks in the built site (`<assets>/umber@<version>/chunks/`) and points the engine at them, so the site loads no Umber code from another origin and a strict `script-src 'self'` works (Hosting, Content Security Policy); `astro dev` and `vite dev` load them from the CDN.
|
|
2035
|
+
|
|
2036
|
+
The prepared files go in `_umber/` inside the output folder. Their names are content hashes, so they can be cached forever: on Cloudflare Pages, add to `_headers`:
|
|
2037
|
+
|
|
2038
|
+
```
|
|
2039
|
+
/_umber/*
|
|
2040
|
+
Cache-Control: public, max-age=31536000, immutable
|
|
2041
|
+
```
|
|
2042
|
+
|
|
2043
|
+
### Options
|
|
2044
|
+
|
|
2045
|
+
Every front end takes the same options (the command line spells them `--formats bc7,astc`, `--no-avif`, `--dom-images avif`, `--effort best`...):
|
|
2046
|
+
|
|
2047
|
+
```js
|
|
2048
|
+
umberAstro({
|
|
2049
|
+
formats: ["bc7", "astc", "etc2"], // which GPU files to make: desktop (BC1 or BC7), ASTC, ETC2 (all three by default)
|
|
2050
|
+
quality: 40, // the quality floor, dB: higher is closer to the original, and larger
|
|
2051
|
+
avif: true, // the AVIF: a <source> for the page's <img>, and for GPUs with none of the formats
|
|
2052
|
+
avifQuality: 80, // 1 to 100
|
|
2053
|
+
domImages: "tiny", // a placeholder while GL loads; "avif": the full AVIF only; "source": the <img>s as written
|
|
2054
|
+
tinySize: 512, // domImages "tiny": the placeholder's longer side, px
|
|
2055
|
+
tinyQuality: 50, // domImages "tiny": the placeholder's AVIF quality, 1 to 100
|
|
2056
|
+
effort: "normal", // "fast", "normal" or "best": slower is closer to the source
|
|
2057
|
+
maxSize: 4096, // the largest level's longest side, px
|
|
2058
|
+
all: false, // every picture in the output, not only the ones Umber draws
|
|
2059
|
+
fonts: false, // true: also the fonts of GL text, painted from their outlines (below)
|
|
2060
|
+
shaders: true, // Vite and Astro: minify your effects' GLSL
|
|
2061
|
+
chunks: true, // Vite and Astro: serve Umber's chunks from the site (false: from the CDN)
|
|
2062
|
+
folder: "_umber", // where the files go, inside the output folder
|
|
2063
|
+
cache: "node_modules/.cache/umber-assets", // false: make every picture again
|
|
2064
|
+
});
|
|
2065
|
+
```
|
|
2066
|
+
|
|
2067
|
+
A picture that has not changed is not made again: it is copied from the cache folder (its key is a hash of its bytes and the options). The first build takes several seconds a picture (it tries formats and settings against the floor); later builds take a moment.
|
|
2068
|
+
|
|
2069
|
+
### What it costs, and what you get
|
|
2070
|
+
|
|
2071
|
+
Measured on a page of 48 photos and cut-outs (1600 px JPEG and 900 px PNG with alpha, at 1440 x 900; median of 3 runs; the full table is in [architecture.md](../architecture.md)):
|
|
2072
|
+
|
|
2073
|
+
| | Chromium | WebKit | Firefox |
|
|
2074
|
+
| --- | --- | --- | --- |
|
|
2075
|
+
| First screen drawn | 446 → 422 ms | 1401 → 887 ms | 884 → 805 ms |
|
|
2076
|
+
| Pictures after a jump to the end | 231 → 156 ms | 1030 → 281 ms | 249 → 125 ms |
|
|
2077
|
+
| GPU memory | 54.1 → 19.9 MB | 54.1 → 19.9 MB | 54.1 → 19.9 MB |
|
|
2078
|
+
| Main-thread time uploading | 24 → 8 ms | 41 → 3 ms | 25 → 12 ms |
|
|
2079
|
+
| Downloaded | 15.1 → 10.7 MB | 15.1 → 10.7 MB in Safari | 15.1 → 10.7 MB |
|
|
2080
|
+
|
|
2081
|
+
- **Looks.** The page without GL looks the same as before. The GL pictures are as close to the original as the quality floor says (40 dB: differences you have to look for side by side, mostly in film grain).
|
|
2082
|
+
- **A browser that can't show AVIF** (Safari on macOS before 13) downloads your original, plus the GPU file, more than before. The test WebKit on Windows is such a browser: 21.2 MB there.
|
|
2083
|
+
|
|
2084
|
+
- **Colour.** A picture with a colour profile other than sRGB (Display P3, Adobe RGB) is converted to sRGB, as the browser does when it shows it.
|
|
2085
|
+
- **SVG.** Left as it is: Umber already draws an SVG sharp at the size it is shown. Made at build it came out further from the browser's own drawing at every scale, and larger than the SVG itself.
|
|
2086
|
+
- **What stays as it was.** Pictures on other domains, video, GL text and pictures Umber does not draw. A picture the manifest does not name, or a prepared file that fails to load, is drawn from its `<img>` as before.
|
|
2087
|
+
|
|
2088
|
+
### GL text painted from the font's outlines (`fonts: true`)
|
|
2089
|
+
|
|
2090
|
+
The same tool can prepare the fonts of your GL text (`data-umber="text"`). For each `@font-face` font whose file is in the site (WOFF2, WOFF, TTF or OTF), it writes each letter's outline (its curves) to `_umber/<key>.glyphs`, keeping only the characters your GL text uses plus printable ASCII; a variable font is prepared at each weight your CSS names. Umber then paints those letters on the GPU straight from their curves, where the browser placed them: sharp at any size and under any zoom or scale, with a few KB of tables instead of glyph pictures. Effects and `glyph()` work on it as before.
|
|
2091
|
+
|
|
2092
|
+
**When to use which.** Leave it off for text that sits still, moves with the page, or fades: the atlas is what the browser would paint. Turn it on for text you animate letter by letter at large sizes, scale up a lot, zoom into or distort with an effect, where the atlas would have to paint it again or show it soft.
|
|
2093
|
+
|
|
2094
|
+
It is off by default: at rest, the glyph atlas (Umber's default) matches the browser's own text more closely in every browser, because it uses the browser's own text rasterizer, which fits letters to the pixel grid and, on Windows, draws coloured sub-pixel edges. Turn it on for text that is scaled, zoomed or turned, where the atlas would have to paint it again or show it soft. Until a prepared font's file is in (with `chunks/curves.js`, which Umber downloads only for a page whose GL text uses a prepared font), and for what curves can't stand for, text is drawn from the atlas: right-to-left text, small caps, emoji, words where the font joins letters (fi, fl, ff) and a character the prepared font lacks.
|
|
2095
|
+
|
|
2096
|
+
---
|
|
2097
|
+
|
|
1834
2098
|
## Instances: one plane, drawn many times
|
|
1835
2099
|
|
|
1836
|
-
`data-
|
|
2100
|
+
`data-umber-instances` draws a plane many times in **one draw call**, and tells its effects which one they are drawing. Tiles that come apart, letters of real DOM text, copies that trail behind a plane, particles where it has ink. All of it is its own small file, `chunks/instances.js`, which the engine downloads by itself on the first element (or effect) that asks. Until it is here, that element shows its DOM. A page without instances never downloads it.
|
|
1837
2101
|
|
|
1838
2102
|
```html
|
|
1839
|
-
<div data-
|
|
2103
|
+
<div data-umber="image" data-umber-instances="tiles 16x10" data-umber-effect="shatter"><img src="dunes.jpg" alt="Dunes"></div>
|
|
1840
2104
|
```
|
|
1841
2105
|
```js
|
|
1842
|
-
|
|
2106
|
+
umber.effect("shatter", {
|
|
1843
2107
|
play: "uApart",
|
|
1844
2108
|
options: { trigger: "hover" },
|
|
1845
2109
|
attributes: { aSeed: 3 }, // 3 random numbers per tile, stable across visits
|
|
@@ -1856,37 +2120,38 @@ gl.effect("shatter", {
|
|
|
1856
2120
|
|
|
1857
2121
|
### The modes
|
|
1858
2122
|
|
|
1859
|
-
| `data-
|
|
2123
|
+
| `data-umber-instances` | What is drawn | GLSL inputs |
|
|
1860
2124
|
|---|---|---|
|
|
1861
2125
|
| `"64"` | 64 copies of the plane. Your vertex code places each. | `instance`, `uInstances` |
|
|
1862
2126
|
| `"tiles 24x16"` | The plane cut into 24 x 16 tiles, each its own quad. At rest they are the image, seamless. | `tile` (vec4: column, row, columns, rows), `tileCenter` (vec2, uv) |
|
|
1863
|
-
| `"chars"`, `"words"`, `"lines"` | GL text (`data-
|
|
2127
|
+
| `"chars"`, `"words"`, `"lines"` | GL text (`data-umber="text"`) as one quad per character, word or line. | `unitValue` (vec4: the unit's t, x, y, z from `plane.text`; `.x` is t, as in `glyph()`'s `charValue`), `unitBox` (vec4: its box in uv) |
|
|
1864
2128
|
| `"echo 6"`, `"echo 6 delay 0.05"` | The plane plus 5 copies where it was 0.05 s, 0.1 s... ago: a trail when it moves (scroll, an animation). Copies that caught up are not drawn. | `echoOffset` (vec2: px from the plane to this copy); `instance` 0 is the plane itself, drawn on top |
|
|
1865
2129
|
| `"ink 3000"`, `"ink 3000 size 3 luma"` | 3000 particles, each a `size` px piece of the plane, seeded where it has ink: its alpha, or its brightness with `luma`. | `inkPoint` (vec4: uv x, uv y, ink 0..1, found) |
|
|
2130
|
+
| `"points 20000"`, `"points 20000 size 3"` | 20000 particles (10000 without a count, up to 65536), each a `size` px piece of the plane, spread evenly at random over it. Placed on the GPU from their index: no seed pass, no extra chunk. Move them in vertex code (`pos`, or `uv` from a `umber.sim()` field with `texelFetch(uSim, ivec2(int(instance) % 256, int(instance) / 256), 0)`); give each its own look from `point.zw`. | `point` (vec4: uv x, uv y, and two random numbers 0..1 of its own), `pointUv` (vec2: 0..1 across the particle; `alpha *= step(length(pointUv - 0.5), 0.5);` makes it round) |
|
|
1866
2131
|
|
|
1867
2132
|
`instance` (0 .. `uInstances` - 1) and `uInstances` are there in every mode. Every input is there in vertex **and** fragment code. They are plain globals: a local of the same name in your code just hides it.
|
|
1868
2133
|
|
|
1869
2134
|
An effect can ask for instances itself, with the same words or an object. The element's own attribute wins:
|
|
1870
2135
|
|
|
1871
2136
|
```js
|
|
1872
|
-
|
|
2137
|
+
umber.effect("trail", {
|
|
1873
2138
|
instances: { echo: 8, delay: 0.035 }, // or "echo 8 delay 0.035"
|
|
1874
2139
|
fragment: { alpha: "if (instance > 0.5) alpha *= 0.4 * (1.0 - instance / uInstances);" },
|
|
1875
2140
|
});
|
|
1876
2141
|
```
|
|
1877
2142
|
|
|
1878
|
-
From JS, `
|
|
2143
|
+
From JS, `umber.add(el, { instances: "tiles 12x8", effects: ["shatter"] })` writes the attribute.
|
|
1879
2144
|
|
|
1880
2145
|
### Text units
|
|
1881
2146
|
|
|
1882
2147
|
`"chars"` reads the same units as `plane.text` (their boxes, and the four numbers `t`, `x`, `y`, `z` any library tweens). Write them with GSAP or Umber's own tween; the quads follow, and a still page stays at 0 frames per second:
|
|
1883
2148
|
|
|
1884
2149
|
```js
|
|
1885
|
-
|
|
2150
|
+
umber.effect("letters", {
|
|
1886
2151
|
vertex: { main: "pos.y += (1.0 - unitValue.x) * uSize.y * 0.6;" }, // .x is t
|
|
1887
2152
|
fragment: { alpha: "alpha *= unitValue.x;" },
|
|
1888
2153
|
setup(ctx) {
|
|
1889
|
-
const go = () => ctx.plane.text
|
|
2154
|
+
const go = () => ctx.plane.text?.chars.forEach((c, i) => c.tween("t", { value: 1, delay: i * 0.05 }));
|
|
1890
2155
|
if (ctx.plane.text?.chars.length) go();
|
|
1891
2156
|
return ctx.plane.on("text", go); // painted (again): a rewrap keeps t by index
|
|
1892
2157
|
},
|
|
@@ -1901,7 +2166,7 @@ gl.effect("letters", {
|
|
|
1901
2166
|
`attributes` declares `in` attributes of the vertex shader, one value per instance. A size (1-4) fills them with a stable random 0..1; a function fills them from the instance:
|
|
1902
2167
|
|
|
1903
2168
|
```js
|
|
1904
|
-
|
|
2169
|
+
umber.effect("fan", {
|
|
1905
2170
|
attributes: { aSeed: 2, aTurn: (i, n) => (i - (n - 1) / 2) * 0.04 },
|
|
1906
2171
|
vertex: { main: "pos.x += aSeed.x * 20.0; /* aTurn: float */" },
|
|
1907
2172
|
});
|
|
@@ -1910,19 +2175,22 @@ gl.effect("fan", {
|
|
|
1910
2175
|
Change them later through `plane.instances`; they go to the GPU on the next frame:
|
|
1911
2176
|
|
|
1912
2177
|
```js
|
|
1913
|
-
const
|
|
1914
|
-
|
|
1915
|
-
|
|
1916
|
-
|
|
1917
|
-
|
|
2178
|
+
const inst = umber.plane(el)?.instances; // undefined on a plane without instances
|
|
2179
|
+
if (inst) {
|
|
2180
|
+
inst.set("aTurn", myFloat32Array); // count x size numbers
|
|
2181
|
+
const seed = inst.data("aSeed"); // or in place (null when no effect declares it)...
|
|
2182
|
+
if (seed) seed[0] = 0.5;
|
|
2183
|
+
inst.update("aSeed"); // ...then say so
|
|
2184
|
+
inst.count; inst.mode;
|
|
2185
|
+
}
|
|
1918
2186
|
```
|
|
1919
2187
|
|
|
1920
|
-
A **data texture** works too: any texture uniform (a `
|
|
2188
|
+
A **data texture** works too: any texture uniform (a `umber.target()`, the input module's `umber.texture({ data, width, height })`: numbers alone have no size and throw) that your vertex code names is declared in the vertex shader for you. Read one texel per instance:
|
|
1921
2189
|
|
|
1922
2190
|
```js
|
|
1923
|
-
const positions = await
|
|
1924
|
-
// or numbers you fill yourself (input module):
|
|
1925
|
-
|
|
2191
|
+
const positions = await umber.target({ width: 64, height: 64, type: "float" });
|
|
2192
|
+
// or numbers you fill yourself (input module): umber.texture({ data: new Float32Array(64 * 64 * 4), width: 64, height: 64 })
|
|
2193
|
+
umber.effect("swarm", {
|
|
1926
2194
|
instances: 4096,
|
|
1927
2195
|
uniforms: { uPositions: positions },
|
|
1928
2196
|
vertex: { main: "vec4 p = texelFetch(uPositions, ivec2(int(instance) % 64, int(instance) / 64), 0); pos.xy += p.xy;" },
|
|
@@ -1931,11 +2199,11 @@ gl.effect("swarm", {
|
|
|
1931
2199
|
|
|
1932
2200
|
### What to know
|
|
1933
2201
|
|
|
1934
|
-
- **One draw per plane**, at its place in the page's order. No sorting,
|
|
2202
|
+
- **One draw per plane**, at its place in the page's order. No sorting, and an instanced plane is never batched with its neighbours: instances draw in their own order (echo: oldest first, the plane last).
|
|
1935
2203
|
- **Drawn while its box is on screen**: it is drawn whenever its element's box overlaps the viewport, like a plane whose vertex code bends it. Instances that move past the box still draw there, but once the box itself leaves the screen nothing is drawn. Its parents' clips never skip it whole (its instances may move out of them), but they still cut what shows.
|
|
1936
2204
|
- **Echo** keeps a short history of where the plane was, by time (the same trail at 60 and 120 Hz). Once every copy caught up, nothing is asked for: 0 frames per second.
|
|
1937
2205
|
- **Ink** seeds once its pixels are there (one small pass of `chunks/fx.js`, a half-float texture of one texel per particle, picked on the GPU), and again when its pixels change (new text) or, with `object-fit: cover` or `contain`, when the plane's shape changes (another part of the image shows). Until then it draws once, whole. A shader surface has no pixels to read: it draws once, with a warning. At most 65536 particles (and instances in any mode); echo at most `"echo 64"` (the plane plus 63 copies).
|
|
1938
|
-
- Words it does not know make it say so (`[umber] data-
|
|
2206
|
+
- Words it does not know make it say so (`[umber] data-umber-instances="...": ... so it draws once`) and the plane draws as without instances. `"chars"` on a plane that is not GL text does the same.
|
|
1939
2207
|
- **Up to 13 attributes** per plane (vertex attribute slots).
|
|
1940
2208
|
|
|
1941
2209
|
---
|
|
@@ -1945,37 +2213,37 @@ gl.effect("swarm", {
|
|
|
1945
2213
|
Mark a video as scrubbed and its frame follows the scroll. Umber decides which frame is on screen and decodes it itself where it can, so it never asks the browser's player to seek on every scroll event (which is what makes scrubbed video stutter).
|
|
1946
2214
|
|
|
1947
2215
|
```html
|
|
1948
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
2216
|
+
<script src="https://umber.occluze.com/umber@0.3.0/modules/scrub.js"></script> <!-- after or before umber.js -->
|
|
1949
2217
|
|
|
1950
|
-
<video data-
|
|
2218
|
+
<video data-umber="video" data-umber-scrub src="/scrub.mp4" poster="/scrub.jpg"
|
|
1951
2219
|
muted playsinline preload="none"></video>
|
|
1952
2220
|
```
|
|
1953
2221
|
```js
|
|
1954
|
-
import {
|
|
2222
|
+
import { createUmber } from "@occluze/umber"; // npm
|
|
1955
2223
|
import { Scrub } from "@occluze/umber/scrub";
|
|
1956
|
-
const
|
|
2224
|
+
const umber = createUmber({ modules: [Scrub] }); // or umber.use(Scrub, { cacheMB: 128, reducedMotion: "scrub" })
|
|
1957
2225
|
```
|
|
1958
2226
|
|
|
1959
|
-
| Attribute (also `--
|
|
2227
|
+
| Attribute (also `--umber-scrub-*` in CSS) | Default | |
|
|
1960
2228
|
|---|---|---|
|
|
1961
|
-
| `data-
|
|
1962
|
-
| `data-
|
|
1963
|
-
| `data-
|
|
1964
|
-
| `data-
|
|
1965
|
-
| `data-
|
|
1966
|
-
| `data-
|
|
1967
|
-
| `data-
|
|
1968
|
-
| `data-
|
|
1969
|
-
| `data-
|
|
1970
|
-
| `data-
|
|
1971
|
-
| `data-
|
|
1972
|
-
|
|
1973
|
-
The module options `cacheMB` and `reducedMotion` set the site-wide defaults for `data-
|
|
2229
|
+
| `data-umber-scrub` | `""` | `""`: the scroll drives it. `"manual"`: your code sets `progress`. |
|
|
2230
|
+
| `data-umber-scrub-start` / `-end` | `"top bottom"` / `"bottom top"` | `"<element edge> <viewport line>"`: `top`, `center`, `bottom`, `%` or px. |
|
|
2231
|
+
| `data-umber-scrub-track` | the video | The element whose position drives it: a selector, `"parent"` or `"closest section"` (a sticky video inside a tall section). |
|
|
2232
|
+
| `data-umber-scrub-smooth` | `0.12` (0 with Lenis) | Seconds to catch up. Lenis already smooths, so Umber doesn't do it twice: also a Lenis made after `createUmber()`, by the `lenis` class it puts on `<html>` (a Lenis on its own wrapper element: set `data-umber-scrub-smooth="0"` yourself). Under reduced motion (with `data-umber-scrub-reduced="scrub"`) it is always 0, whatever you set. |
|
|
2233
|
+
| `data-umber-scrub-source` | `auto` | `decoder` (WebCodecs), `video` (steps the `<video>`), `frames` (an image sequence). |
|
|
2234
|
+
| `data-umber-scrub-src` / `-src-mobile` | the video's `src` | The scrub MP4; `-mobile` on phones and weak GPUs (any device tier but "high"). |
|
|
2235
|
+
| `data-umber-scrub-frames` / `-count` | | An image sequence: `"/seq/f_{0001}.webp"` and its length. |
|
|
2236
|
+
| `data-umber-scrub-fps` | the file's, else `30` | Frame rate of a sequence or of the `<video>` tier. The decoder tier reads it from the MP4; the `<video>` tier can't, so set it to the file's rate (`npm run scrub` encodes 30 unless `--fps`), or frame numbers differ between tiers. |
|
|
2237
|
+
| `data-umber-scrub-blend` | `true` | Mix the two neighbouring frames while scrolling slowly. |
|
|
2238
|
+
| `data-umber-scrub-cache` | by GPU tier: 128 (high), 48 (mid: phones), 32 (low: weak GPUs) | GPU frame cache, MB. |
|
|
2239
|
+
| `data-umber-scrub-reduced` | `"poster"` | Under reduced motion: the poster, or `"scrub"` (the visitor still drives it). |
|
|
2240
|
+
|
|
2241
|
+
The module options `cacheMB` and `reducedMotion` set the site-wide defaults for `data-umber-scrub-cache` and `data-umber-scrub-reduced`.
|
|
1974
2242
|
|
|
1975
2243
|
From code, the handle is on the plane, and every value is plain (tween it with anything):
|
|
1976
2244
|
|
|
1977
2245
|
```js
|
|
1978
|
-
const s =
|
|
2246
|
+
const s = umber.plane(video)?.scrub; // undefined with GL off: the poster and the DOM video show
|
|
1979
2247
|
if (s) {
|
|
1980
2248
|
s.progress = 0.4; // hands it to your code (drive becomes "manual"); s.drive = "scroll" gives it back
|
|
1981
2249
|
s.time = 2.5; // seconds into the clip
|
|
@@ -1992,7 +2260,7 @@ if (s) {
|
|
|
1992
2260
|
- **Storage:** on Android the decoder tier remembers per device whether hardware or software decoding is faster, in `localStorage` (key `umber:scrub-decode`, value `prefer-hardware` or `prefer-software`). Nothing else is stored. Mention it if the site's storage or consent policy lists what it keeps.
|
|
1993
2261
|
- **Shaders** on scrubbed planes get `uScrubProgress` (0..1) and `uScrubVelocity` (progress per second): grain or a motion smear is just another effect (`examples/video/scrub.html` adds grain).
|
|
1994
2262
|
- **Encode for it:** `npm run scrub -- input.mov` makes an H.264 MP4 with a keyframe on every frame (scrubbing back costs the same as forwards), no B-frames, faststart and a poster. `--width`, `--fps`, `--gop`, `--crf`, `--mobile`.
|
|
1995
|
-
- Other MP4s work too, slower to scrub back (keyframes far apart) or with a trim kept as an edit list (the trimmed clip is what scrubs). A file the decoder tier can't read itself scrubs from the next tier (seeking the `<video>`, which is choppier): a fragmented MP4 (its frames are indexed in fragments, not in its header), a codec other than H.264 (HEVC, AV1, VP9), or a file with no frame index. Each such file gets one `[umber]` warning, also without debug mode, that names the file and the fix: encode it with `npm run scrub`. When it's this browser's doing (no WebCodecs, or a codec it can't decode), only a debug note says so (`?umber-debug` or `
|
|
2263
|
+
- Other MP4s work too, slower to scrub back (keyframes far apart) or with a trim kept as an edit list (the trimmed clip is what scrubs). A file the decoder tier can't read itself scrubs from the next tier (seeking the `<video>`, which is choppier): a fragmented MP4 (its frames are indexed in fragments, not in its header), a codec other than H.264 (HEVC, AV1, VP9), or a file with no frame index. Each such file gets one `[umber]` warning, also without debug mode, that names the file and the fix: encode it with `npm run scrub`. When it's this browser's doing (no WebCodecs, or a codec it can't decode), only a debug note says so (`?umber-debug` or `createUmber({ debug: true })`): nothing is wrong with the file.
|
|
1996
2264
|
- Cross-origin files need CORS headers (`Access-Control-Allow-Origin`), like any GL video.
|
|
1997
2265
|
- Not tested yet on real phones, iOS Low Power Mode or Firefox for Android.
|
|
1998
2266
|
|
|
@@ -2000,26 +2268,26 @@ if (s) {
|
|
|
2000
2268
|
|
|
2001
2269
|
## Inputs (module: `modules/input.js`): drag, velocity, trail, press, step, live textures
|
|
2002
2270
|
|
|
2003
|
-
`
|
|
2271
|
+
`umber.pointer` and `umber.progress()` are in the core. The input module adds more inputs, each a live `{ value }` (a Signal) that works as an effect's uniform as it is. Load it on the pages that need it, one way or the other:
|
|
2004
2272
|
|
|
2005
2273
|
```html
|
|
2006
|
-
<!-- Script tags: it registers itself. There is no Input global and nothing to call:
|
|
2007
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
2274
|
+
<!-- Script tags: it registers itself. There is no Input global and nothing to call: umber.drag etc. are just there. -->
|
|
2275
|
+
<script src="https://umber.occluze.com/umber@0.3.0/modules/input.js"></script> <!-- after or before umber.js -->
|
|
2008
2276
|
```
|
|
2009
2277
|
```js
|
|
2010
2278
|
// npm: import it and hand it to the engine.
|
|
2011
2279
|
import { Input } from "@occluze/umber/input";
|
|
2012
|
-
|
|
2280
|
+
umber.use(Input); // or createUmber({ modules: [Input] })
|
|
2013
2281
|
```
|
|
2014
2282
|
|
|
2015
|
-
Types: with npm they come with the import. With script tags and TypeScript, copy `types/input.d.ts` next to `types/umber.d.ts`: it adds `
|
|
2283
|
+
Types: with npm they come with the import. With script tags and TypeScript, copy `types/input.d.ts` next to `types/umber.d.ts` and `types/global.d.ts`: it adds `umber.drag` and the rest to the `Umber` type, and to a `umber.scope()`'s (`s.drag`...) (`handoff.d.ts` and `scrub.d.ts` do the same for theirs).
|
|
2016
2284
|
|
|
2017
2285
|
Every one of them rides frames Umber runs anyway and asks for more only while it still moves. When the input rests, its velocity lands on **exactly 0** and the loop goes back to sleep (0 frames per second).
|
|
2018
2286
|
|
|
2019
|
-
### `
|
|
2287
|
+
### `umber.drag(el, options)`: a drag as a Signal
|
|
2020
2288
|
|
|
2021
2289
|
```js
|
|
2022
|
-
const d =
|
|
2290
|
+
const d = umber.drag(".slider", { axis: "x", bounds: { x: [-2400, 0] } });
|
|
2023
2291
|
d.value; // [x, y] offset in px from where it started
|
|
2024
2292
|
d.velocity.value; // [vx, vy] px per second, smoothed; 0 at rest
|
|
2025
2293
|
d.pressed; // a finger or button is down on it
|
|
@@ -2029,7 +2297,7 @@ d.on("release", (d) => {}); // also "press", "tap", "change"; each on() return
|
|
|
2029
2297
|
d.set(0); // jump (stops a glide)
|
|
2030
2298
|
d.bounds = { x: [-1800, 0] }; // change the limits any time (on resize)
|
|
2031
2299
|
|
|
2032
|
-
|
|
2300
|
+
umber.effect("swing", { uniforms: { uDragSpeed: d.velocity }, ... });
|
|
2033
2301
|
d.on("change", () => (track.style.transform = `translateX(${d.value[0]}px)`));
|
|
2034
2302
|
```
|
|
2035
2303
|
|
|
@@ -2040,106 +2308,106 @@ d.on("change", () => (track.style.transform = `translateX(${d.value[0]}px)`));
|
|
|
2040
2308
|
| `inertia` | `0.92` | How much glide speed is kept per 60 fps frame after release. `0` stops dead. |
|
|
2041
2309
|
| `rubber` | `0.35` | How far it gives past a bound while pressed. `0` is a hard stop. After release it springs back inside; pressed again on the way, it goes on from where it is. |
|
|
2042
2310
|
|
|
2043
|
-
- It **writes nothing to the DOM**: move your own elements from `d.value` (on `"change"`), or use it in a shader. `"change"` comes before Umber reads the frame's DOM changes, so planes inside the element you move are drawn on it in that same frame (no `data-
|
|
2311
|
+
- It **writes nothing to the DOM**: move your own elements from `d.value` (on `"change"`), or use it in a shader. `"change"` comes before Umber reads the frame's DOM changes, so planes inside the element you move are drawn on it in that same frame (no `data-umber-live` needed).
|
|
2044
2312
|
- The element gets the pointer events (the canvas has `pointer-events: none`). Give it `touch-action: pan-y` for a sideways drag (the page still scrolls), `pan-x` for an up-and-down one, `none` for both. Without it Umber warns once: with `auto` a finger scrolls the page instead of dragging.
|
|
2045
2313
|
- The click right after a drag (moved more than 6 px) is swallowed, so links in a dragged slider do not open. Only that one: a later click, and Enter on a link, go through. A press and release without moving is a `"tap"` (a press the browser cancels, to scroll the page, is a `"release"` only), and its click goes through to what was pressed (`d.target`): the pointer is only captured once it moved 6 px, so a tap on a link inside the slider opens it.
|
|
2046
|
-
- **A selector follows a router** (Barba, Swup, Astro, htmx...). `
|
|
2047
|
-
- **An element** (`
|
|
2048
|
-
- Inside `
|
|
2049
|
-
- Either ends with its `
|
|
2314
|
+
- **A selector follows a router** (Barba, Swup, Astro, htmx...). `umber.drag(".slider")` binds its first match, then the first match of each page that enters, so call it once, outside any router hook. It's one drag across pages: the same `d.velocity` (an effect registered once keeps reading it), `value` back to `[0, 0]` on each new page, `d.el` the element it is on now (a `"change"` follows each rebind). While both pages are in the DOM it takes the new one; when the page it is on leaves and another match is still there, it moves to that one. With no match (a page without a slider) it waits. Calling `umber.drag(".slider")` again replaces the older one, so a router hook that calls it on every page still has one drag. It binds one element at a time: two sliders on one page are two `umber.drag()` calls, with two selectors.
|
|
2315
|
+
- **An element** (`umber.drag(el)`) is that element only, and the drag ends when it leaves the page.
|
|
2316
|
+
- Inside `umber.scope(fn, container)` a selector looks only in the container (its first match, and later ones), each container has its own, and `revert()` ends the drag. A page swap in the middle of a press is a `"release"`. After an `await`, call it on the scope: `s.drag(".gallery")` (every call of this module is on the scope too: `s.velocityOf`, `s.trail`, `s.step`, `s.texture`...).
|
|
2317
|
+
- Either ends with its `umber.scope()` and the engine.
|
|
2050
2318
|
|
|
2051
2319
|
```js
|
|
2052
|
-
const d =
|
|
2053
|
-
|
|
2320
|
+
const d = umber.drag(".slider", { axis: "x", bounds: (el) => ({ x: [-(el.scrollWidth - el.clientWidth), 0] }) });
|
|
2321
|
+
umber.effect("swing", { ...swing, uniforms: { uDragSpeed: d.velocity } }); // keeps working on every page
|
|
2054
2322
|
d.on("change", () => (d.el.firstElementChild.style.transform = `translateX(${d.value[0]}px)`));
|
|
2055
2323
|
```
|
|
2056
2324
|
|
|
2057
|
-
### `
|
|
2325
|
+
### `umber.velocityOf(signal, options)`: the speed of any Signal
|
|
2058
2326
|
|
|
2059
2327
|
```js
|
|
2060
|
-
const p =
|
|
2061
|
-
const v =
|
|
2062
|
-
const dv =
|
|
2063
|
-
|
|
2328
|
+
const p = umber.progress(".story");
|
|
2329
|
+
const v = umber.velocityOf(p); // { value }: progress per second, 0 at rest
|
|
2330
|
+
const dv = umber.velocityOf(d, { smooth: 0.2 }); // arrays too: [vx, vy]
|
|
2331
|
+
umber.effect("smear", { uniforms: { uStorySpeed: v }, ... });
|
|
2064
2332
|
```
|
|
2065
2333
|
|
|
2066
2334
|
- `smooth` (default `0.25`) is a 60 fps lerp amount: lower is calmer. `rest` (default `0.001`, units per second) is where a resting value counts as stopped.
|
|
2067
|
-
- It samples `signal.value` on every frame Umber runs (scrolling, the pointer, drawing). A value **your own code** moves between frames needs `
|
|
2335
|
+
- It samples `signal.value` on every frame Umber runs (scrolling, the pointer, drawing). A value **your own code** moves between frames needs `umber.wake()` when it changes.
|
|
2068
2336
|
- **A slider library's progress**: wrap it in a getter, and wake Umber from the slider's own scroll event.
|
|
2069
2337
|
|
|
2070
2338
|
```js
|
|
2071
2339
|
const slider = { get value() { return mySlider.progress; } }; // whatever your slider exposes, 0..1
|
|
2072
|
-
const speed =
|
|
2073
|
-
mySlider.on("scroll", () =>
|
|
2074
|
-
|
|
2340
|
+
const speed = umber.velocityOf(slider);
|
|
2341
|
+
mySlider.on("scroll", () => umber.wake());
|
|
2342
|
+
umber.effect("wave", { uniforms: { uSlide: slider, uSlideSpeed: speed }, ... });
|
|
2075
2343
|
```
|
|
2076
2344
|
|
|
2077
|
-
### `
|
|
2345
|
+
### `umber.trail(count, options)`: the pointer's path
|
|
2078
2346
|
|
|
2079
2347
|
```js
|
|
2080
|
-
const t =
|
|
2348
|
+
const t = umber.trail(16, { follow: 0.5 }); // follow: how fast each point catches the one before
|
|
2081
2349
|
t.points[0].value; // [x, y]: the pointer, viewport px
|
|
2082
2350
|
t.points[15].value; // the end of the tail
|
|
2083
|
-
|
|
2351
|
+
umber.effect("ribbon", { uniforms: { uHead: t.points[0], uMid: t.points[7], uTail: t.points[15] }, ... });
|
|
2084
2352
|
t.destroy();
|
|
2085
2353
|
```
|
|
2086
2354
|
|
|
2087
2355
|
Each point is a vec2 Signal. A shader cannot take the whole list as one array uniform yet: pass the points it needs.
|
|
2088
2356
|
|
|
2089
|
-
### `
|
|
2357
|
+
### `umber.press`: the last press anywhere on the page
|
|
2090
2358
|
|
|
2091
2359
|
```js
|
|
2092
|
-
|
|
2093
|
-
|
|
2094
|
-
|
|
2095
|
-
|
|
2360
|
+
umber.press.value; // [x, y, time]: viewport px, and seconds in uTime's clock (-10000 before the first)
|
|
2361
|
+
umber.press.recent; // the last 4 presses, newest first, each a { value: [x, y, time] } vec3 Signal (a uniform takes one)
|
|
2362
|
+
umber.press.count;
|
|
2363
|
+
umber.press.on("press", (p) => {});
|
|
2096
2364
|
|
|
2097
|
-
|
|
2098
|
-
uniforms: { uPress:
|
|
2365
|
+
umber.effect("ripple", {
|
|
2366
|
+
uniforms: { uPress: umber.press },
|
|
2099
2367
|
fragment: { uv: "vec2 d = uRect.xy + vUv * uRect.zw - uPress.xy; float age = uTime - uPress.z; uv += normalize(d + 0.001) * sin(length(d) * 0.05 - age * 12.0) * exp(-age * 3.0) * 0.01;" },
|
|
2100
|
-
update(ctx) { ctx.busy(ctx.frame.time -
|
|
2368
|
+
update(ctx) { ctx.busy(ctx.frame.time - umber.press.value[2] < 1.5); }, // keep drawing while it ripples
|
|
2101
2369
|
});
|
|
2102
2370
|
```
|
|
2103
2371
|
|
|
2104
|
-
It listens to `pointerdown` (passive, on window) from the first time anything reads `
|
|
2372
|
+
It listens to `pointerdown` (passive, on window) from the first time anything reads `umber.press`. A ripple animates with `uTime`, so keep the plane drawing while it runs (`ctx.busy(true)` in `update`, as above); the press itself only stamps the frame it happened on.
|
|
2105
2373
|
|
|
2106
|
-
`
|
|
2374
|
+
`umber.press` is one for the page and outlives page swaps, but a `umber.press.on()` made inside a `umber.scope()` goes with its `revert()`. Only one made before the scope's first `await` is recorded: after it, keep its `off()` and call it yourself. Like `umber.on()` (and `addEventListener`), the same function added twice is one listener, so the first `off()` or revert removes it.
|
|
2107
2375
|
|
|
2108
|
-
### `
|
|
2376
|
+
### `umber.step(px, fn)`: every N px the pointer travels
|
|
2109
2377
|
|
|
2110
2378
|
```js
|
|
2111
|
-
const off =
|
|
2379
|
+
const off = umber.step(80, ([x, y], n) => stamp(x, y, n)); // image trails, stamps
|
|
2112
2380
|
off();
|
|
2113
2381
|
```
|
|
2114
2382
|
|
|
2115
|
-
It reads `
|
|
2383
|
+
It reads `umber.pointer` on the frames it moves; the first move (from the screen's centre) does not count, nor a jump to a new press (a second finger) or back into the window. `at` is a new `[x, y]` each time, on the path where that step was reached, so it is yours to keep.
|
|
2116
2384
|
|
|
2117
|
-
### `
|
|
2385
|
+
### `umber.texture(source, options)`: a canvas, video or numbers as a `sampler2D`
|
|
2118
2386
|
|
|
2119
2387
|
```js
|
|
2120
2388
|
const canvas = document.querySelector("canvas.mask");
|
|
2121
|
-
const mask =
|
|
2122
|
-
|
|
2389
|
+
const mask = umber.texture(canvas); // also an ImageBitmap, <video>, <img>, ImageData
|
|
2390
|
+
umber.effect("reveal", { uniforms: { uMask: mask }, fragment: { alpha: "alpha *= texture(uMask, vUv).r;" } });
|
|
2123
2391
|
drawMyMask(canvas);
|
|
2124
2392
|
mask.update(); // you drew on it: uploaded before the next draw
|
|
2125
2393
|
|
|
2126
2394
|
const field = new Float32Array(32 * 32); // numbers: 1, 2 or 4 per texel (R, RG, RGBA)
|
|
2127
|
-
const grid =
|
|
2395
|
+
const grid = umber.texture({ data: field, width: 32, height: 32 });
|
|
2128
2396
|
field[5] = 1; grid.update();
|
|
2129
|
-
|
|
2397
|
+
umber.effect("grid", { uniforms: { uGrid: grid }, fragment: { uv: "uv += texture(uGrid, uv).r * 0.02;" } });
|
|
2130
2398
|
```
|
|
2131
2399
|
|
|
2132
2400
|
- It is uploaded **only when you say it changed** (`update()`, or `update(newSource)`), and only once a plane that samples it is drawn: a still page uploads nothing and sleeps. A `<video>` uploads each new frame it shows while it plays (nothing while paused).
|
|
2133
2401
|
- `options`: `filter: "nearest"` for crisp texels, `wrap: "repeat"` to tile it. Float data (`Float32Array`) is always sampled `nearest` and declared `highp` (exact numbers on phones too): read it at texel centres, or with `texelFetch(uGrid, ivec2(x, y), 0)`. 8-bit data (`Uint8Array`) reads 0..1 and is filtered.
|
|
2134
2402
|
- One texture serves any number of planes and effects. Images from another origin need CORS, as every GL image does. `t.width`, `t.height`, `t.destroy()`. After a lost context it is made again by itself.
|
|
2135
|
-
- A raw canvas, video or typed array as a uniform (without `
|
|
2136
|
-
- The pointer's whole trail in one uniform: `
|
|
2403
|
+
- A raw canvas, video or typed array as a uniform (without `umber.texture()`) would sample nothing, and more than 896 numbers are more than a phone's uniforms hold: Umber warns and names this fix (numbers that fit no GLSL type: when the GLSL reads them without declaring them).
|
|
2404
|
+
- The pointer's whole trail in one uniform: `umber.texture({ data: xy, width: 16, height: 1 })` (a `Float32Array` of 32), refilled from `trail.points` and `update()`d on the frames it moves.
|
|
2137
2405
|
|
|
2138
|
-
### `
|
|
2406
|
+
### `umber.touch(options)`: the pointer's fading trail as a texture
|
|
2139
2407
|
|
|
2140
2408
|
```js
|
|
2141
|
-
const touch =
|
|
2142
|
-
|
|
2409
|
+
const touch = umber.touch({ size: 64, radius: 0.08, fade: 0.92 });
|
|
2410
|
+
umber.effect("smear", {
|
|
2143
2411
|
uniforms: { uTouch: touch },
|
|
2144
2412
|
fragment: { uv: "vec4 t = texture(uTouch, screenUv()); uv += (t.rg * 2.0 - 1.0) * t.a * 0.03;" },
|
|
2145
2413
|
});
|
|
@@ -2147,11 +2415,11 @@ gl.effect("smear", {
|
|
|
2147
2415
|
|
|
2148
2416
|
A small screen-shaped canvas (`size` px wide) where the pointer leaves soft dots: `a` is the ink (0..1), `rg` the way it moved (`rg * 2.0 - 1.0`, -1..1). Sample it at the pixel's place on screen, `screenUv()`, so one texture serves every plane. `fade` is how much ink stays per 60 fps frame; `radius` is a share of the width. It draws only on frames the pointer moved, fades to exactly empty, then stops asking for frames: a still page sleeps. `touch.canvas` is the canvas itself.
|
|
2149
2417
|
|
|
2150
|
-
### `
|
|
2418
|
+
### `umber.rects(selector)`: element rects as numbers a shader reads
|
|
2151
2419
|
|
|
2152
2420
|
```js
|
|
2153
|
-
const cards =
|
|
2154
|
-
|
|
2421
|
+
const cards = umber.rects(".card"); // N x 1 texels: x, y, width, height in viewport px per card
|
|
2422
|
+
umber.shader("glow", {
|
|
2155
2423
|
uniforms: { uCards: cards },
|
|
2156
2424
|
fragment: `
|
|
2157
2425
|
vec2 p = screenPx();
|
|
@@ -2163,72 +2431,72 @@ gl.shader("glow", {
|
|
|
2163
2431
|
});
|
|
2164
2432
|
```
|
|
2165
2433
|
|
|
2166
|
-
One shader draws behind or through a whole grid. The rects come from `
|
|
2434
|
+
One shader draws behind or through a whole grid. The rects come from `umber.track()` (no layout reads while scrolling) and are uploaded only on frames one of them moved. `cards.count`, `cards.rects` (the same numbers, 4 per element), `cards.destroy()`. It holds the elements the selector found at the call: call it again after a page change.
|
|
2167
2435
|
|
|
2168
|
-
### `
|
|
2436
|
+
### `umber.imageColor(el)`: the colour of an element's image
|
|
2169
2437
|
|
|
2170
2438
|
```js
|
|
2171
|
-
const c =
|
|
2439
|
+
const c = umber.imageColor(".hero"); // { value: [r, g, b, a] }: the average colour, sRGB 0..1
|
|
2172
2440
|
await c.ready; // true once known (false: no CORS, no image)
|
|
2173
2441
|
c.dominant; // the most common colour
|
|
2174
|
-
|
|
2442
|
+
umber.effect("tint", { setup(ctx) { ctx.plane.set("uBg", umber.imageColor(ctx.el)); }, fragment: { color: "color.rgb = mix(uBg.rgb, color.rgb, color.a);" } });
|
|
2175
2443
|
```
|
|
2176
2444
|
|
|
2177
|
-
Worked out once per image (`data-
|
|
2445
|
+
Worked out once per image (`data-umber-src`, or the `<img>`'s current source) from a 16 x 16 copy that the browser decodes and shrinks off the main thread; `[0, 0, 0, 0]` until then. It is a vec4 Signal: a uniform as it is, which redraws when the colour arrives.
|
|
2178
2446
|
|
|
2179
2447
|
---
|
|
2180
2448
|
|
|
2181
|
-
## Smooth scrolling (module: `modules/scroll.js`): `
|
|
2449
|
+
## Smooth scrolling (module: `modules/scroll.js`): `umber.scroll`, instead of a scroll library
|
|
2182
2450
|
|
|
2183
|
-
Opt-in. Without it Umber scrolls nothing: the page scrolls natively, or with the site's own Lenis (`
|
|
2451
|
+
Opt-in. Without it Umber scrolls nothing: the page scrolls natively, or with the site's own Lenis (`createUmber({ scroll: lenis })`, as above), exactly as before. With it, the wheel eases the page's real scroll position on Umber's own loop, and GL planes stay on their elements to the pixel. Use the module **or** Lenis, never both.
|
|
2184
2452
|
|
|
2185
2453
|
### Start
|
|
2186
2454
|
|
|
2187
2455
|
```html
|
|
2188
|
-
<!--
|
|
2189
|
-
|
|
2190
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
2191
|
-
<script>const
|
|
2456
|
+
<!-- Name it on the umber.js tag: it loads at once and registers itself. Nothing to call: umber.scroll is just there.
|
|
2457
|
+
(A tag of its own, modules/scroll.js after umber.js, works the same.) -->
|
|
2458
|
+
<script src="https://umber.occluze.com/umber@0.3.0/umber.js" data-umber-key="YOUR_KEY" data-umber-modules="scroll"></script>
|
|
2459
|
+
<script>const umber = Umber.createUmber();</script>
|
|
2192
2460
|
```
|
|
2193
2461
|
```js
|
|
2194
2462
|
// npm: import it and hand it to the engine.
|
|
2195
2463
|
import { Scroll } from "@occluze/umber/scroll";
|
|
2196
|
-
|
|
2464
|
+
umber.use(Scroll, { lerp: 0.1 }); // or createUmber({ modules: [[Scroll, { lerp: 0.1 }]] })
|
|
2197
2465
|
```
|
|
2198
2466
|
|
|
2199
2467
|
**Webflow:** put the two script tags in Site settings, Custom code, Footer code. That's the whole setup. Everything else is a Custom attribute on the **Body** (Page settings, or the Body element's settings):
|
|
2200
2468
|
|
|
2201
2469
|
| Body attribute | Value | What it does |
|
|
2202
2470
|
|---|---|---|
|
|
2203
|
-
| `data-
|
|
2204
|
-
| `data-
|
|
2205
|
-
| `data-
|
|
2471
|
+
| `data-umber-scroll-offset` | `-80` | Every `#link` stops 80 px above its target (a fixed navbar 80 px tall). |
|
|
2472
|
+
| `data-umber-scroll` | `off` | This page scrolls natively (the module stays loaded for the others). |
|
|
2473
|
+
| `data-umber-scroll-lerp` | `0.08` | Floatier (lower) or snappier (higher). Default `0.1`. |
|
|
2206
2474
|
|
|
2207
|
-
Types: with npm they come with the import. With script tags and TypeScript, copy `types/scroll.d.ts` next to `types/umber.d.ts`.
|
|
2475
|
+
Types: with npm they come with the import. With script tags and TypeScript, copy `types/scroll.d.ts` next to `types/umber.d.ts` and `types/global.d.ts`.
|
|
2208
2476
|
|
|
2209
2477
|
### Recipes
|
|
2210
2478
|
|
|
2211
2479
|
```js
|
|
2212
2480
|
// Scroll to a section (a selector, an element, px, "top" or "bottom"), 80 px above it.
|
|
2213
|
-
|
|
2481
|
+
umber.scroll.scrollTo("#contact", { offset: -80 });
|
|
2214
2482
|
|
|
2215
2483
|
// The same over exactly 1.2 s with your own ease; the wheel can't interrupt it.
|
|
2216
|
-
|
|
2484
|
+
umber.scroll.scrollTo("#pricing", { duration: 1.2, easing: (t) => 1 - (1 - t) ** 3, lock: true });
|
|
2217
2485
|
|
|
2218
2486
|
// A modal: hold the page while it is open (its own list still scrolls).
|
|
2219
|
-
openButton.addEventListener("click", () => { modal.showModal();
|
|
2220
|
-
modal.addEventListener("close", () =>
|
|
2487
|
+
openButton.addEventListener("click", () => { modal.showModal(); umber.scroll.stop(); });
|
|
2488
|
+
modal.addEventListener("close", () => umber.scroll.start());
|
|
2221
2489
|
|
|
2222
|
-
// A fixed header for every #link (the same as data-
|
|
2223
|
-
|
|
2490
|
+
// A fixed header for every #link (the same as data-umber-scroll-offset="-80" on <body>).
|
|
2491
|
+
umber.scroll.options.anchors = { offset: -80 };
|
|
2224
2492
|
|
|
2225
|
-
// A progress bar, and the scroll speed for an effect (or read
|
|
2226
|
-
|
|
2227
|
-
|
|
2228
|
-
|
|
2493
|
+
// A progress bar, and the scroll speed for an effect (or read umber.velocity, the engine's).
|
|
2494
|
+
umber.scroll.on("scroll", (s) => (bar.style.transform = `scaleX(${s.progress})`));
|
|
2495
|
+
umber.effect("stretch", { uniforms: { uSpeed: { value: 0 } } /* ...your GLSL... */ });
|
|
2496
|
+
umber.on("frame", () => umber.plane(hero)?.set("uSpeed", umber.scroll.velocity / 40));
|
|
2229
2497
|
|
|
2230
|
-
// Turn smoothing off on one page from code (or data-
|
|
2231
|
-
|
|
2498
|
+
// Turn smoothing off on one page from code (or data-umber-scroll="off" on its <body>).
|
|
2499
|
+
umber.scroll.options.wheel = false;
|
|
2232
2500
|
```
|
|
2233
2501
|
|
|
2234
2502
|
**With GSAP ScrollTrigger: nothing to add.** When the page has `ScrollTrigger`, every frame the module writes the scroll it calls `ScrollTrigger.update()` right away, so pins and scrubs move in the same frame as the page (measured: 0 px pin jitter, 0 px scrub lag in Chromium, Firefox and WebKit). Write your ScrollTriggers as for native scroll; no `scrollerProxy`, no `lenis.on("scroll", ScrollTrigger.update)` line.
|
|
@@ -2236,46 +2504,50 @@ gl.scroll.options.wheel = false;
|
|
|
2236
2504
|
### How it works
|
|
2237
2505
|
|
|
2238
2506
|
- The wheel moves a **target**. Every frame of Umber's own loop, the drawn position eases toward it and is **written to the real scroll position** (the window's, or a wrapper's). Nothing is faked: the DOM, `position: sticky`, IntersectionObserver, CSS scroll-driven animations and other code's scroll listeners see a normal scroll.
|
|
2239
|
-
- It writes **before Umber reads the scroll** in the same frame, so planes and the DOM move together, 0 px apart, with no `
|
|
2507
|
+
- It writes **before Umber reads the scroll** in the same frame, so planes and the DOM move together, 0 px apart, with no `createUmber({ scroll })`. One loop: it adds no `requestAnimationFrame` of its own.
|
|
2240
2508
|
- Each engine's wheel step is the distance that browser would scroll natively (they report it in px, kept 1:1), so a notch goes as far as it does without the module. The easing is time-based: the same curve at 30, 60, 120 or 144 Hz, and a slow frame catches up without overshooting.
|
|
2241
|
-
- At rest it asks for no frames: a still page runs 0 rAF/s. It keeps the loop running only while it moves, also with GL paused or off (a phone, Save-Data): smooth scrolling doesn't need GL.
|
|
2509
|
+
- At rest it asks for no frames: a still page runs 0 rAF/s. While it leaves the wheel to the browser (no licence yet, `data-umber-scroll="off"`, `wheel: false`, reduced motion, another smooth scroller), its wheel listener is passive, so the browser never waits for the page to scroll (measured: a frame less latency than a listener that could cancel). It keeps the loop running only while it moves, also with GL paused or off (a phone, Save-Data): smooth scrolling doesn't need GL.
|
|
2242
2510
|
- `limit` follows a ResizeObserver on the content and `resize` events (lazy images, a list that grows, a phone's address bar): no layout read while it moves.
|
|
2243
2511
|
|
|
2244
2512
|
### What stays native
|
|
2245
2513
|
|
|
2246
2514
|
The browser's own scrolling, untouched:
|
|
2247
2515
|
|
|
2248
|
-
- **Keys** (arrows, Space, Page Up / Down, Home, End, Tab to a link below), the **scrollbar**, **find-in-page**, **focus** moving to an element off screen, **back / forward** scroll restoration, **middle-click** autoscroll, a **text selection** dragged past the edge. A key pressed mid-glide hands over to the browser's key scroll. Any scroll the module did not write is taken as the new position, also mid-glide (the glide ends there; `
|
|
2249
|
-
- **Ctrl / ⌘ + wheel** and trackpad pinch (zoom), **sideways** swipes and Shift + wheel (carousels, the back gesture).
|
|
2516
|
+
- **Keys** (arrows, Space, Page Up / Down, Home, End, Tab to a link below), the **scrollbar**, **find-in-page**, **focus** moving to an element off screen, **back / forward** scroll restoration, **middle-click** autoscroll, a **text selection** dragged past the edge. A key pressed mid-glide hands over to the browser's key scroll. Any scroll the module did not write is taken as the new position, also mid-glide (the glide ends there; `umber.scroll` follows it, `isScrolling` is `"native"`). Only when the page grew above (images loading) does the glide go on, shifted with the content.
|
|
2517
|
+
- **Ctrl / ⌘ + wheel** and trackpad pinch (zoom), **sideways** swipes and Shift + wheel (carousels, the back gesture) on a vertical page (`gestureOrientation: "vertical"`, the default). On a horizontal page it is the other way round: sideways and up / down both move it, and an element under the pointer that scrolls the way the gesture goes scrolls first.
|
|
2250
2518
|
- **Touch**: phones and tablets scroll natively, with their own momentum, unless `touch: true`. The module then adds no touch listener at all, so the browser never waits for the page on a touch.
|
|
2251
2519
|
- **`prefers-reduced-motion: reduce`**: the wheel is native and `scrollTo()` jumps.
|
|
2252
|
-
- **Elements that scroll by themselves** under the pointer (a menu, a modal's list, a code block, `overflow: auto`) scroll first, natively; at their end the page goes on, as native scroll chaining does (not past an `overscroll-behavior: contain` one). Iframes (video and map embeds) get their own wheel at rest; while the page glides they take no pointer events, so a glide passing over one goes on. `data-
|
|
2520
|
+
- **Elements that scroll by themselves** under the pointer (a menu, a modal's list, a code block, `overflow: auto`) scroll first, natively; at their end the page goes on, as native scroll chaining does (not past an `overscroll-behavior: contain` one). Iframes (video and map embeds) get their own wheel at rest; while the page glides they take no pointer events, so a glide passing over one goes on. `data-umber-scroll-prevent` keeps any element and its children native (and keeps its scroll in: `overscroll-behavior: contain`); `data-umber-scroll-prevent-wheel` / `-touch` only that input. Lenis's `data-lenis-prevent` (and `-wheel`, `-touch`) work the same, so a site moving from Lenis keeps its markup.
|
|
2253
2521
|
- **CSS `scroll-snap`** on the scroller: the wheel stays native (so it snaps), and `scrollTo()` and `#links` use the browser's own smooth scroll (which snaps too).
|
|
2254
2522
|
- **A page held by a scroll lock**: `overflow: hidden` on `<html>` or `<body>` (most modal libraries) or `position: fixed` on `<body>` (iOS-style locks): the wheel stays native and moves nothing.
|
|
2255
2523
|
- **At the top going up, or the end going down**: the browser's own (overscroll bounce, a parent frame).
|
|
2256
2524
|
- **Another smooth scroller** on the page (Lenis marks `<html class="lenis">`): it keeps the wheel, and Umber warns once.
|
|
2257
|
-
- **A
|
|
2525
|
+
- **A site that isn't licensed** (no key, or not yet approved at occluze.com): scrolling stays the browser's, and `scrollTo()` and `#links` use its own smooth scroll. The same holds while the answer is on its way (asked once per page, `umber.licensed()`; a yes is kept about a week). `localhost`, `*.localhost`, `*.test` and private IP addresses always work.
|
|
2258
2526
|
|
|
2259
|
-
### `
|
|
2527
|
+
### `umber.scroll`
|
|
2260
2528
|
|
|
2261
2529
|
The shape scroll libraries share (Lenis's), so tools that look for one find it at `window.__umber.engine.scroll`:
|
|
2262
2530
|
|
|
2263
2531
|
```js
|
|
2264
|
-
|
|
2265
|
-
|
|
2266
|
-
|
|
2267
|
-
|
|
2268
|
-
|
|
2269
|
-
|
|
2270
|
-
|
|
2271
|
-
|
|
2272
|
-
|
|
2273
|
-
|
|
2274
|
-
|
|
2532
|
+
umber.scroll.animatedScroll; // where the page is drawn now (px)
|
|
2533
|
+
umber.scroll.targetScroll; // where it is heading
|
|
2534
|
+
umber.scroll.limit; // the largest scroll (px)
|
|
2535
|
+
umber.scroll.velocity; // px per frame at 60 fps, + down; 0 at rest (an effect's uScrollVelocity is about this / 60, smoothed, -1..1)
|
|
2536
|
+
umber.scroll.lastVelocity; // the velocity before its last change
|
|
2537
|
+
umber.scroll.userData; // the running scrollTo()'s userData ({ initiator: "snap" } for a snap); {} otherwise
|
|
2538
|
+
umber.scroll.direction; // 1 down, -1 up
|
|
2539
|
+
umber.scroll.progress; // 0..1 down the page
|
|
2540
|
+
umber.scroll.isScrolling; // "smooth" | "native" | false
|
|
2541
|
+
umber.scroll.isStopped; // after stop()
|
|
2542
|
+
umber.scroll.isHorizontal; // orientation: "horizontal" (scrollLeft; + right)
|
|
2543
|
+
|
|
2544
|
+
const off = umber.scroll.on("scroll", (s) => {}); // every frame it moves, and on native scrolls
|
|
2545
|
+
umber.scroll.on("virtual-scroll", ({ deltaX, deltaY, event }) => {}); // every wheel and touch move it hears (px), as Lenis's
|
|
2546
|
+
umber.scroll.stop(); // hold the page: no wheel, touch, keys or scrollTo() without { force } or { immediate } (data-umber-scroll-state="stopped": overflow hidden; a
|
|
2275
2547
|
// scrollbar that takes room keeps it, so nothing reflows)
|
|
2276
|
-
|
|
2277
|
-
|
|
2278
|
-
|
|
2548
|
+
umber.scroll.start(); // ...and back (its own overflow restored)
|
|
2549
|
+
umber.scroll.resize(); // measure again now and take the real position (after a page swap)
|
|
2550
|
+
umber.scroll.raf(time); // only to step it from your own loop; Umber's loop does it otherwise
|
|
2279
2551
|
```
|
|
2280
2552
|
|
|
2281
2553
|
| `scrollTo()` option | Default | |
|
|
@@ -2287,75 +2559,212 @@ gl.scroll.raf(time); // only to step it from your own loop; Umber's loop
|
|
|
2287
2559
|
| `lerp` | the module's | This move's lerp. |
|
|
2288
2560
|
| `lock` | `false` | Ignore the wheel, touch, the scroll keys and other animated `scrollTo()`s until it lands. |
|
|
2289
2561
|
| `force` | `false` | Animate also while stopped or locked. |
|
|
2562
|
+
| `onStart` | | As it starts. |
|
|
2290
2563
|
| `onComplete` | | When it lands (not when the wheel or a key interrupts it). |
|
|
2564
|
+
| `userData` | `{}` | `umber.scroll.userData` while this move runs (who asked for it). |
|
|
2291
2565
|
|
|
2292
2566
|
The wheel interrupts a `scrollTo()` from where the page is drawn.
|
|
2293
2567
|
|
|
2294
2568
|
### Options
|
|
2295
2569
|
|
|
2296
|
-
`
|
|
2570
|
+
`umber.use(Scroll, { ... })`. With the script build, set them on `umber.scroll.options` right after `createUmber()` (each is read when it is used; `touch`, `wrapper`, `content` and `autoResize` only at the start), or use the attributes below. Who wins, for `lerp` and `duration`: the defaults, then the page's `data-umber-scroll-lerp` / `-duration` (each page of a router can have its own), then `umber.use()`'s options, then a write to `umber.scroll.options` (it stays: page changes don't undo it).
|
|
2297
2571
|
|
|
2298
2572
|
| Option | Default | |
|
|
2299
2573
|
|---|---|---|
|
|
2300
|
-
| `
|
|
2574
|
+
| `orientation` | `"vertical"` | `"horizontal"`: the page (or the wrapper) scrolls sideways: `scrollLeft`, widths, `scroll-margin-left`. Read at the start. The same as `data-umber-scroll="horizontal"` on `<body>`. |
|
|
2575
|
+
| `gestureOrientation` | `"vertical"`, `"both"` when horizontal | Which way of the wheel or a finger moves the page: its up / down, its sideways (`"horizontal"`), or whichever is larger (`"both"`). With `"vertical"`, sideways swipes and Shift + wheel stay native (carousels, the back gesture). |
|
|
2576
|
+
| `lerp` | `0.1` | How fast it eases, as Lenis's `lerp` means it (the same number gives the same motion): about this share of the way per 60 fps frame (exactly 1 - e^-lerp), the same at any refresh rate. Lower is floatier; `1` is no smoothing. |
|
|
2301
2577
|
| `duration`, `easing` | `0`, expo out | Seconds a wheel move takes, with this ease, instead of the lerp. |
|
|
2302
2578
|
| `wheelMultiplier` | `1` | Wheel distance times this. |
|
|
2303
2579
|
| `wheel` | `true` | `false`: the wheel scrolls natively (`scrollTo()` and anchors still glide). |
|
|
2304
|
-
| `touch`, `touchMultiplier` | `false`, `1` | Smooth touch too: the page follows the finger 1:1, and a flick goes on at the finger's speed and slows down like a phone's own momentum (speed x 325 ms in all). Off, phones scroll natively, which is what most sites want. |
|
|
2305
|
-
| `
|
|
2580
|
+
| `touch`, `touchMultiplier` | `false`, `1` | Smooth touch too (its code is a second file, `modules/scroll-touch.js`, which the module loads by itself only then; with npm your bundler splits it off): the page follows the finger 1:1, and a flick goes on at the finger's speed and slows down like a phone's own momentum (speed x 325 ms in all). Off, phones scroll natively, which is what most sites want. On iOS and Android a finger on a text selection's handle drags the selection, never the page. |
|
|
2581
|
+
| `touchLerp` | about `0.05` | The fling's lerp (Lenis's `syncTouchLerp`, which is `0.075`). |
|
|
2582
|
+
| `touchInertiaExponent` | `null` | A number: the fling goes the finger's last px per frame to this power, as Lenis's (`1.7`) does. `null`: speed x 325 ms, like a phone. |
|
|
2583
|
+
| `virtualScroll` | none | `({ deltaX, deltaY, event }) => boolean`: sees every wheel and touch move first; `false` leaves that one to the browser (Lenis's filter: a wheel-driven carousel, a custom gesture). |
|
|
2584
|
+
| `wrapper` | `[data-umber~="scroller"]`, else the window | An element that scrolls instead of the window (an app shell: `html, body { overflow: hidden }`, the wrapper `height: 100vh; overflow: auto`). Mark it `data-umber="scroller"`: Umber's engine then follows its scroll by itself. Keys scroll it only while focus is inside it (give it `tabindex="-1"` and focus it), as without the module. |
|
|
2306
2585
|
| `content` | the wrapper's first child, or `<html>` | What grows (watched for `limit`). |
|
|
2307
2586
|
| `anchors` | `true` | In-page `#id` links glide (and add a history entry like a native `#link`, and move focus when used from the keyboard). An object: `scrollTo()` options for them, like `{ offset: -80 }`. |
|
|
2308
|
-
| `autoResize` | `true` | `false`: call `
|
|
2309
|
-
| `prevent` | none | `(el) => boolean`: true keeps that element's wheel and touch native, like `data-
|
|
2310
|
-
| `nested` | `true` | `false`: elements that scroll by themselves don't scroll first (only `data-
|
|
2587
|
+
| `autoResize` | `true` | `false`: call `umber.scroll.resize()` yourself. |
|
|
2588
|
+
| `prevent` | none | `(el) => boolean`: true keeps that element's wheel and touch native, like `data-umber-scroll-prevent`. |
|
|
2589
|
+
| `nested` | `true` | `false`: elements that scroll by themselves don't scroll first (only `data-umber-scroll-prevent` does). |
|
|
2590
|
+
| `autoToggle` | `false` | `stop()` and `start()` follow the scroller's own `overflow`: when a modal library hides it the module stops, and it starts again when it shows (Lenis's `autoToggle`). |
|
|
2591
|
+
| `eventsTarget` | the scroller | Where the wheel and touch are heard (Lenis's `eventsTarget`): an element (or a selector), for a page whose content sits under a layer that takes the pointer. |
|
|
2592
|
+
| `infinite` | `false` | Endless, as Lenis's: past the end the page goes on from the start, and up from the top on from the end; `scrollTo()` takes the shorter way round. The page repeats its first screen at its end (duplicate it), so the jump back can't be seen. `animatedScroll` counts on past the end, `scroll` and `progress` stay within the page. Also `data-umber-scroll="infinite"`. Touch stays native unless `touch: true`. |
|
|
2311
2593
|
|
|
2312
2594
|
### Attributes
|
|
2313
2595
|
|
|
2314
2596
|
| Attribute | On | |
|
|
2315
2597
|
|---|---|---|
|
|
2316
|
-
| `data-
|
|
2317
|
-
| `data-
|
|
2318
|
-
| `data-
|
|
2319
|
-
| `data-
|
|
2320
|
-
| `data-
|
|
2321
|
-
| `data-
|
|
2598
|
+
| `data-umber-scroll="off"` | `<body>` or `<html>` | The wheel, touch and anchors stay native on this page (read on every wheel: a router's new body can carry it). `scrollTo()` still works. |
|
|
2599
|
+
| `data-umber-scroll="touch"` | `<body>` or `<html>` | Smooth touch too. |
|
|
2600
|
+
| `data-umber-scroll="infinite"` | `<body>` or `<html>` | An endless page (`infinite: true`). |
|
|
2601
|
+
| `data-umber-scroll="horizontal"` | `<body>` or `<html>` | The page scrolls sideways (`orientation: "horizontal"`); the wheel's up / down moves it too. Words combine: `"horizontal touch"`. |
|
|
2602
|
+
| `data-umber-scroll-lerp`, `data-umber-scroll-duration` | `<body>` or `<html>` | The options, for sites without code. Read again by `umber.scroll.resize()` (Umber's router calls it after each page change), so each page can have its own. Options given in `umber.use()` win. |
|
|
2603
|
+
| `data-umber-scroll-to="#target"` | any element | A click glides to that `scrollTo()` target (`#id`, a selector, `top`, `bottom`; empty: the element's own `href`), Locomotive's `data-scroll-to`. |
|
|
2604
|
+
| `data-umber-scroll-duration="1.2"` | a `#link` or a `data-umber-scroll-to` element | This link's glide takes that many seconds, with the module's `easing` (Locomotive's `data-scroll-to-duration`). |
|
|
2605
|
+
| `data-umber="nested"` | an element with `overflow: auto` | It scrolls smoothly by itself (Lenis's nested instances); at its end the wheel goes on to the page. Also `umber.scroll.nest(el, options)`, which resolves with its own `umber.scroll`-shaped scroller. |
|
|
2606
|
+
| `data-umber-scroll-offset="-80"` | a `#link`, its target, or `<body>` | px for anchor links (the link's first, then the target's, then the page's). It adds to CSS `scroll-margin-top`: use one or the other. A page opened with a `#hash` in its URL is the browser's own jump, which only CSS (`scroll-margin-top`) moves. |
|
|
2607
|
+
| `data-umber-scroll-prevent` | any element | It and its children scroll natively (a menu, a modal, a map). `-wheel` / `-touch` for one input only. Lenis's `data-lenis-prevent` (and its `-wheel`, `-touch`) too. |
|
|
2608
|
+
| `data-umber="scroller"` | the scroller | The element that scrolls instead of the window. Umber's engine follows it too. |
|
|
2609
|
+
|
|
2610
|
+
### What loads when
|
|
2611
|
+
|
|
2612
|
+
`modules/scroll.js` is the smooth scroll itself. What only some pages use is in two more files next to it, which it loads by itself the first time a page uses them (with npm, your bundler splits them off):
|
|
2613
|
+
|
|
2614
|
+
- `modules/scroll-touch.js`: smooth touch (`touch: true`).
|
|
2615
|
+
- `modules/scroll-more.js`: `#links` and `data-umber-scroll-to` (it comes as the pointer reaches one, a finger touches one or one takes focus, so the click glides), `scrollTo()` with an element or a selector, `duration` and tweens, `lock`, `stop()` / `start()`, the scroll keys' hand-over, `infinite`, `gestureOrientation` other than vertical, `raf()`, `autoToggle`, nested scrollers, and scroll anchoring in the middle of a glide. A page with Umber's router loads it at once.
|
|
2616
|
+
|
|
2617
|
+
Until a file is in, what it does is the browser's own: a `#link` clicked before it arrived jumps natively; a `scrollTo("#work")` or `stop()` runs as soon as it is in (a few milliseconds once cached).
|
|
2618
|
+
|
|
2619
|
+
### Frameworks
|
|
2620
|
+
|
|
2621
|
+
Tiny helpers, each its own file (`dist/frameworks/<name>.mjs`), for the engine on the page (or the one you pass):
|
|
2622
|
+
|
|
2623
|
+
```js
|
|
2624
|
+
// React (Lenis's useLenis): umber.scroll, and a callback every frame it moves.
|
|
2625
|
+
import { useScroll } from "@occluze/umber/react";
|
|
2626
|
+
// const scroll = useScroll((s) => setProgress(s.progress), []);
|
|
2627
|
+
|
|
2628
|
+
// Vue: a ref to umber.scroll.
|
|
2629
|
+
import { useScroll as useVueScroll } from "@occluze/umber/vue";
|
|
2630
|
+
// const scroll = useVueScroll((s) => (progress.value = s.progress));
|
|
2631
|
+
|
|
2632
|
+
// Svelte: a store ($scroll), with no Svelte import of its own.
|
|
2633
|
+
import { scroll } from "@occluze/umber/svelte";
|
|
2634
|
+
|
|
2635
|
+
// Astro's view transitions (<ClientRouter />): held before each swap, measured after it.
|
|
2636
|
+
import { astroScroll } from "@occluze/umber/astro";
|
|
2637
|
+
astroScroll();
|
|
2638
|
+
void [useScroll, useVueScroll, scroll];
|
|
2639
|
+
```
|
|
2322
2640
|
|
|
2323
2641
|
### With a router and with page flights
|
|
2324
2642
|
|
|
2325
|
-
- **Umber's router** (`
|
|
2643
|
+
- **Umber's router** (`umber.router`) does it all by itself: it stops the scroll while a page changes, takes the new page to its top (or its `#hash`, or back to where you were on back / forward), and measures the new page.
|
|
2326
2644
|
- **Another router** (Barba, Swup...): the same in its hooks:
|
|
2327
2645
|
|
|
2328
2646
|
```js
|
|
2329
2647
|
// When the old page starts to leave:
|
|
2330
|
-
|
|
2648
|
+
umber.scroll.stop();
|
|
2331
2649
|
// Once the new page is in:
|
|
2332
|
-
|
|
2333
|
-
|
|
2334
|
-
|
|
2650
|
+
umber.scroll.scrollTo(0, { immediate: true }); // lands also while stopped
|
|
2651
|
+
umber.scroll.start();
|
|
2652
|
+
umber.scroll.resize();
|
|
2335
2653
|
```
|
|
2336
2654
|
|
|
2337
|
-
- **`data-
|
|
2338
|
-
- **Moving from Lenis:** take `new Lenis()` and `
|
|
2655
|
+
- **`data-umber-id` flights** (with a router, or the handoff module across full page loads) work as with native scroll: a flight lands on its element wherever the scroll is, and the back button's restored position is taken as it is.
|
|
2656
|
+
- **Moving from Lenis:** take `new Lenis()` and `createUmber({ scroll: lenis })` out and load the module. `lenis.scrollTo(...)` becomes `umber.scroll.scrollTo(...)`, `lenis.on("scroll", ...)` becomes `umber.scroll.on("scroll", ...)`, `lenis.stop()` / `start()` stay the same, `data-lenis-prevent` works as it is (or becomes `data-umber-scroll-prevent`), CSS on `html.lenis-stopped` / `.lenis-scrolling` becomes `[data-umber-scroll-state~="stopped"]` / `~="smooth"`, and the `ScrollTrigger.update` line goes (it is built in).
|
|
2339
2657
|
|
|
2340
2658
|
### Good to know
|
|
2341
2659
|
|
|
2342
|
-
- **`data-
|
|
2660
|
+
- **`data-umber-scroll-state`** on `<html>` (or the wrapper) says what the module does: `smooth` while it glides, `stopped` after `stop()` (`stopped gutter` when a classic scrollbar keeps its room), nothing at rest. Style on it (`[data-umber-scroll-state~="smooth"] .cursor { opacity: .5 }`). The module's own rules for it come in a small stylesheet it adds itself: `umber.css` isn't needed, and `stop()` writes no inline style, so it composes with a modal library's own lock.
|
|
2343
2661
|
- **Events like a native scroll:** one `scrollend` when a glide lands (not one per frame); a `#link` adds a history entry and fires `hashchange`. CSS `:target` doesn't follow a link the module glides to (only the browser's own jump sets it): a site that styles `:target` sets `anchors: false`.
|
|
2344
2662
|
|
|
2345
2663
|
- **Webflow's own smooth anchor scroll** (Webflow's scripts handle same-page `#links` themselves, with their fixed-header offset) runs first; the module steps aside for those clicks and follows the page as it moves. Legacy Webflow Interactions that read the scroll (IX2 "while scrolling") hear the browser's scroll event, which comes one frame after a write, as with any smooth scroller; GSAP-based interactions are in step (above).
|
|
2346
2664
|
- **CSS scroll-driven animations** (`animation-timeline: scroll()`) are in step in Chromium; WebKit applies a write made during a frame on its next frame (the same for every smooth scroller).
|
|
2347
|
-
-
|
|
2665
|
+
- **Smooth snapping, in-view classes, parallax and the rest of Locomotive's attributes** are the `scrollfx` module (its own chapter). CSS `scroll-snap` on the scroller is honoured as it is (above).
|
|
2666
|
+
- Framework helpers: React, Vue, Svelte and Astro (above).
|
|
2667
|
+
|
|
2668
|
+
---
|
|
2669
|
+
|
|
2670
|
+
## Scroll effects from attributes (module: `modules/scrollfx.js`), on Umber's clock
|
|
2671
|
+
|
|
2672
|
+
Opt-in. Attributes on any element (GL plane or plain DOM) for in-view classes and calls, a scroll-progress CSS variable, parallax, lag, the element's own scroll velocity, pinned sections, horizontal sections and smooth snapping. It works with native scroll, the scroll module and Lenis, and with GL off (a phone, Save-Data): every attribute maps onto `umber.progress()` and `umber.track()`, which follow the scroll in the measure phase, so the DOM and the planes on it move in the same frame (measured: 0 px between GL and DOM through parallax, lag and a horizontal section, in Chromium, Firefox and WebKit). At rest it asks for no frames.
|
|
2673
|
+
|
|
2674
|
+
### Start
|
|
2675
|
+
|
|
2676
|
+
```html
|
|
2677
|
+
<!-- Name it on the umber.js tag, with the scroll module for smooth scrolling and snapping. -->
|
|
2678
|
+
<script src="https://umber.occluze.com/umber@0.3.0/umber.js" data-umber-key="YOUR_KEY" data-umber-modules="scroll scrollfx"></script>
|
|
2679
|
+
<script>const umber = Umber.createUmber();</script>
|
|
2680
|
+
```
|
|
2681
|
+
```js
|
|
2682
|
+
// npm: import it and hand it to the engine.
|
|
2683
|
+
import { ScrollFx } from "@occluze/umber/scrollfx";
|
|
2684
|
+
umber.use(ScrollFx, { snap: { type: "proximity" } });
|
|
2685
|
+
```
|
|
2686
|
+
|
|
2687
|
+
### The attributes
|
|
2688
|
+
|
|
2689
|
+
| Attribute | Locomotive's | What it does |
|
|
2690
|
+
|---|---|---|
|
|
2691
|
+
| `data-umber="inview"` (`data-umber-inview="name"`) | `data-scroll`, `data-scroll-class` | The class `is-inview` (or `name`) while the element is on screen. It stays once added, unless `data-umber-inview-repeat`. `data-umber-inview-start` / `-end` move the window: `umber.progress()` edges, default `"top bottom"` / `"bottom top"` (`"top 80%"`: from its top at 80 % down the screen). |
|
|
2692
|
+
| `data-umber-inview-repeat` | `data-scroll-repeat` | The class comes off as it leaves, and comes back. |
|
|
2693
|
+
| `data-umber-call="name"` | `data-scroll-call` | A `window` event `name` as it enters (and leaves, with `-repeat`): `detail` is `{ target, way: "enter" \| "leave", from: "start" \| "end" }`, as Locomotive's. |
|
|
2694
|
+
| `data-umber-progress` (`="--name"`) | `data-scroll-css-progress` | `var(--progress)` (or `--name`): 0 as its top enters at the bottom, 1 as its bottom leaves at the top. `data-umber-progress-start` / `-end`: other edges. `data-umber-progress-event="name"`: a `window` event per change, `{ target, progress }` (`data-scroll-event-progress`). |
|
|
2695
|
+
| `data-umber-speed="0.2"` | `data-scroll-speed` | Parallax, Locomotive's amount: on its way through the screen the element goes from `speed` screens below where it sits to `speed` screens above (negative: the other way), level with it as its middle crosses the screen's. An element that starts on the first screen starts at 0. `data-umber-speed-ignore-fold`: one on the first screen moves from the start too (Locomotive's `data-scroll-ignore-fold`). Off under reduced motion, and on a touch screen that scrolls natively unless `data-umber-speed-touch` (`data-scroll-enable-touch-speed`). |
|
|
2696
|
+
| `data-umber-lag="0.1"` | v4's `data-scroll-delay` | The element trails the scroll: it eases after it by this share per 60 fps frame (lower: more lag), and catches up when the scroll stops. `var(--umber-lag)`: how far behind it is (px). |
|
|
2697
|
+
| `data-umber-velocity` (`="0.12"`) | | `var(--umber-velocity)`: the element's own speed through the screen, smoothed by this share per frame, -1..1 (3600 px/s is 1; `fullSpeed` changes it), + as the page goes on. A pinned element's is 0 while it is pinned; a lagging one's is its own. |
|
|
2698
|
+
| `data-umber="pin"` (`data-umber-pin="80px"`) | v4's `data-scroll-sticky` | Sticks to the top of the screen (or 80 px down) while its parent scrolls past: CSS `position: sticky`. The parent gets `var(--umber-pin)`, 0..1 over the pin, which the pinned element inherits. Make the parent as tall as the pin should last. |
|
|
2699
|
+
| `data-umber="horizontal"` | (Lenis's `orientation` for a section) | On a section whose first child is a track wider than the screen: the track sticks and slides sideways as the page scrolls down, a px across for a px down. The module makes the section as tall as that needs (a screen more than the distance), whatever the track's height. `var(--umber-horizontal)` (0..1) is how far along it is. |
|
|
2700
|
+
| `data-umber-snap` (`="start"`) | `lenis/snap` | A point the scroll settles on, a moment after the wheel or a finger stops: the element's start, `center` or `end` (or several). With the scroll module. |
|
|
2701
|
+
|
|
2702
|
+
GL planes: a plane on (or inside) an element the module moves (`data-umber-speed`, `-lag`) is drawn with the same move in the same frame, from the engine's own placement (`plane.offset`): the engine measures it without the move, so it needs no measure per frame. Planes inside a pinned element or a horizontal track already are (sticky parents). An effect that declares `uPlaneVelocity` or `uPlaneLag` gets the element's own (`data-umber-velocity`, `data-umber-lag`):
|
|
2703
|
+
|
|
2704
|
+
```js
|
|
2705
|
+
umber.effect("smear", {
|
|
2706
|
+
uniforms: { uPlaneVelocity: 0 }, // the element's own velocity, -1..1
|
|
2707
|
+
vertex: { main: "pos.y += uPlaneVelocity * sin(uv.x * 3.14159) * 40.0;" },
|
|
2708
|
+
});
|
|
2709
|
+
```
|
|
2710
|
+
```html
|
|
2711
|
+
<img data-umber="image" data-umber-effect="smear" data-umber-velocity="0.08" src="work.jpg" alt="">
|
|
2712
|
+
<h2 data-umber="inview" data-umber-call="title">Work</h2>
|
|
2713
|
+
<div data-umber-progress="--p" style="opacity: calc(1 - var(--p))">Fades as it leaves</div>
|
|
2714
|
+
<figure data-umber-speed="-0.15"><img src="hero.jpg" alt=""></figure>
|
|
2715
|
+
```
|
|
2716
|
+
|
|
2717
|
+
A pinned section and a horizontal one:
|
|
2718
|
+
|
|
2719
|
+
```html
|
|
2720
|
+
<section style="height: 300vh">
|
|
2721
|
+
<div data-umber="pin" style="height: 100vh">Stays while the section scrolls past; var(--umber-pin) runs 0..1.</div>
|
|
2722
|
+
</section>
|
|
2723
|
+
<section data-umber="horizontal">
|
|
2724
|
+
<div style="display: flex; height: 100vh">
|
|
2725
|
+
<article style="flex: none; width: 80vw">One</article>
|
|
2726
|
+
<article style="flex: none; width: 80vw">Two</article>
|
|
2727
|
+
<article style="flex: none; width: 80vw">Three</article>
|
|
2728
|
+
</div>
|
|
2729
|
+
</section>
|
|
2730
|
+
```
|
|
2731
|
+
|
|
2732
|
+
### Snapping
|
|
2733
|
+
|
|
2734
|
+
`data-umber-snap` elements are the points. After the last wheel or touch move (`debounce`, 150 ms), the glide still under way is turned toward the point nearest where it is heading: one motion, not a stop and a second move. `"proximity"` (the default) snaps only to a point within `distance` (half a screen); `"mandatory"` always snaps (`data-umber-snap-type="mandatory"` on `<body>` says the same). Keys, the scrollbar and `scrollTo()` don't snap. A snap's move carries `userData: { initiator: "snap" }`.
|
|
2735
|
+
|
|
2736
|
+
```js
|
|
2737
|
+
umber.use(ScrollFx, { snap: { type: "mandatory", duration: 0.8, onSnapComplete: ({ index }) => console.log(index) } });
|
|
2738
|
+
umber.scrollFx.snap.next(); // previous(), goTo(index), stop(), start()
|
|
2739
|
+
```
|
|
2740
|
+
|
|
2741
|
+
| `snap` option | Default | |
|
|
2742
|
+
|---|---|---|
|
|
2743
|
+
| `type` | `"proximity"` | Or `"mandatory"`. |
|
|
2744
|
+
| `distance` | `"50%"` | px, or a share of a screen, for proximity. |
|
|
2745
|
+
| `debounce` | `150` | ms after the last move. |
|
|
2746
|
+
| `lerp`, `duration`, `easing` | the scroll module's | The snap's own move. |
|
|
2747
|
+
| `onSnapStart`, `onSnapComplete` | | `({ index, value })`. |
|
|
2748
|
+
|
|
2749
|
+
`snap: false` turns it off. The module's other options: `velocitySmooth` (the default smoothing of `data-umber-velocity`, `0.12`) and `fullSpeed` (px/s that reads as 1, `3600`).
|
|
2750
|
+
|
|
2751
|
+
### Good to know
|
|
2752
|
+
|
|
2753
|
+
- **Routers:** new content is picked up as it arrives (the engine's `"added"`), and elements that leave let go. `umber.scrollFx.scan(root)` picks up content no router reports.
|
|
2754
|
+
- **No DOM writes per frame:** the moves and variables go into one stylesheet the module adds (a rule per element, `[data-umber-fx="3"]`), so neither the site's MutationObservers nor Umber's DOM watch see them. Parallax and lag use the CSS `translate` property, which adds to an element's own `transform`.
|
|
2755
|
+
- **Horizontal pages** (`data-umber-scroll="horizontal"`): in-view, progress, parallax, lag and velocity follow the x axis.
|
|
2756
|
+
- **From Locomotive Scroll 5:** `data-scroll` + `data-scroll-class` become `data-umber="inview"`, `data-scroll-repeat` becomes `data-umber-inview-repeat`, `data-scroll-call` becomes `data-umber-call` (same detail), `data-scroll-css-progress` becomes `data-umber-progress` (same `--progress`), `data-scroll-speed` becomes `data-umber-speed` (same amount), `data-scroll-offset="10%,0"` becomes `data-umber-inview-start="top 90%"`, and `new LocomotiveScroll()` becomes the two modules.
|
|
2348
2757
|
|
|
2349
2758
|
---
|
|
2350
2759
|
|
|
2351
2760
|
## Utilities: tracking, the loop, maths
|
|
2352
2761
|
|
|
2353
|
-
Small tools for the jobs GL work always needs.
|
|
2762
|
+
Small tools for the jobs GL work always needs.
|
|
2354
2763
|
|
|
2355
|
-
###
|
|
2764
|
+
### umber.track(el): where an element is, every frame, without WebGL
|
|
2356
2765
|
|
|
2357
2766
|
```js
|
|
2358
|
-
const t =
|
|
2767
|
+
const t = umber.track(".card"); // works with GL off (phones, Save-Data) too
|
|
2359
2768
|
t.rect; // { x, y, width, height } in viewport CSS px this frame, like getBoundingClientRect
|
|
2360
2769
|
t.inView; // on screen
|
|
2361
2770
|
t.near; // within 1.5 screens
|
|
@@ -2365,7 +2774,7 @@ const off = t.on("enter", (t) => {}); // also "leave", "resize", "destroy"; on
|
|
|
2365
2774
|
t.destroy(); // automatic when the element leaves the page
|
|
2366
2775
|
```
|
|
2367
2776
|
|
|
2368
|
-
A scroll over a still layout reads nothing: the element is measured once and moved with the absolute scroll position, like a plane (measured again on a resize, or a style or class change on it or a parent). `
|
|
2777
|
+
A scroll over a still layout reads nothing: the element is measured once and moved with the absolute scroll position, like a plane (measured again on a resize, or a style or class change on it or a parent). `umber.track(el, { live: true })` measures it every frame (detected by itself for sticky, fixed and pinned parents).
|
|
2369
2778
|
|
|
2370
2779
|
### Signals: live `{ value }` objects Umber keeps up to date
|
|
2371
2780
|
|
|
@@ -2373,29 +2782,29 @@ A Signal is a plain `{ value }` that Umber writes every frame it changes. Read i
|
|
|
2373
2782
|
|
|
2374
2783
|
```js
|
|
2375
2784
|
// 0..1 as an element scrolls through: "<element edge> <viewport line>", the same syntax as scrub
|
|
2376
|
-
const p =
|
|
2785
|
+
const p = umber.progress(".story", { start: "top top", end: "bottom bottom" });
|
|
2377
2786
|
p.value; // this frame's progress (works with GL off too)
|
|
2378
2787
|
p.on("change", (p) => {}); // also "destroy"; each on() returns its off()
|
|
2379
2788
|
p.destroy(); // automatic when the element leaves the page
|
|
2380
2789
|
|
|
2381
|
-
|
|
2382
|
-
|
|
2383
|
-
|
|
2384
|
-
|
|
2790
|
+
umber.progress(el); // default: "top bottom" to "bottom top"
|
|
2791
|
+
umber.progress(el, { start: "top+=100 80%", end: "center center-=10%" }); // px and % offsets (not in a play's `start`)
|
|
2792
|
+
umber.progress(el, { start: "entry", end: "exit" }); // CSS view-timeline ranges: cover, contain, entry, exit, entry-crossing, exit-crossing ("entry 50%", "cover 50px")
|
|
2793
|
+
umber.progress(".hero", { css: "--hero" }); // also as a CSS variable on the element: opacity: calc(1 - var(--hero))
|
|
2385
2794
|
|
|
2386
|
-
|
|
2387
|
-
|
|
2388
|
-
|
|
2795
|
+
umber.pointer.value; // [x, y] viewport CSS px (mouse, pen, touch)
|
|
2796
|
+
umber.pointer.velocity.value; // [vx, vy] px per second, smoothed, 0 at rest
|
|
2797
|
+
umber.pointer.active; // false until it first moved (value is the viewport's centre)
|
|
2389
2798
|
|
|
2390
|
-
|
|
2391
|
-
|
|
2799
|
+
umber.effect("story", { uniforms: { uStory: p, uPointer: umber.pointer, uSpeed: umber.pointer.velocity }, ... });
|
|
2800
|
+
umber.plane(el)?.set("uStory", umber.progress(el.closest("section"))); // per plane: set() links it too
|
|
2392
2801
|
```
|
|
2393
2802
|
|
|
2394
|
-
- `
|
|
2395
|
-
- `css: "--name"` writes the value (4 decimals) only when it changed, into a rule of Umber's own stylesheet that matches that element (it gets `data-
|
|
2803
|
+
- `umber.progress()` is a tracker underneath: measured once, then moved with the **absolute** scroll in the measure phase, so it is right with native scroll, a scrolling element (`createUmber({ scroll: el })`) and a Lenis you passed in. It never keeps the loop awake; scrolling, resizes and DOM changes wake it, and that is when it changes.
|
|
2804
|
+
- `css: "--name"` writes the value (4 decimals) only when it changed, into a rule of Umber's own stylesheet that matches that element (it gets `data-umber-css="n"`), never its `style` attribute: no DOM change, so no layout read and no observer wakes. The property stays at its last value after the signal ends.
|
|
2396
2805
|
- Range names follow CSS `animation-range`: `cover` is `top bottom` to `bottom top`; `contain` is the part where the element is fully on screen (or covers the whole screen, when taller); `entry` and `exit` are the parts where it comes in and goes out. A name alone is its 0% as a `start` and its 100% as an `end`.
|
|
2397
|
-
- `
|
|
2398
|
-
- `
|
|
2806
|
+
- `umber.pointer` attaches its passive listeners the first time anything reads it, and keeps the loop awake only while its velocity settles back to 0. To use it in GLSL, compare with the pixel's own viewport position: `vec2 d = screenPx() - uPointer;` (`screenPx()` is right also on a rotated or tilted element).
|
|
2807
|
+
- `umber.velocity` (scroll) is a Signal too. Any `{ value }` of your own works as a uniform; Umber reads it on frames it draws anyway, so call `umber.wake()` after changing it while nothing else moves.
|
|
2399
2808
|
- More inputs (a drag, the speed of any Signal, the pointer's trail, presses, steps) come with the input module: see Inputs.
|
|
2400
2809
|
|
|
2401
2810
|
### The loop
|
|
@@ -2403,45 +2812,76 @@ gl.plane(el)?.set("uStory", gl.progress(el.closest("section"))); // per plane:
|
|
|
2403
2812
|
Umber runs one `requestAnimationFrame` loop with three phases per frame: **measure** (layout reads only), **update** (maths and writes) and **render** (WebGL). It sleeps when nothing changes: a still page runs no frames at all.
|
|
2404
2813
|
|
|
2405
2814
|
```js
|
|
2406
|
-
const off =
|
|
2407
|
-
// f = { time, dt, ratio, frame, woke, scroll: { x, y, velocity } }
|
|
2815
|
+
const off = umber.on("frame", (f) => {
|
|
2816
|
+
// f = { time, dt, ratio, frame, woke, scroll: { x, y, velocity }, budget() }
|
|
2408
2817
|
}, { phase: "update", order: 0 }); // keeps the loop running every frame while it is on
|
|
2409
2818
|
|
|
2410
|
-
|
|
2819
|
+
umber.on("frame", followPlanes, { phase: "render", always: false }); // only on frames Umber runs anyway
|
|
2820
|
+
umber.on("frame", collide, { fps: 30 }); // at most 30 runs a second; f.dt is the time since it last ran
|
|
2821
|
+
umber.on("frame", sparkle, { fps: "50%" }); // on every other frame the loop runs ("33%": one in three)
|
|
2822
|
+
umber.on("frame", (f) => { while (jobs.length && f.budget() > 2) jobs.shift()(); }); // f.budget(): ms left in this frame
|
|
2411
2823
|
|
|
2412
|
-
|
|
2413
|
-
|
|
2824
|
+
umber.velocity.value; // the scroll speed effects get as uScrollVelocity: px/s / 3600, clamped to -1..1 and smoothed (a plain { value })
|
|
2825
|
+
umber.wake(2); // run at least 2 more frames
|
|
2414
2826
|
|
|
2415
|
-
const cancel =
|
|
2416
|
-
|
|
2827
|
+
const cancel = umber.nextFrame((f) => {}); // once, on the next frame (update phase)
|
|
2828
|
+
umber.nextFrame(() => readLayout(), { phase: "measure" }); // or in another phase
|
|
2417
2829
|
```
|
|
2418
2830
|
|
|
2419
|
-
**Your own loop instead:** `
|
|
2831
|
+
**Your own loop instead:** `createUmber({ loop: false })`, then call `umber.render(time)` once per frame with the frame time in **ms**:
|
|
2832
|
+
|
|
2833
|
+
```js
|
|
2834
|
+
const umber = Umber.createUmber({ loop: false });
|
|
2835
|
+
gsap.ticker.add((t) => umber.render(t * 1000)); // GSAP's ticker
|
|
2836
|
+
renderer.setAnimationLoop((t) => { umber.render(t); }); // or three.js's loop
|
|
2837
|
+
```
|
|
2838
|
+
|
|
2839
|
+
Calling `umber.render()` while Umber runs its own loop warns and does nothing (use `createUmber({ loop: false })`). Calling it twice in one frame (two loops) warns.
|
|
2840
|
+
|
|
2841
|
+
`f.budget()` is the ms left before this frame takes longer than the screen's frame time (16.7 ms at 60 Hz, 6.9 at 144 Hz), live: call it again after some work. Below 0 the frame is late already. A throttled callback (`fps`) never wakes a sleeping loop and does not make up for frames the loop slept through.
|
|
2842
|
+
|
|
2843
|
+
**The whole clock:** `umber.loop.pause()` stops every frame callback (with `patch`, the page's own loops too) until `umber.loop.play()`, which goes on where it stopped (`f.time` does not jump). `umber.loop.restart()` starts `f.time` and `f.frame` from 0 again. `umber.loop.playing`, and `umber.loop.fps`: the screen's frame rate as measured. This is not `umber.pause()`, which lets the DOM show and holds GL's planes while the clock runs on.
|
|
2844
|
+
|
|
2845
|
+
#### One clock for the whole page: `patch`
|
|
2846
|
+
|
|
2847
|
+
`createUmber({ patch: true })`, or `data-umber-patch` on the `umber.js` tag, makes every `requestAnimationFrame` loop on the page run inside Umber's frame: GSAP's ticker, Lenis, three.js's `setAnimationLoop`, Motion, a canvas loop of yours, minified third-party code. One `requestAnimationFrame` per frame, in this order:
|
|
2848
|
+
|
|
2849
|
+
1. **measure**: Lenis scrolls the page, then the scroll module, then the page's loops (GSAP and the rest, in the order they asked), then Umber reads the scroll and the page. What those loops wrote is drawn in the same frame.
|
|
2850
|
+
2. **update**: Umber's maths and your `umber.on("frame")` callbacks.
|
|
2851
|
+
3. **render**: Umber draws. A renderer of yours that should draw after Umber: `umber.on("frame", () => renderer.render(scene, camera), { phase: "render" })`.
|
|
2852
|
+
|
|
2853
|
+
```html
|
|
2854
|
+
<script src="https://umber.occluze.com/umber@x.y.z/umber.js" data-umber-key="YOUR_KEY" data-umber-patch></script>
|
|
2855
|
+
```
|
|
2420
2856
|
|
|
2421
2857
|
```js
|
|
2422
|
-
const
|
|
2423
|
-
|
|
2424
|
-
|
|
2858
|
+
const lenis = new Lenis({ autoRaf: true });
|
|
2859
|
+
const umber = Umber.createUmber({ scroll: lenis, patch: true }); // npm: the same option
|
|
2860
|
+
// npm, with a bundled GSAP (not on window): createUmber({ patch: { gsap } })
|
|
2425
2861
|
```
|
|
2426
2862
|
|
|
2427
|
-
|
|
2863
|
+
- **Lenis** (`scroll: lenis` with `autoRaf: true`): Umber turns its own loop off and calls `lenis.raf()` first in each frame, only while it scrolls, so a still page still sleeps, and the first frame after a sleep shows the scroll Lenis made in it. A Lenis you step yourself (`autoRaf: false`, from your own `requestAnimationFrame` loop or `gsap.ticker`) stays yours: that loop is patched in.
|
|
2864
|
+
- **GSAP** (`window.gsap`, or `patch: { gsap }`): its ticker asks for its frames through Umber from `createUmber()` on, and sleeps by itself when nothing tweens.
|
|
2865
|
+
- **Sleeping:** the loop runs as long as some loop on the page asks for the next frame. Nothing asks: no frame at all.
|
|
2866
|
+
- A library that keeps its own copy of `requestAnimationFrame` from before the patch (loaded before `umber.js`, or imported before `createUmber()` runs in a bundle) keeps its own frame; Umber follows it as without `patch`. `data-umber-patch` patches as `umber.js` runs: put the tag before the libraries.
|
|
2867
|
+
- `umber.destroy()` gives the page its own `requestAnimationFrame` back. With `loop: false` there is nothing to patch (your loop drives Umber).
|
|
2428
2868
|
|
|
2429
2869
|
### Scopes: one revert() for everything a component made
|
|
2430
2870
|
|
|
2431
2871
|
```js
|
|
2432
|
-
const scope =
|
|
2433
|
-
|
|
2434
|
-
|
|
2435
|
-
const p =
|
|
2436
|
-
|
|
2437
|
-
|
|
2872
|
+
const scope = umber.scope((s) => {
|
|
2873
|
+
umber.effect("bulge", bulge); // definitions (revert brings the old one back, or none)
|
|
2874
|
+
umber.add(".media", { effects: ["bulge"] }); // planes from code; selectors look inside `card`
|
|
2875
|
+
const p = umber.progress(card); // trackers and signals
|
|
2876
|
+
umber.on("frame", () => (bar.style.width = `${p.value * 100}%`), { always: false }); // frame callbacks, events
|
|
2877
|
+
umber.attach(".scene", { renderer, scene, camera }); // three.js views; also umber.view, umber.nextFrame, nested scopes
|
|
2438
2878
|
}, card);
|
|
2439
2879
|
|
|
2440
2880
|
scope.revert(); // all of it, newest first: planes go, Umber's attributes come off, effects unregister
|
|
2441
2881
|
```
|
|
2442
2882
|
|
|
2443
2883
|
- It records the Umber calls made **while fn runs**. After an `await`, call them on the scope itself (`s.add`, `s.track`, `s.progress`, `s.attach`, `s.view`, `s.effect`, `s.shader`, `s.layer`, `s.chunk`, `s.on`, `s.nextFrame`, `s.scope`, and `s.target`, `s.snapshot`, `s.sim`, `s.flow`, `s.brush`, `s.preload`, `s.warm`, `s.leave`, `s.flip`, plus every call a module adds: `s.drag`, `s.texture`...): those always belong to it.
|
|
2444
|
-
- What `revert()` does to the later calls: targets, snapshots, sims and brushes are released (a target asked for and reverted before it arrived is released when it does); `
|
|
2884
|
+
- What `revert()` does to the later calls: targets, snapshots, sims and brushes are released (a target asked for and reverted before it arrived is released when it does); `umber.leave()` goes back to the newest one still set (scopes may revert in any order; one set outside any scope stays), and a page change already holding or playing the old page finishes first; `umber.preload({ hover })` is turned off; a module's objects (`umber.drag`, `umber.trail`, `umber.texture`, `umber.touch`...) are destroyed and `umber.step()` stops. The page's one `umber.flow()` flowmap is released only by the scope whose call made it (one made before is shared: a scope that only tunes it with `umber.flow({ fade })` leaves it, with those options), and kept while a plane reads `uFlow`. `umber.warm()`, `umber.flip()` and a plain `umber.preload()` hold nothing to undo (images made ahead are freed after 20 s unless a plane claims them).
|
|
2445
2885
|
- `revert()` while an async fn still awaits is safe: that run's calls through `s` then make nothing (`s.add()` resolves `null`), so a fast mount and unmount never leaks. `s.reverted` tells the rest of fn to stop.
|
|
2446
2886
|
- `scope.run(fn)` runs more code in the scope later; `await scope.ready` waits for an async fn. A scope made inside another goes with it. A fn that throws is logged; what it made before stays in the scope.
|
|
2447
2887
|
- Umber never reads GSAP, so it does not join a `gsap.context()`: call `scope.revert()` next to `ctx.revert()` (or inside your framework's unmount).
|
|
@@ -2456,7 +2896,7 @@ clamp(v, 0, 1);
|
|
|
2456
2896
|
lerp(a, b, t);
|
|
2457
2897
|
mapRange(v, inMin, inMax, outMin, outMax);
|
|
2458
2898
|
smoothstep(0.2, 0.8, v); // GLSL's: 0 below, 1 above, smooth between
|
|
2459
|
-
rectProgress(el.getBoundingClientRect(), "top bottom", "bottom top"); //
|
|
2899
|
+
rectProgress(el.getBoundingClientRect(), "top bottom", "bottom top"); // umber.progress's maths on any rect
|
|
2460
2900
|
```
|
|
2461
2901
|
|
|
2462
2902
|
Plus the DOM ↔ 3D helpers in three.js: `rectToWorld`, `worldToRect`, `pxPerWorld`, `fitCamera`.
|
|
@@ -2464,43 +2904,49 @@ Plus the DOM ↔ 3D helpers in three.js: `rectToWorld`, `worldToRect`, `pxPerWor
|
|
|
2464
2904
|
### Modules
|
|
2465
2905
|
|
|
2466
2906
|
```js
|
|
2467
|
-
import {
|
|
2907
|
+
import { createUmber } from "@occluze/umber";
|
|
2468
2908
|
import { Scrub } from "@occluze/umber/scrub";
|
|
2469
2909
|
import { Debug } from "@occluze/umber/debug";
|
|
2470
2910
|
|
|
2471
|
-
const
|
|
2472
|
-
// or later, for this engine:
|
|
2911
|
+
const umber = createUmber({ modules: [[Scrub, { cacheMB: 128 }], Debug] }); // optional modules, from the start
|
|
2912
|
+
// or later, for this engine: umber.use(Scrub, { cacheMB: 128 }).use(Debug);
|
|
2473
2913
|
```
|
|
2474
2914
|
|
|
2475
|
-
|
|
2915
|
+
An add-on named in `data-umber-modules` on the `umber.js` tag loads at once from the same version, and so does a module script of its own (`modules/scrub.js`, `modules/debug.js`): it registers itself (with `Umber.use()`: for the engine on the page and every later one); load it before or after `umber.js`, always from the **same version**. A module from another version warns: `modules/scrub.js 0.1.1 with umber.js 0.1.0: load both from the same version.` Any difference warns, even a patch (the full version strings are compared). An attribute of a module that is not loaded warns too: `data-umber-scrub on <video.hero>: no module "scrub". Load modules/scrub.js next to umber.js...`. A module's api lands on each plane it handles at `plane[module.name]` (`umber.plane(el).scrub`), so `umber.use()` refuses a module named like the plane's own members (`play`, `set`, `get`, `tween`, `on`, `destroy`... or any name starting with `_`) and warns: `module "play": plane.play is Umber's own. Rename the module.` A name that is one of the plane's inner fields (`mouse`, `texture`...) is only known once GL is loaded: the module still runs, its api stays off the plane, and Umber warns the same way.
|
|
2476
2916
|
|
|
2477
2917
|
---
|
|
2478
2918
|
|
|
2479
|
-
## Debugging: warnings,
|
|
2919
|
+
## Debugging: warnings, umber.inspect, the debug module
|
|
2920
|
+
|
|
2921
|
+
### Where Umber talks, and the one switch
|
|
2922
|
+
|
|
2923
|
+
- **On your own computer** (`localhost`, `*.localhost`, `*.test`, and a private IP address such as `192.168.1.20` for a phone on the same Wi-Fi): every warning and error shows, and a first line says what a live site needs (its key) and how add-ons load.
|
|
2924
|
+
- **On staging or anywhere else, while you test:** `data-umber-debug` on the `umber.js` tag, or `?umber-debug` in the address. It turns on every warning, error and debug note, for the core and every add-on, and loads the debug overlay (no `modules/debug.js` tag needed). With npm: `createUmber({ debug: true })`.
|
|
2925
|
+
- **On a live site, without it:** quiet. Two lines can still show, because a visitor's page is affected: the licence (no key, or the site isn't on the account's domains) and **Umber's own failure** (`umber.reason` `"context"`, `"context-lost"`, `"load-failed"`, `"load-timeout"` or `"error"`). That line ends with a link to occluze.com that opens a bug report filled in with the version, the browser and the reason: tell the user to send it if it keeps happening.
|
|
2480
2926
|
|
|
2481
2927
|
### Warnings that name the fix
|
|
2482
2928
|
|
|
2483
|
-
Every message starts with `[umber]`, is shown **once**, and says what to change. After 100 messages Umber stays quiet for the visit.
|
|
2929
|
+
Every message starts with `[umber]`, is shown **once**, and says what to change. After 100 messages Umber stays quiet for the visit. Warnings and errors (a shader that does not compile, a callback that threw) show on localhost and with debug on; a live site stays quiet unless `createUmber({ warnings: true })`, and `createUmber({ warnings: false })` silences them anywhere. Umber never throws at the page, with one exception: `umber.texture()` from the input module throws a TypeError naming the fix when it gets no source, or numbers without a size. Anywhere else, when something fails, that element's DOM shows.
|
|
2484
2930
|
|
|
2485
2931
|
| You did | Umber says (shortened) |
|
|
2486
2932
|
|---|---|
|
|
2487
|
-
| `data-
|
|
2933
|
+
| `data-umber-effect="disolve"` | `data-umber-effect="disolve" on <div#typo>: no effect with that name (did you mean "dissolve"?). Define it first with umber.effect("disolve", {...}): Umber ships no effects...` |
|
|
2488
2934
|
| `plane.set("uShw", 1)` | `plane.set("uShw") on <div.card>: no effect on this plane has a uniform "uShw", so no shader reads it (did you mean "uShow"?)...` |
|
|
2489
|
-
| a `data-
|
|
2490
|
-
| `
|
|
2491
|
-
| `
|
|
2492
|
-
| `
|
|
2935
|
+
| a `data-umber` element that is hidden or has no size | `<div#hidden> has data-umber but is 0×0 px after 3 s, so it draws nothing: hidden (display: none), or it has no size yet...` |
|
|
2936
|
+
| `umber.render()` from two loops | `umber.render() was called twice in one frame (two loops call it?). Call it from one loop only...` |
|
|
2937
|
+
| `umber.render()` with Umber's own loop on | `umber.render() was called while Umber runs its own loop (two loops?). Use createUmber({ loop: false })...` |
|
|
2938
|
+
| `createUmber()` twice | `createUmber() was called twice; returning the existing engine. Call umber.destroy() first to start fresh.` |
|
|
2493
2939
|
| `umber.js` and a module from different versions | `modules/scrub.js 0.1.1 with umber.js 0.1.0: load both from the same version.` |
|
|
2494
|
-
| `data-
|
|
2940
|
+
| `data-umber-scrub` without the module | `data-umber-scrub on <video.hero>: no module "scrub". Load modules/scrub.js next to umber.js...` |
|
|
2495
2941
|
| a video or image on another domain without CORS | `<video.hero>: the video at https://... is on another domain that sends no CORS headers, so it can't become a texture and the DOM video shows. Serve it with Access-Control-Allow-Origin...` |
|
|
2496
2942
|
| a shader that does not compile | The GLSL error with numbered source lines around it. |
|
|
2497
|
-
| a `clip-path: path()` (or `url()`, `shape()`) on a GL element or a parent | `<img.hero>: clip-path path("M 0 0 ...") on <div.mask> can't be drawn in GL, so its DOM shows. Use inset(), rect(), xywh(), circle(), ellipse() or polygon(), or add data-
|
|
2498
|
-
| a CSS mask on a parent of a GL element | `<div.card>: GL can't draw the CSS mask on <div.marquee>, so its DOM shows. Move the mask off the parents of GL elements, or add data-
|
|
2943
|
+
| a `clip-path: path()` (or `url()`, `shape()`) on a GL element or a parent | `<img.hero>: clip-path path("M 0 0 ...") on <div.mask> can't be drawn in GL, so its DOM shows. Use inset(), rect(), xywh(), circle(), ellipse() or polygon(), or add data-umber-clip="false" to draw it uncut.` |
|
|
2944
|
+
| a CSS mask on a parent of a GL element | `<div.card>: GL can't draw the CSS mask on <div.marquee>, so its DOM shows. Move the mask off the parents of GL elements, or add data-umber-clip="false" to draw it unmasked.` |
|
|
2499
2945
|
| three or more rounded / shaped clips on one element | `<div.card>: cut by too many rounded or shaped parents (<div.a>, <div.b>, <div.c>), so its DOM shows. Make one of them a straight overflow: hidden...` |
|
|
2500
2946
|
| a 3D tilt that turns part of an element behind the viewer | `<div.card>: part of it turns behind the viewer (3D transform on <div.tilt>), so its DOM shows until it turns back. Lower the angle or raise the perspective.` |
|
|
2501
2947
|
| in WebKit browsers (Safari, iOS), a tilt under a `perspective` parent that also has `overflow` and `border-radius` (WebKit draws that tilt flat; seen in Safari 26.6) | `<div.card>: WebKit draws a tilt flat when its perspective parent (<div.stage>) also has overflow and border-radius, so its DOM shows. Put the perspective on an inner element, or round the corners with clip-path: inset(0 round <radius>).` |
|
|
2502
2948
|
| `chunks/shapes.js` missing on your server, or so slow it takes more than 5 s | `<div.card>: it is cut, turned or tilted by CSS, and chunks/shapes.js failed to load (or: took more than 5 s to load), so its DOM shows. Serve chunks/shapes.js next to chunks/gl.js.` If it still arrives, GL draws those elements from then on. |
|
|
2503
|
-
| `chunks/glsl.js`, `chunks/instances.js`, `chunks/video.js`, `chunks/text.js`, `chunks/layers.js` or `chunks/fx.js` missing on your server, or so slow it takes more than 5 s | `chunks/video.js failed to load; GL videos and module elements show their DOM. (no answer in 5 s)` (for text: `chunks/text.js took more than 5 s to load; data-
|
|
2949
|
+
| `chunks/glsl.js`, `chunks/instances.js`, `chunks/video.js`, `chunks/text.js`, `chunks/layers.js` or `chunks/fx.js` missing on your server, or so slow it takes more than 5 s | `chunks/video.js failed to load; GL videos and module elements show their DOM. (no answer in 5 s)` (for text: `chunks/text.js took more than 5 s to load; data-umber="text" stays normal DOM text.`) The elements waiting for it show their DOM, a reveal too (for fx.js: planes that read `uBackdrop`; groups draw their members straight to the canvas). If it still arrives, GL takes it from then on and draws the elements that waited. |
|
|
2504
2950
|
| several GL elements facing you in one `preserve-3d` scene | `<div.face>: GL can't depth-sort several GL elements in one preserve-3d scene (<div.cube>), so their DOM shows. Add backface-visibility: hidden to faces that turn away, or use transform-style: flat.` |
|
|
2505
2951
|
| `offset-path` on a GL element or a parent | `<div.card>: offset-path on <div.x> moves it along a path GL does not follow, so its DOM shows. Animate transform instead.` |
|
|
2506
2952
|
| `zoom` on a parent of a turned element | `<div.card>: zoom on <div.x> scales it in a way GL can't follow together with its transforms, so its DOM shows. Use transform: scale() instead of zoom.` |
|
|
@@ -2508,75 +2954,77 @@ Every message starts with `[umber]`, is shown **once**, and says what to change.
|
|
|
2508
2954
|
| a `transform`, `perspective`, `contain` or `will-change` on `<body>` / `<html>`, a `filter` on `<body>` (or `zoom` on `<html>`) | `<body> has transform: matrix(...), which makes Umber's fixed canvas scroll or turn with the page, so GL is off and the DOM shows. Move the transform to a wrapper element inside <body>.` |
|
|
2509
2955
|
| a three.js layer under a rotation | `<div.scene>: a three.js layer is drawn upright; GL can't turn or tilt a layer's own drawing. Turn the camera in your scene instead.` |
|
|
2510
2956
|
|
|
2511
|
-
###
|
|
2957
|
+
### umber.inspect(el): why is this element (not) drawn?
|
|
2512
2958
|
|
|
2513
2959
|
```js
|
|
2514
|
-
|
|
2960
|
+
umber.inspect(".hero img"); // or an element; one inside a plane (its <img>) reports that plane
|
|
2515
2961
|
// [umber] inspect <div.hero>: not drawn: it is off screen (at 0, 2400 px; the screen is 1280×800)
|
|
2516
|
-
const report = await
|
|
2962
|
+
const report = await umber.inspect(".hero img");
|
|
2517
2963
|
```
|
|
2518
2964
|
|
|
2519
|
-
"On screen" means the visible screen (`innerWidth` × `innerHeight`), as for `plane.inView`. It is async (what it reads comes with `chunks/inspect.js`, fetched on the first call): it prints, and resolves with one report: `kind`, `status`, `drawn`, `why` (every reason it is not drawn, in words), `notes` (worth knowing but not stopping it: an unknown effect name, which it draws without), `source` (the image or video URL), `tier` (device tier, plus the scrub tier), `effects` with their options, `uniforms` with their values and `used` (does the compiled shader read it), `program`, `rect`, `inView`, `near`, `texture`, `modules`, and `clips`: every parent (or the element itself) that cuts it, as `{ el, by: "overflow" | "clip-path" | "clip" | "occlude", shape, how }`, where `how` is `"scissor"` (a straight clip, free), `"shader"` (rounded or shaped, per pixel), `"corners"` (a rounded parent hugging the image: its corners), `"pruned"` (it holds the whole element: cuts nothing; a `data-
|
|
2965
|
+
"On screen" means the visible screen (`innerWidth` × `innerHeight`), as for `plane.inView`. It is async (what it reads comes with `chunks/inspect.js`, fetched on the first call): it prints, and resolves with one report: `kind`, `status`, `drawn`, `why` (every reason it is not drawn, in words), `notes` (worth knowing but not stopping it: an unknown effect name, which it draws without), `source` (the image or video URL), `tier` (device tier, plus the scrub tier), `effects` with their options, `uniforms` with their values and `used` (does the compiled shader read it), `program`, `rect`, `inView`, `near`, `texture`, `modules`, and `clips`: every parent (or the element itself) that cuts it, as `{ el, by: "overflow" | "clip-path" | "clip" | "occlude", shape, how }`, where `how` is `"scissor"` (a straight clip, free), `"shader"` (rounded or shaped, per pixel), `"corners"` (a rounded parent hugging the image: its corners), `"pruned"` (it holds the whole element: cuts nothing; a `data-umber-occlude` panel: it misses the element this frame), `"ignored"` (that parent turns past the viewer right now) or `"uncut"` (a `data-umber-occlude` panel over it, with no clip slot free: GL draws over the panel there); and `geometry`: `{ transform: "none" | "2d" | "3d", size, corners, live }`, where `corners` is the quad GL draws (viewport px) and `live` says what measures it every frame right now (`"CSS transition on <div.card>, 0.32 s left"`, `"infinite CSS animation on <div.track>"`, `"scroll-driven CSS animation on <div.reveal>"`, `"data-umber-live"`, `"a sticky or fixed parent"`, `"live mode (a page change, umber.live())"`, or `null`). `why` also says when its back faces you (`backface-visibility: hidden`), when its clips hide it entirely (`it is entirely cut off by overflow: hidden on <div.slider>`) or when its DOM shows because of a clip GL can't draw. With GL off it says why (`GL is off for this visit: not a desktop device...`).
|
|
2520
2966
|
|
|
2521
2967
|
### The debug module (`modules/debug.js`): HUD, outlines, markers
|
|
2522
2968
|
|
|
2523
2969
|
Never on the live site: add it while you build.
|
|
2524
2970
|
|
|
2525
2971
|
```html
|
|
2526
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
2527
|
-
<script src="https://umber.occluze.com/umber@0.
|
|
2972
|
+
<script src="https://umber.occluze.com/umber@0.3.0/modules/debug.js"></script> <!-- the HUD -->
|
|
2973
|
+
<script src="https://umber.occluze.com/umber@0.3.0/modules/debug.js" data-outlines data-markers></script> <!-- all three -->
|
|
2528
2974
|
```
|
|
2529
2975
|
```js
|
|
2530
2976
|
import { Debug } from "@occluze/umber/debug";
|
|
2531
|
-
|
|
2977
|
+
umber.use(Debug, { hud: true, outlines: true, markers: true });
|
|
2532
2978
|
```
|
|
2533
2979
|
|
|
2534
|
-
`?umber-debug=hud,outlines,markers` in the URL picks the parts too (a bare `?umber-debug` also turns on debug notes in the console). `cost` adds the cost meter (below): `?umber-debug=hud,cost`, `
|
|
2980
|
+
`?umber-debug=hud,outlines,markers` in the URL picks the parts too (a bare `?umber-debug` also turns on debug notes in the console). `cost` adds the cost meter (below): `?umber-debug=hud,cost`, `umber.use(Debug, { cost: true })`.
|
|
2535
2981
|
|
|
2536
|
-
- **HUD** (bottom left; click its title to fold it, Ctrl/Cmd + Shift + H hides it): frame time and fps with a graph of the last 60 frames the loop ran, renders vs skipped frames, draw calls, planes on screen / all, shader programs, textures (how many, their MB, and the render targets' MB once groups, passes or sims run) and uploads, canvas size, DPR and adaptive scale, and **busy**: why it keeps drawing (`live`: a page change or `
|
|
2982
|
+
- **HUD** (bottom left; click its title to fold it, Ctrl/Cmd + Shift + H hides it): frame time and fps with a graph of the last 60 frames the loop ran, renders vs skipped frames, draw calls, planes on screen / all, shader programs, textures (how many, their MB, and the render targets' MB once groups, passes or sims run) and uploads, canvas size, DPR and adaptive scale, and **busy**: why it keeps drawing (`live`: a page change or `umber.live()`, `scroll`, `tween`, `upload`, `video`, `shader:name`, `dom-watch:<section#hero>`: the site restyled that element, which holds a plane, on that frame...). A still page should say `nothing (sleeping)`, and `umber.info.busy` is `[]` once the loop sleeps. The **gpu** row is the GPU tier: its level (0 to 5), why (`rule: <the part of the GPU's name that matched>` for levels 0 and 1, `default`, or `url` for `?umber-gpu`) and the GPU's name; the canvas row says `cut` when a weak GPU's wide window lowered the DPR.
|
|
2537
2983
|
- **Outlines:** a box on every plane exactly where GL draws it, labelled with its kind, effects and status. Green ready, amber loading, red gave up (the DOM shows); dashed when not drawn right now. A box that is off its element means the plane is off too. A purple dashed box marks each parent that cuts a plane (its overflow or clip-path box), where GL cuts it.
|
|
2538
2984
|
- **Markers:** for each effect that plays on scroll, a fixed line where its `start` sits on the screen and a dashed tick on the element edge that has to reach it; for each scrubbed video, its start and end lines.
|
|
2539
2985
|
- **Cost** (`cost: true`): what each effect stack costs per frame, as rows in the HUD, costliest first (`dissolve+grain: 0.42 cpu · 0.31 gpu ms`). Planes are grouped by their effects (or their shader, or their kind). `cpu` works on every GPU: frames are timed from the start of Umber's render until the GPU finished it, with every plane and with one group switched off for a few frames, in turn; the difference is that group's cost. `gpu` is a timer per draw, only where the browser exposes `EXT_disjoint_timer_query_webgl2` (desktop Chrome, Edge, Firefox); on Apple GPUs and phones (tile GPUs, which defer the drawing) read `cpu`. While on, the loop keeps drawing and each group blinks off for a few frames now and then: turn it on to compare effects, then off.
|
|
2540
2986
|
|
|
2541
|
-
|
|
2987
|
+
- **Profiler** (`profiler: true`, `?umber-debug=profiler`, or `await umber.loop.profile()` without the module): a panel (top right) with one bar for the frame's budget, the screen's frame time, and each frame callback as a piece of it in the order they run, red past the budget; under it one row per callback: its phase and order, its rate (`30 fps`, `50%`, `page` for one of the page's own loops under `patch`), its ms per frame averaged over about a second. Name your callbacks with `umber.on("frame", fn, { label: "hero" })`; Umber's own are `umber`, Lenis and GSAP under `patch` are `lenis` and `gsap`. Its button pauses and plays the whole clock (`umber.loop.pause()`). `chunks/profiler.js` loads only then; nothing is timed before or after. `const p = await umber.loop.profile({ panel: false }); p.read()` gives the same rows as data.
|
|
2988
|
+
|
|
2989
|
+
The panel and overlays never keep the loop awake (the cost meter does, while on). They go when the engine does (`umber.destroy()`).
|
|
2542
2990
|
|
|
2543
2991
|
### Devtools hooks
|
|
2544
2992
|
|
|
2545
|
-
- The canvas carries `data-
|
|
2993
|
+
- The canvas carries `data-umber-canvas` and `data-engine="umber <version>"`.
|
|
2546
2994
|
- `window.__umber = { version, engine, modules }`: the running engine (`__umber.engine.info`, `__umber.engine.inspect(el)`) from the console, on any site.
|
|
2547
2995
|
- `?umber-debug` turns on debug notes: GL tier, render scale changes, why GL is off.
|
|
2548
|
-
- `?umber=off` keeps every element on its DOM for this visit (`
|
|
2996
|
+
- `?umber=off` keeps every element on its DOM for this visit (`umber.reason` is `"disabled"`, no chunk loads): compare a page with and without GL.
|
|
2549
2997
|
- `?umber-gpu=<level>` forces a GPU tier for this visit, to see a site as a weaker or stronger device would (nothing is stored): `0` to `5` as a desktop, `m0` to `m5` as a phone, or `low` / `mid` / `high`. Anything else is ignored with a warning.
|
|
2550
2998
|
|
|
2551
2999
|
### Reporting to your own analytics
|
|
2552
3000
|
|
|
2553
|
-
Two engine events say what a visitor got, for the site's own analytics (Umber sends nothing anywhere). Both also go to `document` (`umber:off`, `umber:fallback`, the payload in `event.detail`), so a tag manager can listen without `
|
|
3001
|
+
Two engine events say what a visitor got, for the site's own analytics (Umber sends nothing anywhere). Both also go to `document` (`umber:off`, `umber:fallback`, the payload in `event.detail`), so a tag manager can listen without `umber`.
|
|
2554
3002
|
|
|
2555
3003
|
```js
|
|
2556
|
-
const
|
|
2557
|
-
// GL is off for this visit: at the start (a device it skips, ?umber=off) or later (a page with data-
|
|
2558
|
-
|
|
3004
|
+
const umber = Umber.createUmber();
|
|
3005
|
+
// GL is off for this visit: at the start (a device it skips, ?umber=off) or later (a page with data-umber-disable, too many WebGL context losses, an error inside a GL frame).
|
|
3006
|
+
umber.on("off", ({ reason }) => track("umber_off", { reason }));
|
|
2559
3007
|
// One element shows its DOM instead: `reason` is the warning's words, or null when something failed (a picture or video that didn't load, a shader that didn't compile).
|
|
2560
|
-
|
|
2561
|
-
|
|
3008
|
+
umber.on("fallback", ({ el, reason }) => track("umber_fallback", { id: el.id, reason }));
|
|
3009
|
+
umber.ready.then((on) => on && track("umber_on", { gpu: umber.info.tier }));
|
|
2562
3010
|
```
|
|
2563
3011
|
|
|
2564
|
-
`
|
|
3012
|
+
`umber.reason` is one of the codes in `UmberReason`. Send codes and short strings, never the element itself.
|
|
2565
3013
|
|
|
2566
3014
|
### Turning it off from the site (a remote off switch)
|
|
2567
3015
|
|
|
2568
|
-
`?umber=off` turns GL off for one visit. To turn it off for everyone without a release (a campaign page, a bad device), read your own flag before `
|
|
3016
|
+
`?umber=off` turns GL off for one visit. To turn it off for everyone without a release (a campaign page, a bad device), read your own flag before `createUmber()` and pass `devices: false`: the API stays the same (`umber.drag`, `umber.track`, `umber.progress` keep working), every element keeps its DOM, and no GL chunk loads (`umber.attach()` views stay off too, whatever their own `devices`).
|
|
2569
3017
|
|
|
2570
3018
|
```js
|
|
2571
3019
|
const flags = await fetch("/flags.json").then((r) => r.json()).catch(() => ({})); // your own, cached briefly
|
|
2572
|
-
const
|
|
3020
|
+
const umber = Umber.createUmber(flags.umberOff ? { devices: false } : {});
|
|
2573
3021
|
```
|
|
2574
3022
|
|
|
2575
3023
|
### GPU tiers
|
|
2576
3024
|
|
|
2577
|
-
When GL starts, Umber gives the device a level from its GPU's name (`
|
|
3025
|
+
When GL starts, Umber gives the device a level from its GPU's name (`umber.info.gpu`: `level`, `tier`, `mobile`, `renderer`, `reason`, `maxTexture`, `textureBudget`, `wide`):
|
|
2578
3026
|
|
|
2579
|
-
| level | band (`
|
|
3027
|
+
| level | band (`umber.info.tier`) | who | max DPR | largest texture | image memory |
|
|
2580
3028
|
|---|---|---|---|---|---|
|
|
2581
3029
|
| 0 | low | software renderers (no GPU) | 1 | 2048 | 96 MB |
|
|
2582
3030
|
| 1 | low | old or weak GPUs (Intel(R) HD 2000 to 5xxx, Mali-4xx / T, Adreno (TM) 2xx to 5xx, PowerVR) | 1 | 2048 | 96 MB |
|
|
@@ -2585,7 +3033,7 @@ When GL starts, Umber gives the device a level from its GPU's name (`gl.info.gpu
|
|
|
2585
3033
|
| 4 | high | desktops, every one Umber finds itself (an Apple M Pro, Max or Ultra, an RTX card: all 4, reason `default`) | 2 | 4096 | 192 MB |
|
|
2586
3034
|
| 5 | high | strong desktops: only with `?umber-gpu=5` | 2 | 4096 | 192 MB |
|
|
2587
3035
|
|
|
2588
|
-
- The max DPR is per band, so `
|
|
3036
|
+
- The max DPR is per band, so `createUmber({ dpr: { high, mid, low } })` still sets it.
|
|
2589
3037
|
- Safari only says "Apple GPU": a Mac gets 4, an iPhone or iPad with a touch screen under 820 px gets 2.
|
|
2590
3038
|
- A desktop at level 0 in a window wider than 1400 CSS px, or at level 1 wider than 1600, draws at DPR 0.8 from the first frame (a `[min, max]` dpr option's min still holds). Adaptive resolution still lowers it further when the GPU can't keep up.
|
|
2591
3039
|
- Levels 3 and 5 draw exactly like 2 and 4 today, so Umber does not look for strong GPUs by name: a device lands on 0, 1, 2 or 4, and 3 and 5 are there for `?umber-gpu`.
|
|
@@ -2600,48 +3048,68 @@ When GL starts, Umber gives the device a level from its GPU's name (`gl.info.gpu
|
|
|
2600
3048
|
Every site loads the engine from an **exact version**:
|
|
2601
3049
|
|
|
2602
3050
|
```
|
|
2603
|
-
https://umber.occluze.com/umber@0.
|
|
2604
|
-
umber.js window.Umber (
|
|
3051
|
+
https://umber.occluze.com/umber@0.3.0/
|
|
3052
|
+
umber.js window.Umber (version, createUmber, math, use). Small; loads chunks/gl.js lazily
|
|
2605
3053
|
umber.mjs the same API as an ES module (the npm package's entry)
|
|
2606
3054
|
umber.css the canvas host and the "hide once drawn" rules
|
|
2607
|
-
chunks/gl.js the GL runtime: downloaded once the device passes and the page has [data-
|
|
3055
|
+
chunks/gl.js the GL runtime: downloaded once the device passes and the page has [data-umber], or on the first umber.renderer(), umber.view(), umber.target(), umber.snapshot(), umber.sim(), umber.flow(), umber.placeholder(), umber.preload() or umber.warm()
|
|
2608
3056
|
chunks/shapes.js clips, turns and tilts: downloaded only when a GL element is cut, turned or tilted by CSS or by an animation
|
|
2609
|
-
chunks/text.js GL text: downloaded only when the page has data-
|
|
2610
|
-
chunks/
|
|
2611
|
-
chunks/
|
|
3057
|
+
chunks/text.js GL text: downloaded only when the page has data-umber="text" (nothing to add for it)
|
|
3058
|
+
chunks/curves.js GL text from prepared fonts: downloaded by chunks/text.js only when a GL text uses a font the asset tool prepared
|
|
3059
|
+
chunks/layers.js three.js on Umber's canvas: downloaded on the first data-umber="layer", umber.renderer() or umber.view()
|
|
3060
|
+
chunks/morph.js data-umber-id flights: downloaded on the first data-umber-id
|
|
2612
3061
|
chunks/video.js GL videos and module frames: downloaded on the first GL <video> or module element
|
|
2613
|
-
chunks/glsl.js
|
|
3062
|
+
chunks/glsl.js umber.chunk() includes and helper renaming: downloaded on the first effect stack that needs them
|
|
2614
3063
|
chunks/restore.js getting a lost WebGL context back: downloaded only when the browser returns it
|
|
2615
|
-
chunks/inspect.js
|
|
2616
|
-
chunks/
|
|
2617
|
-
chunks/
|
|
2618
|
-
chunks/
|
|
2619
|
-
chunks/
|
|
2620
|
-
chunks/
|
|
2621
|
-
chunks/
|
|
2622
|
-
chunks/
|
|
3064
|
+
chunks/inspect.js umber.inspect() and the words of rare warnings: downloaded on the first call or warning only
|
|
3065
|
+
chunks/vocabulary.js the check of data-umber's words: only where warnings show (localhost, debug)
|
|
3066
|
+
chunks/views.js the umber.attach() runtime: downloaded on the first umber.attach() only
|
|
3067
|
+
chunks/fx.js render targets (umber.target, umber.snapshot, uBackdrop, data-umber-pass, umber.leave): downloaded on the first of them
|
|
3068
|
+
chunks/sim.js umber.sim, umber.flow, umber.brush, uFlow: downloaded by chunks/fx.js on the first of them
|
|
3069
|
+
chunks/warm.js umber.preload(), umber.warm(), umber.placeholder(), data-umber-placeholder, hover prefetch: downloaded on the first of them
|
|
3070
|
+
chunks/flip.js umber.flip(), plane.lift()/land(), picture swaps (uSwap): downloaded on the first of them
|
|
3071
|
+
chunks/instances.js data-umber-instances: downloaded on the first plane with instances
|
|
3072
|
+
chunks/covers.js the check when a data-umber-id flight lands: downloaded by chunks/morph.js on the first landing
|
|
3073
|
+
chunks/licence.js whether this site may run Umber: downloaded next to chunks/gl.js (never on localhost)
|
|
3074
|
+
chunks/badge.js the small Occluze badge: downloaded only on a preview address
|
|
3075
|
+
chunks/capture.js a frame-by-frame export by Kovo: downloaded only while Kovo records the page
|
|
3076
|
+
chunks/basis.js hand-made KTX2 pictures (data-umber-src="....ktx2"): downloaded on the first one, with basis_transcoder.js and .wasm next to it
|
|
3077
|
+
chunks/prepared.js pictures the asset tool prepared: downloaded by chunks/gl.js on the first one
|
|
3078
|
+
chunks/patch.js the page's own requestAnimationFrame loops in Umber's frame: only with createUmber({ patch: true }) or data-umber-patch
|
|
3079
|
+
chunks/profiler.js umber.loop.profile() and the debug module's profiler: downloaded on the first of them
|
|
2623
3080
|
modules/scrub.js scroll-scrubbed video (script; registers itself) modules/scrub.mjs (ES module)
|
|
2624
|
-
modules/debug.js HUD, outlines, markers, cost (script; registers itself) modules/debug.mjs (ES module)
|
|
2625
|
-
modules/input.js
|
|
2626
|
-
modules/handoff.js data-
|
|
2627
|
-
modules/scroll.js smooth scrolling on Umber's own loop,
|
|
3081
|
+
modules/debug.js HUD, outlines, markers, cost, profiler (script; registers itself) modules/debug.mjs (ES module)
|
|
3082
|
+
modules/input.js umber.drag, velocityOf, trail, press, step, textures (script; registers itself) modules/input.mjs (ES module)
|
|
3083
|
+
modules/handoff.js data-umber-id flights across full page loads, View Transitions, cover pass (script; registers itself) modules/handoff.mjs (ES module)
|
|
3084
|
+
modules/scroll.js smooth scrolling on Umber's own loop, umber.scroll (script; registers itself) modules/scroll.mjs (ES module)
|
|
3085
|
+
modules/scroll-touch.js the scroll module's second file: downloaded by it only with touch: true
|
|
3086
|
+
modules/scrollfx.js scroll effects from attributes: in-view, progress, parallax, pins, snapping (script; registers itself) modules/scrollfx.mjs (ES module)
|
|
3087
|
+
modules/scroll-more.js the scroll module's third file: anchors, scrollTo() with an element, tweens, lock: downloaded by it on first need
|
|
3088
|
+
modules/router.js page changes without a full load, umber.router (script; registers itself) modules/router.mjs (ES module)
|
|
3089
|
+
modules/three.js glTF models (data-umber="model") and three.js helpers (script; registers itself) modules/three.mjs (ES module)
|
|
3090
|
+
modules/router-swap.js the router's second file: downloaded by it when the browser is idle, or at the first click
|
|
2628
3091
|
manifest.json the version and its file list
|
|
3092
|
+
integrity.json the Subresource Integrity hashes of umber.js and umber.css (versions released from now on)
|
|
2629
3093
|
```
|
|
2630
3094
|
|
|
2631
3095
|
Rules:
|
|
2632
3096
|
|
|
2633
|
-
- **
|
|
2634
|
-
- **Every site uses exactly these URLs.**
|
|
2635
|
-
- **
|
|
2636
|
-
- **Staging may use a channel:** `umber@0` is the newest 0.x.x, `umber@0.1` the newest 0.1.x. Channels redirect to an exact version and move as soon as a release is deployed. **Never `umber@latest`** on a real site. Pre-releases (like `0.2.0-beta.1`) never get a channel: load them by their exact URL.
|
|
3097
|
+
- **An exact version** (`umber@0.3.0`) never changes: for a site that must only change when someone chooses to.
|
|
3098
|
+
- **Every site uses exactly these URLs.** The one thing to add is the account's key, the same on all its sites.
|
|
3099
|
+
- **Moving links:** `umber@0.3`, `umber@0` and `umber@latest` redirect to the newest matching version and move with each release. Never use one in a site's install code: an exact version never changes, so nothing changes under the site. Pre-releases (like `0.2.0-beta.1`) load by their exact URL.
|
|
2637
3100
|
- **One version everywhere.** `umber.css`, `umber.js` and every `modules/*.js` must come from the same `umber@x.y.z/` folder. Never load `chunks/*.js` yourself: the engine loads them from its own folder.
|
|
2638
|
-
- **Don't add a `v`:** `umber@0.
|
|
2639
|
-
- **If GL doesn't start on a new
|
|
2640
|
-
- **
|
|
3101
|
+
- **Don't add a `v`:** `umber@0.3.0`, not `umber@v0.3.0`.
|
|
3102
|
+
- **If GL doesn't start on a new site** (`umber.reason` is `"unlicensed"`, and the console says the site has no key or isn't on the account's domains): check the key on the `umber.js` tag (or `createUmber({ key })`), turn on Approve automatically in the dashboard, in the dashboard at occluze.com/dashboard?view=umber, then reload the site. Site code can't fix it otherwise. `localhost` always works. The same licence covers `umber.scroll` and `umber.router`: on a site that isn't approved they stay native (the browser's scrolling, normal navigation). `await umber.licensed()` is the answer (`umber.licence` once it is in). `umber.reason` `"licence-unreachable"` is different: the check got no clear answer (umber.occluze.com unreachable or blocked by an extension, a firewall or the site's Content Security Policy: see Content Security Policy below). GL stays off on that visit; check `connect-src` first. The check needs an HTTPS page: a public page on plain `http://` shows the plain DOM.
|
|
3103
|
+
- **What the licence check sends** (for a privacy policy): one request to `https://umber.occluze.com/v2/check?k=<key>&h=<hostname>`, no cookies. Like any web request it reaches the server with the visitor's IP address, which is never stored, logged or passed on. Kept: the site's name, the account, first and last seen, a rough count; nothing about visitors. A browser keeps a yes for about a week, and 30 days if the check is down; a no ends it. Local hosts and private IP addresses send nothing.
|
|
3104
|
+
- **npm** (bundled sites): the public package `@occluze/umber` has the same files, with `exports` for `.`, `./scrub`, `./debug`, `./input`, `./handoff`, `./scroll`, `./scrollfx`, `./router`, `./three`, `./react`, `./vue`, `./svelte`, `./vite` (the Vite plugin), `./astro` (the Astro integration), `./assets` (the asset tool), `./module` (types only), `./global` (types only: `window.Umber` for a site that loads `umber.js` with a tag, `/// <reference types="@occluze/umber/global" />`), `./umber.css`, `./umber.js` and `./types`. Built with the Vite plugin or the Astro integration (`@occluze/umber/vite`, `@occluze/umber/astro`), the build copies its chunks into the site (`<assets>/umber@<version>/chunks/`) and the engine loads them from there, so the site is same-origin with nothing to set (`chunks: false` keeps the CDN; `vite dev` / `astro dev` use the CDN). With any other bundler they load from the CDN folder of the same version. `createUmber({ base })` or `window.UmberConfig = { base }` points them elsewhere (self-hosting: copy the package's `dist/chunks/` into a `umber@<version>/` folder and set `base` to it). The licence check always asks umber.occluze.com. Setup: `docs/npm.md`.
|
|
3105
|
+
|
|
3106
|
+
- **Browsers:** Chrome and Edge 92+, Firefox 101+, Safari 16.4+ (iOS and iPadOS 16.4+). Older browsers aren't supported; one without WebGL2 shows the plain page (`umber.reason` `"no-webgl2"`). Newer features are used where present, with a fallback: WebCodecs (`scrub`), `requestVideoFrameCallback` (GL video), `Intl.Segmenter` (GL text), `pageswap` (`handoff`), `scrollend` (`scroll`).
|
|
3107
|
+
- **Content Security Policy** (a site that sends one). By setup: `umber.js` from the CDN needs `script-src 'self' https://umber.occluze.com`, `style-src 'self' https://umber.occluze.com`, `connect-src 'self' https://umber.occluze.com`; npm built with the Vite plugin or the Astro integration needs only `script-src 'self'`, `style-src 'self'`, `connect-src 'self' https://umber.occluze.com` (the licence check); npm with another bundler adds `https://umber.occluze.com` to `script-src` (the chunks). Hand-made KTX2 files (`data-umber-src="....ktx2"`) add `script-src 'wasm-unsafe-eval'` and `worker-src blob:` (the transcoder runs in a `blob:` worker and compiles WebAssembly; Chrome and Edge before 97 and Firefox 101 need `'unsafe-eval'` in place of `'wasm-unsafe-eval'`) and `connect-src` for the chunk folder (it fetches `basis_transcoder.js` and `.wasm`); without them the transcoder can't start, and the picture falls back to its `<img>`'s own file (with a warning on localhost). Pictures from the asset tool need none of that. In detail: `script-src` for umber.js, `modules/*.js` and the `chunks/*.js` it `import()`s (the `data-umber-modules` add-on tags carry the umber.js tag's nonce); `style-src https://umber.occluze.com` (umber.css; no `'unsafe-inline'`: Umber's own rules for `umber.progress(el, { css })`, GL text's `--umber-lines` / `--umber-words` / `--umber-chars` and the `scroll`, `scrollfx`, `handoff` and `debug` add-ons go in adopted constructable stylesheets, and its inline styles through the `style` property, which `style-src` doesn't govern); `connect-src https://umber.occluze.com` (the licence check; blocked, `umber.reason` is `"licence-unreachable"`), plus `'self'` and the origins of the GL images and videos (Umber fetches images to decode them, blocked it falls back to an `<img>`; a cross-origin GL video gets a `GET` request, its body dropped once the headers are in; `umber.preload()`, `umber.warm()` and flights read ahead; the router fetches pages; `scrub` fetches its video); `img-src` / `media-src` for the same origins, and `img-src data:` with `data-umber-placeholder` / `umber.placeholder()` (the preview is a `data:` image). No `'unsafe-eval'` (beyond those older browsers' WebAssembly), and no worker, `blob:` or WebAssembly outside hand-made KTX2 files. Trusted Types isn't supported (`document.write` of the add-on tags, the router's script text). `handoff`'s head snippet is an inline `<script>`: the page's nonce on the pasted tag, its hash, or `'unsafe-inline'` in `script-src` (its rules go in a constructable stylesheet: nothing for `style-src`). The router runs the next page's scripts as fresh copies (and a script it ran before as inline code inside `{ }`), each with this page's nonce in place of one the next page's own policy gives (its `Content-Security-Policy` header or `<head>` `<meta http-equiv>`, the directive that rules the element, every policy that names nonces); any other nonce (an injected one, or every one on a page sent without a policy) is taken off, and under `'strict-dynamic'` such a script isn't run at all (there every script needs the nonce); stylesheets the same way. A nonce `script-src` works when the pages put the nonce on their scripts and in their policy; a hash `script-src` doesn't match the wrapped code, so there allow `'unsafe-inline'`, put `data-umber="skip"` on those scripts or set `umber.router.options.scripts = false`. Serving Umber's files from your own domain: that domain in place of `https://umber.occluze.com`.
|
|
3108
|
+
- **Checking a page:** `?umber=off` shows it without GL for that visit (`umber.reason` `"disabled"`); `?umber-debug` turns on every warning and debug note and the overlay, on any domain (more under Debugging).
|
|
2641
3109
|
|
|
2642
3110
|
To see which versions exist, open `https://umber.occluze.com/versions/` or `/versions.json`.
|
|
2643
3111
|
|
|
2644
|
-
**What's breaking:** removing or renaming any attribute (`data-
|
|
3112
|
+
**What's breaking:** removing or renaming any attribute or word (`data-umber`, `data-umber-*`), `createUmber()` option, engine or plane method, GLSL slot, input or helper, CSS hook (`has-umber`, `data-umber-status`), or event; or changing a visible default. Before 1.0 a breaking release renames outright, with no old spelling kept: the changelog says what to change, and the older version keeps working at its own URL.
|
|
2645
3113
|
|
|
2646
3114
|
---
|
|
2647
3115
|
|
|
@@ -2649,12 +3117,14 @@ To see which versions exist, open `https://umber.occluze.com/versions/` or `/ver
|
|
|
2649
3117
|
|
|
2650
3118
|
Go through this list before you hand over code for a site that uses Umber. Every line is a mistake that is easy to make and hard to see.
|
|
2651
3119
|
|
|
2652
|
-
1. **
|
|
2653
|
-
2. **
|
|
2654
|
-
3. **
|
|
2655
|
-
4. **
|
|
2656
|
-
5. **
|
|
2657
|
-
6. **
|
|
2658
|
-
7. **
|
|
2659
|
-
8. **
|
|
2660
|
-
9. **
|
|
3120
|
+
1. **What it is, how it behaves, what it's set to:** each GL element has exactly one kind in `data-umber` (`image`, `video`, `text`...), behaviours after it (`data-umber="image pin"`), and each setting as its own `data-umber-<setting>` attribute. Only the words in the Attributes table; a behaviour with a value only in its long form (`data-umber-pin="80px"`); `above` never on the element that holds the GL image. The attributes are `data-umber*`, the engine `createUmber()`, the object `umber`.
|
|
3121
|
+
2. **Tags and versions:** `umber.css` in `<head>`, `umber.js` before the code that calls `Umber.createUmber()`, modules from the **same** `umber@x.y.z/` folder. Use the URLs from the setup above; never invent a version, never load `chunks/*.js`. Always an exact `umber@x.y.z`, never a moving link (`umber@0.3`, `umber@latest`), so nothing changes under the site. The account's key goes on the `umber.js` tag (`data-umber-key`) or in `createUmber({ key })`.
|
|
3122
|
+
3. **One engine:** `createUmber()` once per visit, in code that runs once, never inside a Barba hook or a component's init. A component makes its Umber objects inside `umber.scope()` and calls `scope.revert()` on unmount.
|
|
3123
|
+
4. **No Umber code per page:** no `umber.scan()` in router hooks and no cleanup on page leave; planes come and go with the DOM, with any router. `umber.transition()` (or `umber.hold()` / `umber.live()` / `umber.morph.*`) only when you want them, and every `umber.transition()` gets its `end()`.
|
|
3124
|
+
5. **Libraries are yours:** set up Lenis and your router (Barba, Swup, Turbo...) the way their docs show, and pass the Lenis instance as `createUmber({ scroll: lenis })` (or load `modules/scroll.js` instead of Lenis, never both). Umber never creates, drives or configures them, and never needs GSAP.
|
|
3125
|
+
6. **Every effect is defined:** each name in `data-umber-effect` has a `umber.effect()` written for this site (Umber ships none). Options and uniforms use the names the effect declares (`data-umber-dissolve-scale` -> `uDissolveScale`).
|
|
3126
|
+
7. **The page works without GL:** GL runs on every device unless the site turns some off (`devices: "desktop"` / `data-umber-devices="desktop"`, or a media query: `media` / `data-umber-media`), and is off for Save-Data (or a 2G connection), reduced-motion "off", no WebGL2 and High Contrast. Never hide real content for an effect; always write `umber.plane(el)?.`.
|
|
3127
|
+
8. **Layering:** text or buttons over a GL image get `data-umber="above"`; a fixed nav, menus and overlays get a z-index above 1. A section with `z-index` 1 or more and a background hides the GL inside it: `umber.inspect(el)` says so, and Umber warns only on pages that load `chunks/shapes.js` (see Layering). Cross-origin images and videos need CORS headers.
|
|
3128
|
+
9. **umber.leave() and umber.flip() are GL only:** `umber.leave()` lays out the old page's GL, not its DOM; `umber.flip()` moves GL copies while the DOM jumps. Pair them with the router's or GSAP's own DOM animation, never both on one element.
|
|
3129
|
+
10. **Content Security Policy:** if the site sends one, take its lines from Hosting for its setup (CDN, Vite or Astro, another bundler). Umber needs no `'unsafe-inline'` and no `'unsafe-eval'`; only hand-made `.ktx2` pictures add `'wasm-unsafe-eval'` and `worker-src blob:`.
|
|
3130
|
+
11. **Test it:** one page change and back, a fast double click on a link, a narrow window, and the console: no `[umber]` warnings. `umber.inspect(el)` explains any element that is not drawn.
|