liquid-gl 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -14
- package/liquidGL.js +1797 -59
- package/package.json +1 -4
package/README.md
CHANGED
|
@@ -2,13 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
<a href="https://liquidgl.naughtyduk.com"><img src="https://raw.githubusercontent.com/naughtyduk/liquidGL/main/assets/liquidGL-npm-preview.gif" alt="liquidGL" width="100%" height="auto"/></a>
|
|
4
4
|
|
|
5
|
-
**v2.0.
|
|
5
|
+
**v2.0.1**
|
|
6
6
|
|
|
7
7
|
> [!NOTE]
|
|
8
8
|
> `liquidGL` is free to use for both non-commercial and commercial purposes. _BETA_ has now ended and the library is now ready for production use.
|
|
9
9
|
|
|
10
10
|
> [!WARNING]
|
|
11
|
-
> **v2.0.
|
|
11
|
+
> **v2.0.1 changes snapshot capture.** `liquidGL` now snapshots the page with its own built-in rasteriser, so `html2canvas` is no longer a dependency. Nothing needs to change in your code.
|
|
12
|
+
>
|
|
13
|
+
> | Rasteriser | Median | Min | Max | Worst single stall |
|
|
14
|
+
> | :------------ | :------ | :------ | :------- | :----------------- |
|
|
15
|
+
> | NaughtyDOM | 55.5 ms | 54.1 ms | 57.5 ms | 37.8 ms |
|
|
16
|
+
> | `html2canvas` | 86.3 ms | 85.3 ms | 134.8 ms | 16.2 ms |
|
|
17
|
+
>
|
|
18
|
+
> Measured over 7 alternating runs of the full home page at `resolution: 2` (2880×10036 output), Chrome 150.
|
|
19
|
+
>
|
|
20
|
+
> **v2.0.0 changed tilt behaviour.** The tilt interaction now eases symmetrically over the new `tiltEase` option (default `400`ms) in both directions, replacing the previous hard-coded `0.12s` ease-in and `0.4s` ease-out. If you depended on the old timing, set `tiltEase` explicitly. All other defaults are unchanged and existing configurations render identically.
|
|
12
21
|
|
|
13
22
|
`liquidGL` turns any fixed-position element into a perfectly refracted, glossy "glass pane" rendered in WebGL.
|
|
14
23
|
|
|
@@ -18,6 +27,14 @@
|
|
|
18
27
|
|
|
19
28
|
---
|
|
20
29
|
|
|
30
|
+
## What's new in v2.0.1
|
|
31
|
+
|
|
32
|
+
**Changes**
|
|
33
|
+
|
|
34
|
+
- **Built-in DOM snapshotter** — the `html2canvas` dependency has been replaced with an integrated rasteriser. The package now installs with no runtime dependencies.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
21
38
|
## What's new in v2.0.0
|
|
22
39
|
|
|
23
40
|
**New features**
|
|
@@ -54,7 +71,7 @@ const glassEffect = liquidGL({
|
|
|
54
71
|
});
|
|
55
72
|
```
|
|
56
73
|
|
|
57
|
-
> `
|
|
74
|
+
> `liquidGL` renders with raw WebGL and snapshots the page with its own built-in rasteriser, so it has no runtime dependencies.
|
|
58
75
|
|
|
59
76
|
---
|
|
60
77
|
|
|
@@ -225,23 +242,23 @@ Passing `gsap` lets `liquidGL` drive its render loop from the GSAP ticker and ke
|
|
|
225
242
|
|
|
226
243
|
## FAQ
|
|
227
244
|
|
|
228
|
-
| Question | Answer
|
|
229
|
-
| :----------------------------------------------------------------------- |
|
|
230
|
-
| Is there a resize handler? | Yes resize is handled in the library and debounced to 250ms for performance.
|
|
231
|
-
| Does the effect work on mobile? | Yes the library handles all 3 versions of WebGL and provides a frosted CSS `backdrop-filter` as a backup for older devices.
|
|
232
|
-
| I have a preloader, how should I initialise `liquidGL()`? | Add the `data-liquid-ignore` attribute to your preloader's top-level container to exclude it from the snapshot. You can then call `liquidGL()` inside a `DOMContentLoaded` listener as you normally would.
|
|
233
|
-
| What is the correct way to use `liquidGL` with page animations? | Lets say you have a preloader, above the fold intro animations and scroll animations on your page. You would:<br><br>1) set the `data-liquid-ignore` attribute on your preloader<br>2) animate your preloader and set up your initial animation states<br>3) then call `liquidGL();`<br>4) optionally, in the `on.init();` callback, you can run post snapshot scripts, such as animating the `target` element
|
|
234
|
-
| Can I use `liquidGL` on multiple elements? | Yes, any element which has the class declared as your `target` will be glassified. Note **all elements must use the same `z-index`** due to shared canvas optimisations, if you use different `z-index` values for multiple targets, the highest value will be used by `liquidGL`.
|
|
235
|
-
| Will the library exceed WebGL contexts or have other performance issues? | No, the library uses a shared canvas for all instances, we have tested up to 30 elements on one page and we were not able to cause performance problems or crashes.
|
|
236
|
-
| Are there any animation limitations? | It depends on what you're trying to do, rotation and scale are expensive CPU/GPU processes, additionally `shadow` `specular` and `tilt` should be used with care when you have lots of instances or complex animations as they can clog the render pipeline.
|
|
237
|
-
| Why does `liquidGL`
|
|
245
|
+
| Question | Answer |
|
|
246
|
+
| :----------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
247
|
+
| Is there a resize handler? | Yes resize is handled in the library and debounced to 250ms for performance. |
|
|
248
|
+
| Does the effect work on mobile? | Yes the library handles all 3 versions of WebGL and provides a frosted CSS `backdrop-filter` as a backup for older devices. |
|
|
249
|
+
| I have a preloader, how should I initialise `liquidGL()`? | Add the `data-liquid-ignore` attribute to your preloader's top-level container to exclude it from the snapshot. You can then call `liquidGL()` inside a `DOMContentLoaded` listener as you normally would. |
|
|
250
|
+
| What is the correct way to use `liquidGL` with page animations? | Lets say you have a preloader, above the fold intro animations and scroll animations on your page. You would:<br><br>1) set the `data-liquid-ignore` attribute on your preloader<br>2) animate your preloader and set up your initial animation states<br>3) then call `liquidGL();`<br>4) optionally, in the `on.init();` callback, you can run post snapshot scripts, such as animating the `target` element |
|
|
251
|
+
| Can I use `liquidGL` on multiple elements? | Yes, any element which has the class declared as your `target` will be glassified. Note **all elements must use the same `z-index`** due to shared canvas optimisations, if you use different `z-index` values for multiple targets, the highest value will be used by `liquidGL`. |
|
|
252
|
+
| Will the library exceed WebGL contexts or have other performance issues? | No, the library uses a shared canvas for all instances, we have tested up to 30 elements on one page and we were not able to cause performance problems or crashes. |
|
|
253
|
+
| Are there any animation limitations? | It depends on what you're trying to do, rotation and scale are expensive CPU/GPU processes, additionally `shadow` `specular` and `tilt` should be used with care when you have lots of instances or complex animations as they can clog the render pipeline. |
|
|
254
|
+
| Why does `liquidGL` use its own snapshotter rather than `snapdom`? | We evaluated `snapdom` and chose not to adopt it. It is faster at capture in isolation, but it rasterises through `foreignObject`, which introduces correctness problems that matter for a full-page background snapshot: CSS `background-image` does not paint inside `foreignObject` on WebKit, Chromium clips the output beyond the first viewport on long pages, and only in-viewport content is rasterised, so off-screen dynamic elements need re-capturing. The built-in rasteriser paints directly to a canvas, so none of those limits apply, and it ships as part of the library rather than as an extra dependency. |
|
|
238
255
|
|
|
239
256
|
---
|
|
240
257
|
|
|
241
258
|
## Important Notes
|
|
242
259
|
|
|
243
260
|
- For dynamic content to be refracted in real-time, you must register the element(s) with `liquidGL.registerDynamic()`. It is crucial to set the initial state of your animations **before** calling `liquidGL()` to ensure they are captured correctly.
|
|
244
|
-
- The library ignores `fixed` position elements, this is to prevent a known bug
|
|
261
|
+
- The library ignores `fixed` position elements, this is to prevent a known snapshotting bug on mobile browsers from surfacing which can prevent the snapshot from running. This is a safety net that shouldn't interfere with your use of the library.
|
|
245
262
|
- You can have multiple instances on one page **but they must share the same `z-index` value**. If you specify different `z-index` values, `liquidGL` will use the highest `z-index` for all elements with the `target` selector. This is because the effect uses a shared canvas to prevent WebGL context issues, there is no work around to this unfortunately.
|
|
246
263
|
- To improve performance on complex pages, you can snapshot a smaller, specific element like a background container instead of the whole page. Use the `snapshot` option with a CSS selector (e.g., `snapshot: '.my-background'`). This reduces texture memory and improves performance.
|
|
247
264
|
- The initial capture is asynchronous. Call `liquidGL()` inside a `DOMContentLoaded` or `load` handler to ensure content is available to the snapshot.
|