@docyrus/animaguru 0.6.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/NOTICE.md +256 -0
- package/README.md +241 -0
- package/dist/animaguru.js +27338 -0
- package/package.json +37 -0
- package/skills/animaguru/SKILL.md +115 -0
- package/skills/animaguru-advertising/SKILL.md +25 -0
- package/skills/animaguru-advertising/references/brand-bumper.md +11 -0
- package/skills/animaguru-advertising/references/comparison.md +11 -0
- package/skills/animaguru-advertising/references/creator-testimonial.md +11 -0
- package/skills/animaguru-advertising/references/editorial-advertorial.md +11 -0
- package/skills/animaguru-advertising/references/game-reward.md +11 -0
- package/skills/animaguru-advertising/references/offer-promotion.md +11 -0
- package/skills/animaguru-advertising/references/product-launch.md +11 -0
- package/skills/animaguru-advertising/references/product-proof.md +11 -0
- package/skills/animaguru-analog-film-tape/SKILL.md +29 -0
- package/skills/animaguru-analog-film-tape/references/recipe.md +23 -0
- package/skills/animaguru-animated-data-visualization/SKILL.md +39 -0
- package/skills/animaguru-animated-data-visualization/references/data-contract.md +16 -0
- package/skills/animaguru-animated-data-visualization/references/variants.md +17 -0
- package/skills/animaguru-art-deco-motion/SKILL.md +29 -0
- package/skills/animaguru-art-deco-motion/references/recipe.md +22 -0
- package/skills/animaguru-ascii-crt/SKILL.md +29 -0
- package/skills/animaguru-ascii-crt/references/recipe.md +22 -0
- package/skills/animaguru-blueprint-drafting/SKILL.md +29 -0
- package/skills/animaguru-blueprint-drafting/references/recipe.md +22 -0
- package/skills/animaguru-cartoon-character-animation/SKILL.md +35 -0
- package/skills/animaguru-cartoon-character-animation/references/variants.md +17 -0
- package/skills/animaguru-cutout-animation/SKILL.md +33 -0
- package/skills/animaguru-cutout-animation/references/production-recipe.md +37 -0
- package/skills/animaguru-cutout-animation/references/variants.md +17 -0
- package/skills/animaguru-cutout-animation/references/visual-style.md +34 -0
- package/skills/animaguru-dark-tech-stage/SKILL.md +29 -0
- package/skills/animaguru-dark-tech-stage/references/recipe.md +23 -0
- package/skills/animaguru-diagram-formula-motion/SKILL.md +36 -0
- package/skills/animaguru-diagram-formula-motion/references/variants.md +17 -0
- package/skills/animaguru-engraved-relief-print/SKILL.md +29 -0
- package/skills/animaguru-engraved-relief-print/references/recipe.md +24 -0
- package/skills/animaguru-flat-vector-motion/SKILL.md +35 -0
- package/skills/animaguru-flat-vector-motion/references/variants.md +17 -0
- package/skills/animaguru-general-video/SKILL.md +20 -0
- package/skills/animaguru-general-video/references/ambient-loop.md +11 -0
- package/skills/animaguru-general-video/references/music-lyrics.md +11 -0
- package/skills/animaguru-general-video/references/short-film.md +11 -0
- package/skills/animaguru-general-video/references/titles-event.md +11 -0
- package/skills/animaguru-general-video/references/visual-essay.md +11 -0
- package/skills/animaguru-generative-light-signal/SKILL.md +29 -0
- package/skills/animaguru-generative-light-signal/references/recipe.md +23 -0
- package/skills/animaguru-glass-mosaic/SKILL.md +29 -0
- package/skills/animaguru-glass-mosaic/references/recipe.md +23 -0
- package/skills/animaguru-halftone-editorial/SKILL.md +29 -0
- package/skills/animaguru-halftone-editorial/references/recipe.md +23 -0
- package/skills/animaguru-holographic-scan/SKILL.md +29 -0
- package/skills/animaguru-holographic-scan/references/recipe.md +22 -0
- package/skills/animaguru-interface-motion/SKILL.md +36 -0
- package/skills/animaguru-interface-motion/references/screen-mapping.md +16 -0
- package/skills/animaguru-interface-motion/references/variants.md +17 -0
- package/skills/animaguru-isometric-worlds/SKILL.md +35 -0
- package/skills/animaguru-isometric-worlds/references/variants.md +17 -0
- package/skills/animaguru-kinetic-typography/SKILL.md +35 -0
- package/skills/animaguru-kinetic-typography/references/variants.md +17 -0
- package/skills/animaguru-miniature-diorama/SKILL.md +29 -0
- package/skills/animaguru-miniature-diorama/references/recipe.md +23 -0
- package/skills/animaguru-painterly-depth-animation/SKILL.md +35 -0
- package/skills/animaguru-painterly-depth-animation/references/variants.md +17 -0
- package/skills/animaguru-paper-popup/SKILL.md +29 -0
- package/skills/animaguru-paper-popup/references/recipe.md +22 -0
- package/skills/animaguru-photo-footage-editorial/SKILL.md +29 -0
- package/skills/animaguru-photo-footage-editorial/references/recipe.md +23 -0
- package/skills/animaguru-pixel-art-animation/SKILL.md +36 -0
- package/skills/animaguru-pixel-art-animation/references/variants.md +17 -0
- package/skills/animaguru-portal-zoom/SKILL.md +29 -0
- package/skills/animaguru-portal-zoom/references/recipe.md +21 -0
- package/skills/animaguru-risograph-print/SKILL.md +29 -0
- package/skills/animaguru-risograph-print/references/recipe.md +23 -0
- package/skills/animaguru-sand-drawing/SKILL.md +29 -0
- package/skills/animaguru-sand-drawing/references/recipe.md +21 -0
- package/skills/animaguru-shadow-theatre/SKILL.md +29 -0
- package/skills/animaguru-shadow-theatre/references/recipe.md +23 -0
- package/skills/animaguru-silkscreen-poster/SKILL.md +29 -0
- package/skills/animaguru-silkscreen-poster/references/recipe.md +22 -0
- package/skills/animaguru-stop-motion-objects/SKILL.md +29 -0
- package/skills/animaguru-stop-motion-objects/references/recipe.md +23 -0
- package/skills/animaguru-studio-product-reveal/SKILL.md +29 -0
- package/skills/animaguru-studio-product-reveal/references/recipe.md +23 -0
- package/skills/animaguru-video/SKILL.md +79 -0
- package/skills/animaguru-whiteboard-line-drawing/SKILL.md +34 -0
- package/skills/animaguru-whiteboard-line-drawing/references/variants.md +17 -0
- package/templates/video/AGENTS.md +34 -0
- package/templates/video/CLAUDE.md +19 -0
- package/templates/video/README.md +101 -0
- package/templates/video/VIDEO-STYLE-NOTICES.txt +54 -0
- package/templates/video/film.config.json +10 -0
- package/templates/video/gitignore +11 -0
- package/templates/video/index.html +14 -0
- package/templates/video/package.json +28 -0
- package/templates/video/public/brand/logo-mark.svg +5 -0
- package/templates/video/scripts/build.mjs +12 -0
- package/templates/video/scripts/export-html.mjs +12 -0
- package/templates/video/scripts/export-mp4.mjs +209 -0
- package/templates/video/scripts/html-export-plugin.mjs +35 -0
- package/templates/video/scripts/html-export.mjs +54 -0
- package/templates/video/scripts/install-example.mjs +32 -0
- package/templates/video/scripts/review-analysis.mjs +29 -0
- package/templates/video/scripts/review-audio.mjs +24 -0
- package/templates/video/scripts/review.mjs +37 -0
- package/templates/video/scripts/starter-film.sha256 +1 -0
- package/templates/video/shared/locales/en/export.json +10 -0
- package/templates/video/shared/locales/en/film.json +42 -0
- package/templates/video/shared/locales/en/player.json +31 -0
- package/templates/video/shared/locales/en/style-studies.json +168 -0
- package/templates/video/shared/locales/en/timeline.json +33 -0
- package/templates/video/src/assets.ts +4 -0
- package/templates/video/src/download.ts +27 -0
- package/templates/video/src/exporter.ts +70 -0
- package/templates/video/src/film-resources.ts +29 -0
- package/templates/video/src/film.ts +132 -0
- package/templates/video/src/main.ts +219 -0
- package/templates/video/src/resource-timeline.ts +193 -0
- package/templates/video/src/review.ts +50 -0
- package/templates/video/src/studies/film.ts +26 -0
- package/templates/video/src/studies/media.ts +46 -0
- package/templates/video/src/studies/model.ts +60 -0
- package/templates/video/src/studies/pixi-renderer.ts +121 -0
- package/templates/video/src/studies/scenes.ts +410 -0
- package/templates/video/src/studies/timing.ts +53 -0
- package/templates/video/src/studies/variants.ts +39 -0
- package/templates/video/src/style.css +111 -0
- package/templates/video/src/timeline-model.ts +55 -0
- package/templates/video/style-source-provenance.json +11 -0
- package/templates/video/tsconfig.json +15 -0
- package/templates/video/vite.config.mjs +9 -0
- package/vendor/pixijs-skills/LICENSE +21 -0
- package/vendor/pixijs-skills/provenance.json +79 -0
- package/vendor/pixijs-skills/skills/pixijs/SKILL.md +66 -0
- package/vendor/pixijs-skills/skills/pixijs/references/index.md +136 -0
- package/vendor/pixijs-skills/skills/pixijs-accessibility/SKILL.md +224 -0
- package/vendor/pixijs-skills/skills/pixijs-application/SKILL.md +293 -0
- package/vendor/pixijs-skills/skills/pixijs-application/references/application-options.md +314 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/SKILL.md +303 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/background.md +137 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/bundles.md +122 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/caching.md +143 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/compressed-textures.md +120 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/fonts.md +205 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/gif.md +171 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/manifests.md +175 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/progress.md +142 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/resolution.md +142 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/spritesheet.md +119 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/svg.md +132 -0
- package/vendor/pixijs-skills/skills/pixijs-assets/references/video.md +158 -0
- package/vendor/pixijs-skills/skills/pixijs-blend-modes/SKILL.md +215 -0
- package/vendor/pixijs-skills/skills/pixijs-color/SKILL.md +299 -0
- package/vendor/pixijs-skills/skills/pixijs-core-concepts/SKILL.md +132 -0
- package/vendor/pixijs-skills/skills/pixijs-core-concepts/references/render-loop.md +216 -0
- package/vendor/pixijs-skills/skills/pixijs-core-concepts/references/renderers.md +287 -0
- package/vendor/pixijs-skills/skills/pixijs-create/SKILL.md +276 -0
- package/vendor/pixijs-skills/skills/pixijs-custom-rendering/SKILL.md +405 -0
- package/vendor/pixijs-skills/skills/pixijs-custom-rendering/references/advanced-gpu.md +244 -0
- package/vendor/pixijs-skills/skills/pixijs-custom-rendering/references/uniform-types.md +94 -0
- package/vendor/pixijs-skills/skills/pixijs-environments/SKILL.md +243 -0
- package/vendor/pixijs-skills/skills/pixijs-events/SKILL.md +387 -0
- package/vendor/pixijs-skills/skills/pixijs-filters/SKILL.md +300 -0
- package/vendor/pixijs-skills/skills/pixijs-html-source/SKILL.md +228 -0
- package/vendor/pixijs-skills/skills/pixijs-math/SKILL.md +489 -0
- package/vendor/pixijs-skills/skills/pixijs-migration-v8/SKILL.md +415 -0
- package/vendor/pixijs-skills/skills/pixijs-performance/SKILL.md +489 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-container/SKILL.md +345 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/SKILL.md +243 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/constructor-options.md +155 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/container-hierarchy.md +232 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/layers.md +145 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/masking.md +129 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/render-groups.md +140 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/scene-management.md +169 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/transforms.md +198 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-dom-container/SKILL.md +193 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-gif/SKILL.md +233 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-graphics/SKILL.md +576 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/SKILL.md +141 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-perspective.md +189 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-plane.md +159 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-rope.md +176 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-simple.md +144 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh.md +213 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-particle-container/SKILL.md +323 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-sprite/SKILL.md +120 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/animated-sprite.md +262 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/nineslice-sprite.md +202 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/sprite.md +181 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/tiling-sprite.md +216 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/SKILL.md +136 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/references/bitmap-text.md +232 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/references/html-text.md +192 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/references/split-bitmap-text.md +187 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/references/split-text.md +168 -0
- package/vendor/pixijs-skills/skills/pixijs-scene-text/references/text.md +311 -0
- package/vendor/pixijs-skills/skills/pixijs-ticker/SKILL.md +292 -0
|
@@ -0,0 +1,387 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pixijs-events
|
|
3
|
+
description: "Use this skill when handling pointer, mouse, touch, or wheel input in PixiJS v8. Covers eventMode (none, passive, auto, static, dynamic), FederatedEvent types, propagation and capture phase, hitArea, interactiveChildren, cursor and cursorStyles, global move events for drag, eventFeatures config. Triggers on: eventMode, FederatedPointerEvent, pointerdown, click, tap, globalpointermove, drag, hitArea, cursor, stopPropagation, persistentDeviceId, contextmenu, rightclick."
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
PixiJS's federated event system mirrors DOM events on the scene graph. Set `container.eventMode = 'static'` to opt an object in, then listen with `.on()`, `addEventListener()`, or `onEventName` property handlers. Move events fire only over the listening object; use `globalpointermove` for drag.
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
const button = new Sprite(await Assets.load("button.png"));
|
|
13
|
+
button.eventMode = "static";
|
|
14
|
+
button.cursor = "pointer";
|
|
15
|
+
app.stage.addChild(button);
|
|
16
|
+
|
|
17
|
+
button.on("pointertap", (event) => {
|
|
18
|
+
console.log("clicked at", event.global.x, event.global.y);
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
let dragging = false;
|
|
22
|
+
button.on("pointerdown", () => {
|
|
23
|
+
dragging = true;
|
|
24
|
+
});
|
|
25
|
+
button.on("pointerup", () => {
|
|
26
|
+
dragging = false;
|
|
27
|
+
});
|
|
28
|
+
button.on("pointerupoutside", () => {
|
|
29
|
+
dragging = false;
|
|
30
|
+
});
|
|
31
|
+
button.on("globalpointermove", (event) => {
|
|
32
|
+
if (dragging) button.parent.toLocal(event.global, undefined, button.position);
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Related skills:** `pixijs-accessibility` (screen reader + keyboard), `pixijs-scene-dom-container` (HTML overlays), `pixijs-performance` (event-heavy scenes).
|
|
37
|
+
|
|
38
|
+
## Core Patterns
|
|
39
|
+
|
|
40
|
+
### eventMode values
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { Sprite } from "pixi.js";
|
|
44
|
+
|
|
45
|
+
const sprite = new Sprite();
|
|
46
|
+
|
|
47
|
+
// No interaction at all; children also ignored
|
|
48
|
+
sprite.eventMode = "none";
|
|
49
|
+
|
|
50
|
+
// Default. Self not interactive; interactive children still work
|
|
51
|
+
sprite.eventMode = "passive";
|
|
52
|
+
|
|
53
|
+
// Hit tested only when a parent is interactive
|
|
54
|
+
sprite.eventMode = "auto";
|
|
55
|
+
|
|
56
|
+
// Standard interaction: receives pointer/mouse/touch events
|
|
57
|
+
sprite.eventMode = "static";
|
|
58
|
+
|
|
59
|
+
// Like static, but also fires synthetic events from the ticker
|
|
60
|
+
// when the pointer is stationary (for animated objects under cursor)
|
|
61
|
+
sprite.eventMode = "dynamic";
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Use `'static'` for buttons, UI elements, and drag targets. Use `'dynamic'` only for objects that move under a stationary cursor and need continuous hover updates.
|
|
65
|
+
|
|
66
|
+
Use `isInteractive()` to check whether an object can receive events:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
sprite.eventMode = "static";
|
|
70
|
+
sprite.isInteractive(); // true
|
|
71
|
+
|
|
72
|
+
sprite.eventMode = "passive";
|
|
73
|
+
sprite.isInteractive(); // false
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Event types
|
|
77
|
+
|
|
78
|
+
Pointer events (recommended for cross-device compatibility): `pointerdown`, `pointerup`, `pointerupoutside`, `pointermove`, `pointerover`, `pointerout`, `pointerenter`, `pointerleave`, `pointertap`, `pointercancel`.
|
|
79
|
+
|
|
80
|
+
Mouse events: `mousedown`, `mouseup`, `mouseupoutside`, `mousemove`, `mouseover`, `mouseout`, `mouseenter`, `mouseleave`, `click`, `rightdown`, `rightup`, `rightupoutside`, `rightclick`, `contextmenu`, `wheel`. PixiJS doesn't block the browser's context menu; call `event.preventDefault()` in a `contextmenu` listener to keep it closed. Canceling `rightdown`, `rightup`, or `rightclick` doesn't keep it closed. On macOS, ctrl + click also fires `contextmenu`, and the browser can report it as a left click.
|
|
81
|
+
|
|
82
|
+
Touch events: `touchstart`, `touchend`, `touchendoutside`, `touchmove`, `touchcancel`, `tap`. Each touch carries `altKey`, `ctrlKey`, `metaKey`, and `shiftKey` copied from the native `TouchEvent`, so modifier keys work the same as with mouse or pointer events.
|
|
83
|
+
|
|
84
|
+
Global move events: `globalpointermove`, `globalmousemove`, `globaltouchmove`. These fire on every pointer movement regardless of whether the pointer is over the listening object.
|
|
85
|
+
|
|
86
|
+
Container lifecycle events (no `eventMode` required): `added`, `removed`, `destroyed`, `childAdded`, `childRemoved`, `visibleChanged`.
|
|
87
|
+
|
|
88
|
+
### Listening styles
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import { Sprite } from "pixi.js";
|
|
92
|
+
|
|
93
|
+
const sprite = new Sprite();
|
|
94
|
+
sprite.eventMode = "static";
|
|
95
|
+
|
|
96
|
+
// EventEmitter style (recommended)
|
|
97
|
+
const handler = (e) => console.log("clicked");
|
|
98
|
+
sprite.on("pointerdown", handler);
|
|
99
|
+
sprite.once("pointerdown", handler); // one-time
|
|
100
|
+
sprite.off("pointerdown", handler);
|
|
101
|
+
|
|
102
|
+
// DOM style
|
|
103
|
+
sprite.addEventListener(
|
|
104
|
+
"click",
|
|
105
|
+
(event) => {
|
|
106
|
+
console.log("Clicked!", event.detail);
|
|
107
|
+
},
|
|
108
|
+
{ once: true },
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
// Property-based handlers
|
|
112
|
+
sprite.onclick = (event) => {
|
|
113
|
+
console.log("Clicked!", event.detail);
|
|
114
|
+
};
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Pointer events and propagation
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { Sprite, Container } from "pixi.js";
|
|
121
|
+
|
|
122
|
+
const parent = new Container();
|
|
123
|
+
parent.eventMode = "static";
|
|
124
|
+
|
|
125
|
+
const child = new Sprite();
|
|
126
|
+
child.eventMode = "static";
|
|
127
|
+
parent.addChild(child);
|
|
128
|
+
|
|
129
|
+
child.on("pointerdown", (event) => {
|
|
130
|
+
console.log("child pressed");
|
|
131
|
+
event.stopPropagation(); // prevent parent from receiving this event
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
parent.on("pointerdown", () => {
|
|
135
|
+
console.log("parent pressed (only if child did not stop propagation)");
|
|
136
|
+
});
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Capture phase events
|
|
140
|
+
|
|
141
|
+
All events support capture phase by appending `capture` to the event name (e.g., `pointerdowncapture`, `clickcapture`). Capture listeners fire during the capturing phase, before the event reaches its target.
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
container.addEventListener(
|
|
145
|
+
"pointerdown",
|
|
146
|
+
(event) => {
|
|
147
|
+
event.stopImmediatePropagation(); // blocks event from reaching children
|
|
148
|
+
},
|
|
149
|
+
{ capture: true },
|
|
150
|
+
);
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Hit testing
|
|
154
|
+
|
|
155
|
+
When a pointer event fires, PixiJS walks the display tree to find the top-most interactive element under the pointer. The traversal follows these rules:
|
|
156
|
+
|
|
157
|
+
- `eventMode = 'none'` on a container skips that element and its entire subtree.
|
|
158
|
+
- `interactiveChildren = false` on a container skips its children (the container itself can still be tested).
|
|
159
|
+
- A `hitArea` overrides bounds-based testing; only the shape is checked.
|
|
160
|
+
- Objects that are not visible, not renderable, or not measurable are skipped.
|
|
161
|
+
|
|
162
|
+
Set a custom `hitArea` to override bounds-based testing. This also speeds up hit tests on large or complex objects by reducing the geometry checked:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
import { Sprite, Rectangle, Circle, Polygon } from "pixi.js";
|
|
166
|
+
|
|
167
|
+
const sprite = new Sprite();
|
|
168
|
+
sprite.eventMode = "static";
|
|
169
|
+
|
|
170
|
+
// Rectangular hit area
|
|
171
|
+
sprite.hitArea = new Rectangle(0, 0, 100, 50);
|
|
172
|
+
|
|
173
|
+
// Circular hit area
|
|
174
|
+
sprite.hitArea = new Circle(50, 50, 40);
|
|
175
|
+
|
|
176
|
+
// Polygon hit area
|
|
177
|
+
sprite.hitArea = new Polygon([0, 0, 100, 0, 50, 100]);
|
|
178
|
+
|
|
179
|
+
// Custom hit test via contains()
|
|
180
|
+
sprite.hitArea = {
|
|
181
|
+
contains(x: number, y: number): boolean {
|
|
182
|
+
return x >= 0 && x <= 100 && y >= 0 && y <= 100;
|
|
183
|
+
},
|
|
184
|
+
};
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Global move events and drag
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
import { Sprite, FederatedPointerEvent } from "pixi.js";
|
|
191
|
+
|
|
192
|
+
const sprite = new Sprite();
|
|
193
|
+
sprite.eventMode = "static";
|
|
194
|
+
sprite.cursor = "grab";
|
|
195
|
+
|
|
196
|
+
let dragging = false;
|
|
197
|
+
|
|
198
|
+
sprite.on("pointerdown", (event: FederatedPointerEvent) => {
|
|
199
|
+
dragging = true;
|
|
200
|
+
sprite.cursor = "grabbing";
|
|
201
|
+
});
|
|
202
|
+
|
|
203
|
+
// globalpointermove fires even when pointer leaves the object
|
|
204
|
+
sprite.on("globalpointermove", (event: FederatedPointerEvent) => {
|
|
205
|
+
if (dragging) {
|
|
206
|
+
sprite.position.set(event.global.x, event.global.y);
|
|
207
|
+
}
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
sprite.on("pointerup", () => {
|
|
211
|
+
dragging = false;
|
|
212
|
+
sprite.cursor = "grab";
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
sprite.on("pointerupoutside", () => {
|
|
216
|
+
dragging = false;
|
|
217
|
+
sprite.cursor = "grab";
|
|
218
|
+
});
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Cursor styles
|
|
222
|
+
|
|
223
|
+
Basic usage sets the `cursor` property per-object. For reusable cursors, register named styles on the event system:
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
app.renderer.events.cursorStyles.default = "url('bunny.png'), auto";
|
|
227
|
+
app.renderer.events.cursorStyles.hover = "url('bunny_saturated.png'), auto";
|
|
228
|
+
|
|
229
|
+
sprite.eventMode = "static";
|
|
230
|
+
sprite.cursor = "hover"; // uses the registered 'hover' style
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Cursor styles can be strings (CSS cursor values), objects (applied as CSS styles), or functions (called with the mode string).
|
|
234
|
+
|
|
235
|
+
### Event properties
|
|
236
|
+
|
|
237
|
+
`FederatedPointerEvent` carries rich input data; the more useful fields are:
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
sprite.on("pointerdown", (event: FederatedPointerEvent) => {
|
|
241
|
+
event.global; // scene-space Point where the event happened
|
|
242
|
+
event.client; // CSS-pixel Point relative to the viewport
|
|
243
|
+
event.offset; // Point w.r.t. target Container in world space (not supported at the moment)
|
|
244
|
+
event.target; // the Container that received the event
|
|
245
|
+
event.currentTarget; // the Container whose listener is running
|
|
246
|
+
|
|
247
|
+
event.pointerType; // 'mouse' | 'pen' | 'touch'
|
|
248
|
+
event.pointerId; // unique id for multi-touch tracking
|
|
249
|
+
event.isPrimary; // first pointer in a multi-pointer gesture
|
|
250
|
+
event.persistentDeviceId; // always 0; present for DOM PointerEvent type compatibility
|
|
251
|
+
event.pressure; // 0-1 pen/touch pressure
|
|
252
|
+
event.button; // 0 left, 1 middle, 2 right
|
|
253
|
+
event.buttons; // bitmask of held buttons
|
|
254
|
+
event.altKey; // modifier key state
|
|
255
|
+
event.ctrlKey;
|
|
256
|
+
event.shiftKey;
|
|
257
|
+
event.metaKey;
|
|
258
|
+
|
|
259
|
+
event.nativeEvent; // the underlying DOM PointerEvent / MouseEvent / Touch
|
|
260
|
+
event.preventDefault();
|
|
261
|
+
event.stopPropagation();
|
|
262
|
+
event.stopImmediatePropagation();
|
|
263
|
+
});
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
`FederatedWheelEvent` adds `deltaX`, `deltaY`, `deltaZ`, and `deltaMode`. Wheel events fire on the same hit-tested object as pointer events.
|
|
267
|
+
|
|
268
|
+
### Event features
|
|
269
|
+
|
|
270
|
+
Toggle event categories globally for performance:
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
await app.init({
|
|
274
|
+
eventFeatures: {
|
|
275
|
+
move: true, // pointer/mouse/touch move events
|
|
276
|
+
globalMove: true, // global move events (globalpointermove, etc.)
|
|
277
|
+
click: true, // click/tap/press and contextmenu events
|
|
278
|
+
wheel: true, // mouse wheel events
|
|
279
|
+
},
|
|
280
|
+
});
|
|
281
|
+
|
|
282
|
+
// or configure after init
|
|
283
|
+
app.renderer.events.features.globalMove = false;
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### Performance tips
|
|
287
|
+
|
|
288
|
+
- Set `eventMode = 'none'` on non-interactive subtrees to skip hit testing entirely.
|
|
289
|
+
- Set `interactiveChildren = false` on containers where only the container itself needs interaction.
|
|
290
|
+
- Use `hitArea` on large or complex objects to replace bounds-based hit testing with a cheap shape check.
|
|
291
|
+
- Prefer `'static'` for stationary elements; reserve `'dynamic'` for objects that move or animate under a stationary pointer.
|
|
292
|
+
- Disable unused event features via `eventFeatures` (e.g., `globalMove: false`) to cut per-frame work.
|
|
293
|
+
|
|
294
|
+
## Common Mistakes
|
|
295
|
+
|
|
296
|
+
### [HIGH] Default eventMode is passive
|
|
297
|
+
|
|
298
|
+
Wrong:
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
const sprite = new Sprite(texture);
|
|
302
|
+
sprite.on("pointerdown", () => {
|
|
303
|
+
console.log("clicked");
|
|
304
|
+
});
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Correct:
|
|
308
|
+
|
|
309
|
+
```ts
|
|
310
|
+
const sprite = new Sprite(texture);
|
|
311
|
+
sprite.eventMode = "static";
|
|
312
|
+
sprite.on("pointerdown", () => {
|
|
313
|
+
console.log("clicked");
|
|
314
|
+
});
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The default `eventMode` is `'passive'`, which means the object itself receives no events. You must explicitly set `eventMode` to `'static'` or `'dynamic'` before any listener will fire.
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
### [HIGH] buttonMode removed; use cursor
|
|
321
|
+
|
|
322
|
+
Wrong:
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
sprite.interactive = true;
|
|
326
|
+
sprite.buttonMode = true;
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Correct:
|
|
330
|
+
|
|
331
|
+
```ts
|
|
332
|
+
sprite.eventMode = "static";
|
|
333
|
+
sprite.cursor = "pointer";
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
`buttonMode` was removed in v8. Use `cursor = 'pointer'` to show a hand cursor on hover. `interactive = true` still works as an alias for `eventMode = 'static'`, but `eventMode` is preferred.
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
### [HIGH] Move events only fire over the object in v8
|
|
340
|
+
|
|
341
|
+
Wrong:
|
|
342
|
+
|
|
343
|
+
```ts
|
|
344
|
+
sprite.eventMode = "static";
|
|
345
|
+
sprite.on("pointermove", (event) => {
|
|
346
|
+
// expects to fire everywhere; only fires inside sprite bounds
|
|
347
|
+
updateDrag(event.global.x, event.global.y);
|
|
348
|
+
});
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Correct:
|
|
352
|
+
|
|
353
|
+
```ts
|
|
354
|
+
sprite.eventMode = "static";
|
|
355
|
+
sprite.on("globalpointermove", (event) => {
|
|
356
|
+
// fires everywhere, even outside sprite bounds
|
|
357
|
+
updateDrag(event.global.x, event.global.y);
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
In v8, `pointermove`, `mousemove`, and `touchmove` only fire when the pointer is over the display object. In v7 they fired on any canvas move. For drag operations or global tracking, use `globalpointermove`, `globalmousemove`, or `globaltouchmove`.
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
### [MEDIUM] Cursor does not inherit from parent
|
|
365
|
+
|
|
366
|
+
Setting `cursor` on a parent container has no effect on its children. Only the direct hit target's `cursor` value is applied.
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
// This does NOT make children show a pointer cursor
|
|
370
|
+
parent.cursor = "pointer";
|
|
371
|
+
|
|
372
|
+
// Each interactive child needs its own cursor
|
|
373
|
+
child.eventMode = "static";
|
|
374
|
+
child.cursor = "pointer";
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
If you want a uniform cursor for all children, set `cursor` on each interactive child individually, or set `hitArea` on the parent and make children non-interactive.
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
## API Reference
|
|
381
|
+
|
|
382
|
+
- [EventSystem](https://pixijs.download/release/docs/events.EventSystem.html.md)
|
|
383
|
+
- [FederatedEvent](https://pixijs.download/release/docs/events.FederatedEvent.html.md)
|
|
384
|
+
- [FederatedPointerEvent](https://pixijs.download/release/docs/events.FederatedPointerEvent.html.md)
|
|
385
|
+
- [FederatedMouseEvent](https://pixijs.download/release/docs/events.FederatedMouseEvent.html.md)
|
|
386
|
+
- [FederatedWheelEvent](https://pixijs.download/release/docs/events.FederatedWheelEvent.html.md)
|
|
387
|
+
- [EventBoundary](https://pixijs.download/release/docs/events.EventBoundary.html.md)
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pixijs-filters
|
|
3
|
+
description: "Use this skill when applying visual effects to PixiJS v8 containers via the filter pipeline. Covers built-in filters (AlphaFilter, BlurFilter, ColorMatrixFilter, DisplacementFilter, NoiseFilter), custom Filter.from() with GLSL/WGSL, options (resolution, padding, antialias, blendRequired), filterArea optimization, pixi-filters community package. Triggers on: filters, BlurFilter, ColorMatrixFilter, DisplacementFilter, NoiseFilter, Filter.from, GLSL filter, pixi-filters, filterArea."
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Attach visual effects by assigning one filter (or an array for chaining) to `container.filters`. Built-in filters cover blur, color matrix, displacement, alpha, and noise; custom filters wrap a GLSL/WGSL fragment shader via `Filter.from(...)`.
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
const sprite = new Sprite(await Assets.load("hero.png"));
|
|
13
|
+
app.stage.addChild(sprite);
|
|
14
|
+
|
|
15
|
+
const blur = new BlurFilter({ strength: 4, quality: 4 });
|
|
16
|
+
const colorMatrix = new ColorMatrixFilter();
|
|
17
|
+
colorMatrix.brightness(1.2, false);
|
|
18
|
+
|
|
19
|
+
sprite.filters = [blur, colorMatrix];
|
|
20
|
+
|
|
21
|
+
const container = new Container();
|
|
22
|
+
container.filters = [new BlurFilter({ strength: 2 })];
|
|
23
|
+
container.filterArea = new Rectangle(0, 0, 800, 600);
|
|
24
|
+
app.stage.addChild(container);
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Related skills:** `pixijs-custom-rendering` (shader internals, uniform types), `pixijs-blend-modes` (composing with filters), `pixijs-performance` (filter tuning, filterArea).
|
|
28
|
+
|
|
29
|
+
## Core Patterns
|
|
30
|
+
|
|
31
|
+
### Built-in filters
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import {
|
|
35
|
+
AlphaFilter,
|
|
36
|
+
BlurFilter,
|
|
37
|
+
ColorMatrixFilter,
|
|
38
|
+
DisplacementFilter,
|
|
39
|
+
NoiseFilter,
|
|
40
|
+
Assets,
|
|
41
|
+
Sprite,
|
|
42
|
+
} from "pixi.js";
|
|
43
|
+
|
|
44
|
+
// Alpha (uniform transparency without per-child layering)
|
|
45
|
+
const alpha = new AlphaFilter({ alpha: 0.5 });
|
|
46
|
+
|
|
47
|
+
// Blur — strength/quality are uniform; strengthX/strengthY split axes;
|
|
48
|
+
// kernelSize must be odd (5, 7, 9, ... 15); repeatEdgePixels avoids transparent edges
|
|
49
|
+
const blur = new BlurFilter({
|
|
50
|
+
strength: 4,
|
|
51
|
+
quality: 4,
|
|
52
|
+
kernelSize: 5,
|
|
53
|
+
repeatEdgePixels: false,
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
// Color matrix — brightness is one of many presets. Others: tint, hue,
|
|
57
|
+
// contrast, saturate, desaturate, greyscale/grayscale, blackAndWhite,
|
|
58
|
+
// negative, sepia, technicolor, polaroid, kodachrome, browni, vintage,
|
|
59
|
+
// colorTone, night, predator, lsd, reset. Direct access via
|
|
60
|
+
// `colorMatrix.matrix` (20-element array) and `colorMatrix.alpha` (blend
|
|
61
|
+
// between original and transformed).
|
|
62
|
+
const colorMatrix = new ColorMatrixFilter();
|
|
63
|
+
colorMatrix.brightness(1.5, false);
|
|
64
|
+
colorMatrix.contrast(0.5, true); // multiply stacks on top of existing matrix
|
|
65
|
+
colorMatrix.alpha = 0.7; // blend at 70% strength
|
|
66
|
+
|
|
67
|
+
// Displacement — scale is a number or PointData
|
|
68
|
+
const displacementTexture = await Assets.load("displacement_map.png");
|
|
69
|
+
const displacementSprite = new Sprite(displacementTexture);
|
|
70
|
+
const displacement = new DisplacementFilter({
|
|
71
|
+
sprite: displacementSprite,
|
|
72
|
+
scale: { x: 20, y: 10 },
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
// Noise — seed is an arbitrary number that determines the noise pattern; same seed reproduces the same pattern
|
|
76
|
+
const noise = new NoiseFilter({ noise: 0.5, seed: Math.random() });
|
|
77
|
+
|
|
78
|
+
sprite.filters = [blur, colorMatrix];
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Custom filter with Filter.from()
|
|
82
|
+
|
|
83
|
+
The simplest way to create a custom filter. Only a fragment shader is needed; PixiJS provides a default vertex shader.
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import { Filter } from "pixi.js";
|
|
87
|
+
|
|
88
|
+
const filter = Filter.from({
|
|
89
|
+
gl: {
|
|
90
|
+
fragment: `
|
|
91
|
+
in vec2 vTextureCoord;
|
|
92
|
+
out vec4 finalColor;
|
|
93
|
+
uniform sampler2D uTexture;
|
|
94
|
+
uniform float uTime;
|
|
95
|
+
|
|
96
|
+
void main() {
|
|
97
|
+
vec2 uv = vTextureCoord;
|
|
98
|
+
uv.x += sin(uv.y * 10.0 + uTime) * 0.02;
|
|
99
|
+
finalColor = texture(uTexture, uv);
|
|
100
|
+
}
|
|
101
|
+
`,
|
|
102
|
+
},
|
|
103
|
+
resources: {
|
|
104
|
+
timeUniforms: {
|
|
105
|
+
uTime: { value: 0, type: "f32" },
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
sprite.filters = filter;
|
|
111
|
+
|
|
112
|
+
app.ticker.add((ticker) => {
|
|
113
|
+
filter.resources.timeUniforms.uniforms.uTime += 0.04 * ticker.deltaTime;
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
For more control, construct `GlProgram`/`GpuProgram` objects directly:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import { Filter, GlProgram } from "pixi.js";
|
|
121
|
+
|
|
122
|
+
const glProgram = GlProgram.from({ fragment: fragmentSrc, vertex: vertexSrc });
|
|
123
|
+
|
|
124
|
+
const filter = new Filter({
|
|
125
|
+
glProgram,
|
|
126
|
+
resources: {
|
|
127
|
+
timeUniforms: {
|
|
128
|
+
uTime: { value: 0, type: "f32" },
|
|
129
|
+
},
|
|
130
|
+
},
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Key points:
|
|
135
|
+
|
|
136
|
+
- Use `out vec4 finalColor` in fragment shaders, not `gl_FragColor` (GLSL ES 3.0).
|
|
137
|
+
- Use `texture()` to sample, not `texture2D`.
|
|
138
|
+
- `glProgram` for WebGL, `gpuProgram` for WebGPU. Omitting one skips that renderer.
|
|
139
|
+
- Textures go in `resources`, not uniforms. The filter system auto-provides `uTexture` (the input).
|
|
140
|
+
- Access uniform values via `filter.resources.{groupName}.uniforms.{name}`.
|
|
141
|
+
|
|
142
|
+
### Filter options
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { Filter, GlProgram, Rectangle } from "pixi.js";
|
|
146
|
+
|
|
147
|
+
const filter = new Filter({
|
|
148
|
+
glProgram: GlProgram.from({ fragment }),
|
|
149
|
+
resources: {},
|
|
150
|
+
resolution: 0.5, // default 1. Lower = faster, blurrier. 'inherit' matches the render target resolution
|
|
151
|
+
padding: 10, // default 0. Extra pixels for effects that extend bounds
|
|
152
|
+
antialias: "off", // default 'off'. 'on' | 'off' | 'inherit'
|
|
153
|
+
blendMode: "normal", // default 'normal'
|
|
154
|
+
blendRequired: false, // default false. true if shader samples uBackTexture
|
|
155
|
+
clipToViewport: true, // default true
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
// Optimization: set known bounds to avoid per-frame measurement
|
|
159
|
+
container.filterArea = new Rectangle(0, 0, 800, 600);
|
|
160
|
+
|
|
161
|
+
// Toggle without rebuilding the filter array
|
|
162
|
+
filter.enabled = false;
|
|
163
|
+
|
|
164
|
+
// Share one filter instance across many display objects
|
|
165
|
+
sprite1.filters = [filter];
|
|
166
|
+
sprite2.filters = [filter];
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Community filters (pixi-filters)
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
import { AdjustmentFilter } from "pixi-filters/adjustment";
|
|
173
|
+
import { GlowFilter } from "pixi-filters/glow";
|
|
174
|
+
|
|
175
|
+
sprite.filters = [
|
|
176
|
+
new AdjustmentFilter({ brightness: 1.2, contrast: 1.1 }),
|
|
177
|
+
new GlowFilter({ distance: 15, outerStrength: 2 }),
|
|
178
|
+
];
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
For v8, community filters use `pixi-filters/{name}` imports, not the old `@pixi/filter-*` packages.
|
|
182
|
+
|
|
183
|
+
### Advanced blend modes
|
|
184
|
+
|
|
185
|
+
Advanced blend modes (`color-burn`, `overlay`, `hard-light`, etc.) are powered by the filter system and must be imported before use. They also require `useBackBuffer: true` on WebGL; see the `pixijs-blend-modes` skill for the full list.
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
import "pixi.js/advanced-blend-modes";
|
|
189
|
+
|
|
190
|
+
await app.init({ useBackBuffer: true });
|
|
191
|
+
sprite.blendMode = "color-burn";
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Advanced blend modes are filter-based, so they inherit `Filter.defaultOptions`, whose `resolution` defaults to `1`. On high-DPI render targets this can make a blend mode look clipped, scaled, or only partially applied. Set `Filter.defaultOptions.resolution = 'inherit'` before creating the affected objects to render at the render target resolution, at higher memory and runtime cost:
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
import { Filter } from "pixi.js";
|
|
198
|
+
import "pixi.js/advanced-blend-modes";
|
|
199
|
+
|
|
200
|
+
Filter.defaultOptions.resolution = "inherit";
|
|
201
|
+
sprite.blendMode = "overlay";
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Common Mistakes
|
|
205
|
+
|
|
206
|
+
### [CRITICAL] Using old Filter constructor (vertex, fragment, uniforms)
|
|
207
|
+
|
|
208
|
+
Wrong:
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
import { Filter } from "pixi.js";
|
|
212
|
+
|
|
213
|
+
const filter = new Filter(vertex, fragment, { uTime: 0 });
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Correct:
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
import { Filter, GlProgram } from "pixi.js";
|
|
220
|
+
|
|
221
|
+
const filter = new Filter({
|
|
222
|
+
glProgram: GlProgram.from({ fragment, vertex }),
|
|
223
|
+
resources: {
|
|
224
|
+
timeUniforms: { uTime: { value: 0, type: "f32" } },
|
|
225
|
+
},
|
|
226
|
+
});
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
v8 uses an options object. Shaders must be wrapped in `GlProgram.from()` or `GpuProgram.from()`. Uniforms are grouped in `resources` with explicit types. Textures are resources, not uniforms.
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
### [HIGH] Using @pixi/filter-\* packages for v8
|
|
233
|
+
|
|
234
|
+
Wrong:
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
import { AdjustmentFilter } from "@pixi/filter-adjustment";
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Correct:
|
|
241
|
+
|
|
242
|
+
```ts
|
|
243
|
+
import { AdjustmentFilter } from "pixi-filters/adjustment";
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`@pixi/filter-*` packages are v7 only. For v8, the community filters package restructured to `pixi-filters/{name}`.
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
### [HIGH] Using too many filters without containerizing
|
|
250
|
+
|
|
251
|
+
Each filter application requires a framebuffer switch, bounds measurement, and render-to-texture pass. One filter on a parent container is much cheaper than the same filter on each child.
|
|
252
|
+
|
|
253
|
+
Wrong:
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
for (const child of container.children) {
|
|
257
|
+
child.filters = [new BlurFilter({ strength: 4 })];
|
|
258
|
+
}
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Correct:
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
container.filters = [new BlurFilter({ strength: 4 })];
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
### [HIGH] Using a blendRequired filter without useBackBuffer on WebGL
|
|
269
|
+
|
|
270
|
+
Custom filters and most advanced community filters that set `blendRequired: true` sample the back buffer. On WebGL that only works if the renderer was initialized with `useBackBuffer: true`; otherwise PixiJS logs a warning and the filter silently falls back:
|
|
271
|
+
|
|
272
|
+
```ts
|
|
273
|
+
await app.init({ useBackBuffer: true });
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
WebGPU enables the back buffer unconditionally, so this only affects WebGL.
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
### [MEDIUM] Not setting filterArea for known-size containers
|
|
280
|
+
|
|
281
|
+
Without `filterArea`, PixiJS measures the container bounds every frame via `getGlobalBounds()`, which recursively walks all children. For containers with known dimensions, set `filterArea` to avoid this cost:
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
import { Rectangle } from "pixi.js";
|
|
285
|
+
|
|
286
|
+
container.filterArea = new Rectangle(0, 0, 800, 600);
|
|
287
|
+
container.filters = [someFilter];
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
## API Reference
|
|
292
|
+
|
|
293
|
+
- [Filter](https://pixijs.download/release/docs/filters.Filter.html.md)
|
|
294
|
+
- [AlphaFilter](https://pixijs.download/release/docs/filters.AlphaFilter.html.md)
|
|
295
|
+
- [BlurFilter](https://pixijs.download/release/docs/filters.BlurFilter.html.md)
|
|
296
|
+
- [BlurFilterPass](https://pixijs.download/release/docs/filters.BlurFilterPass.html.md)
|
|
297
|
+
- [ColorMatrixFilter](https://pixijs.download/release/docs/filters.ColorMatrixFilter.html.md)
|
|
298
|
+
- [DisplacementFilter](https://pixijs.download/release/docs/filters.DisplacementFilter.html.md)
|
|
299
|
+
- [NoiseFilter](https://pixijs.download/release/docs/filters.NoiseFilter.html.md)
|
|
300
|
+
- [FilterSystem](https://pixijs.download/release/docs/rendering.FilterSystem.html.md)
|