0
# Filters and Effects
1

2
Visual effects system including built-in filters (blur, color matrix, displacement) and custom filter creation with shader support. Filters provide post-processing effects that can be applied to display objects for enhanced visual presentation.
3

4
## Capabilities
5

6
### Filter Base Class  
7

8
Core filter class for creating visual effects.
9

10
```typescript { .api }
11
/**
12
 * Base filter class for visual effects
13
 */
14
class Filter {
15
  constructor(options?: FilterOptions);
16
  
17
  /** Fragment shader source */
18
  glProgram: GlProgram;
19
  
20
  /** GPU program */
21
  gpuProgram: GpuProgram;
22
  
23
  /** Uniform groups */
24
  groups: Record<string, UniformGroup>;
25
  
26
  /** Shader resources */
27
  resources: Record<string, any>;
28
  
29
  /** Filter blend mode */
30
  blendMode: BLEND_MODES;
31
  
32
  /** Filter enabled state */
33
  enabled: boolean;
34
  
35
  /** Filter padding */
36
  padding: number;
37
  
38
  /** Filter antialias */
39
  antialias: 'inherit' | 'on' | 'off';
40
  
41
  /** Filter resolution */
42
  resolution: number;
43
  
44
  /** Multisample level */
45
  multisample: MSAA_QUALITY;
46
  
47
  /**
48
   * Apply filter
49
   * @param filterManager - Filter system
50
   * @param input - Input render target
51
   * @param output - Output render target
52
   * @param clearMode - Clear mode
53
   */
54
  apply(filterManager: FilterSystem, input: RenderTarget, output: RenderTarget, clearMode?: CLEAR_MODES): void;
55
  
56
  /**
57
   * Destroy filter and clean up resources
58
   */
59
  destroy(): void;
60
}
61

62
interface FilterOptions {
63
  /** WebGL program */
64
  glProgram?: GlProgram;
65
  
66
  /** WebGPU program */
67
  gpuProgram?: GpuProgram;
68
  
69
  /** Uniform groups */
70
  groups?: Record<string, UniformGroup>;
71
  
72
  /** Shader resources */
73
  resources?: Record<string, any>;
74
  
75
  /** Padding */
76
  padding?: number;
77
  
78
  /** Antialias */
79
  antialias?: 'inherit' | 'on' | 'off';
80
  
81
  /** Resolution */
82
  resolution?: number;
83
  
84
  /** Multisample */
85
  multisample?: MSAA_QUALITY;
86
}
87
```
88

89
### Built-in Filters
90

91
Collection of commonly used visual effects filters.
92

93
```typescript { .api }
94
/**
95
 * Blur filter for gaussian blur effects
96
 */
97
class BlurFilter extends Filter {
98
  constructor(options?: BlurFilterOptions);
99
  
100
  /** Blur strength */
101
  blur: number;
102
  
103
  /** Blur quality (number of passes) */
104
  quality: number;
105
  
106
  /** Horizontal blur amount */
107
  blurX: number;
108
  
109
  /** Vertical blur amount */
110
  blurY: number;
111
  
112
  /** Kernel size */
113
  kernelSize: number;
114
  
115
  /**
116
   * Apply blur in single direction
117
   * @param filterManager - Filter system
118
   * @param input - Input render target
119
   * @param output - Output render target
120
   * @param clearMode - Clear mode
121
   * @param horizontal - Horizontal direction
122
   */
123
  applyFilter(filterManager: FilterSystem, input: RenderTarget, output: RenderTarget, clearMode?: CLEAR_MODES, horizontal?: boolean): void;
124
}
125

126
interface BlurFilterOptions {
127
  /** Blur strength */
128
  strength?: number;
129
  
130
  /** Blur quality */
131
  quality?: number;
132
  
133
  /** Texture resolution */
134
  resolution?: number;
135
  
136
  /** Kernel size */
137
  kernelSize?: number;
138
}
139

140
/**
141
 * Color matrix filter for color transformations
142
 */
143
class ColorMatrixFilter extends Filter {
144
  constructor(matrix?: number[]);
145
  
146
  /** 5x4 color transformation matrix */
147
  matrix: number[];
148
  
149
  /** Filter alpha */
150
  alpha: number;
151
  
152
  /**
153
   * Reset matrix to identity
154
   */
155
  reset(): void;
156
  
157
  /**
158
   * Set matrix values
159
   * @param matrix - 5x4 matrix array
160
   */
161
  setMatrix(matrix: number[]): void;
162
  
163
  /**
164
   * Adjust brightness
165
   * @param b - Brightness adjustment (-1 to 1)
166
   * @param multiply - Multiply existing values
167
   */
168
  brightness(b: number, multiply?: boolean): void;
169
  
170
  /**
171
   * Adjust contrast
172
   * @param amount - Contrast adjustment (0 to 2)
173
   * @param multiply - Multiply existing values
174
   */
175
  contrast(amount: number, multiply?: boolean): void;
176
  
177
  /**
178
   * Adjust saturation
179
   * @param amount - Saturation adjustment (0 to 2)
180
   * @param multiply - Multiply existing values
181
   */
182
  saturate(amount: number, multiply?: boolean): void;
183
  
184
  /**
185
   * Desaturate (grayscale)
186
   * @param multiply - Multiply existing values
187
   */
188
  desaturate(multiply?: boolean): void;
189
  
190
  /**
191
   * Adjust hue
192
   * @param rotation - Hue rotation in degrees
193
   * @param multiply - Multiply existing values
194
   */
195
  hue(rotation: number, multiply?: boolean): void;
196
  
197
  /**
198
   * Apply color tint
199
   * @param color - Tint color
200
   * @param multiply - Multiply existing values
201
   */
202
  tint(color: ColorSource, multiply?: boolean): void;
203
  
204
  /**
205
   * Convert to sepia tone
206
   * @param multiply - Multiply existing values
207
   */
208
  sepia(multiply?: boolean): void;
209
  
210
  /**
211
   * Invert colors
212
   * @param multiply - Multiply existing values
213
   */
214
  negative(multiply?: boolean): void;
215
}
216

217
/**
218
 * Alpha filter for transparency effects
219
 */
220
class AlphaFilter extends Filter {
221
  constructor(alpha?: number);
222
  
223
  /** Alpha multiplier (0-1) */
224
  alpha: number;
225
}
226

227
/**
228
 * Displacement filter for distortion effects
229
 */
230
class DisplacementFilter extends Filter {
231
  constructor(sprite?: Sprite, scale?: number);
232
  
233
  /** Displacement map sprite */
234
  sprite: Sprite;
235
  
236
  /** Displacement scale */
237
  scale: Point;
238
  
239
  /** Displacement map texture */
240
  maskSprite: Sprite;
241
  
242
  /** Mask matrix */
243
  maskMatrix: Matrix;
244
}
245

246
/**
247
 * Noise filter for noise/grain effects
248
 */
249
class NoiseFilter extends Filter {
250
  constructor(noise?: number, seed?: number);
251
  
252
  /** Noise amount (0-1) */
253
  noise: number;
254
  
255
  /** Random seed */
256
  seed: number;
257
}
258
```
259

260
### Filter Effects
261

262
Filter effect wrapper for managing filter application.
263

264
```typescript { .api }
265
/**
266
 * Filter effect wrapper
267
 */
268
class FilterEffect {
269
  constructor(options?: FilterEffectOptions);
270
  
271
  /** Associated filters */
272
  filters: Filter[];
273
  
274
  /** Effect enabled state */
275
  enabled: boolean;
276
  
277
  /** Effect priority */
278
  priority: number;
279
  
280
  /**
281
   * Add filter to effect
282
   * @param filter - Filter to add
283
   */
284
  addFilter(filter: Filter): void;
285
  
286
  /**
287
   * Remove filter from effect
288
   * @param filter - Filter to remove
289
   */
290
  removeFilter(filter: Filter): void;
291
  
292
  /**
293
   * Destroy effect and filters
294
   */
295
  destroy(): void;
296
}
297

298
interface FilterEffectOptions {
299
  /** Initial filters */
300
  filters?: Filter[];
301
  
302
  /** Enabled state */
303
  enabled?: boolean;
304
  
305
  /** Effect priority */
306
  priority?: number;
307
}
308
```
309

310
### Filter System
311

312
System for managing and applying filters.
313

314
```typescript { .api }
315
/**
316
 * Filter management system
317
 */
318
class FilterSystem {
319
  constructor(renderer: Renderer);
320
  
321
  /** Associated renderer */
322
  renderer: Renderer;
323
  
324
  /** Default filter vertex shader */
325
  defaultFilterVertex: string;
326
  
327
  /** Filter stack */
328
  filterStack: FilterStackEntry[];
329
  
330
  /** Current filter data */
331
  currentFilterData: FilterData;
332
  
333
  /**
334
   * Push filter onto stack
335
   * @param filterStackEntry - Filter stack entry
336
   */
337
  push(filterStackEntry: FilterStackEntry): void;
338
  
339
  /**
340
   * Pop filter from stack
341
   */
342
  pop(): void;
343
  
344
  /**
345
   * Apply filters to render target
346
   * @param filters - Filters to apply
347
   * @param input - Input render target
348
   * @param output - Output render target
349
   * @param clearMode - Clear mode
350
   */
351
  applyFilter(filters: Filter[], input: RenderTarget, output: RenderTarget, clearMode?: CLEAR_MODES): void;
352
  
353
  /**
354
   * Calculate filter area
355
   * @param filters - Filters
356
   * @param inputBounds - Input bounds
357
   * @param outputBounds - Output bounds
358
   */
359
  calculateFilterArea(filters: Filter[], inputBounds: Rectangle, outputBounds: Rectangle): void;
360
  
361
  /**
362
   * Get optimal filter texture
363
   * @param resolution - Texture resolution
364
   * @param multisample - Multisample level
365
   * @returns Render texture
366
   */
367
  getOptimalFilterTexture(resolution: number, multisample?: MSAA_QUALITY): RenderTexture;
368
  
369
  /**
370
   * Return filter texture to pool
371
   * @param renderTexture - Texture to return
372
   */
373
  returnFilterTexture(renderTexture: RenderTexture): void;
374
  
375
  /**
376
   * Destroy filter system
377
   */
378
  destroy(): void;
379
}
380
```
381

382
### Custom Filter Creation
383

384
Utilities for creating custom filters with shaders.
385

386
```typescript { .api }
387
/**
388
 * Create custom filter from shader sources
389
 * @param vertexSrc - Vertex shader source
390
 * @param fragmentSrc - Fragment shader source
391
 * @param uniforms - Uniform values
392
 * @returns Custom filter
393
 */
394
function createFilter(vertexSrc?: string, fragmentSrc?: string, uniforms?: Record<string, any>): Filter;
395

396
/**
397
 * Filter shader template
398
 */
399
const DEFAULT_VERTEX_SHADER = `
400
  attribute vec2 aVertexPosition;
401
  attribute vec2 aTextureCoord;
402
  
403
  uniform mat3 projectionMatrix;
404
  
405
  varying vec2 vTextureCoord;
406
  
407
  void main(void) {
408
    gl_Position = vec4((projectionMatrix * vec3(aVertexPosition, 1.0)).xy, 0.0, 1.0);
409
    vTextureCoord = aTextureCoord;
410
  }
411
`;
412

413
const DEFAULT_FRAGMENT_SHADER = `
414
  varying vec2 vTextureCoord;
415
  
416
  uniform sampler2D uSampler;
417
  
418
  void main(void) {
419
    gl_FragColor = texture2D(uSampler, vTextureCoord);
420
  }
421
`;
422
```
423

424
### Blend Mode Filter
425

426
Filter for custom blend modes and color blending.
427

428
```typescript { .api }
429
/**
430
 * Blend mode filter for advanced blending
431
 */
432
class BlendModeFilter extends Filter {
433
  constructor(blendMode: BLEND_MODES);
434
  
435
  /** Blend mode */
436
  blendMode: BLEND_MODES;
437
  
438
  /**
439
   * Set blend mode
440
   * @param blendMode - New blend mode
441
   */
442
  setBlendMode(blendMode: BLEND_MODES): void;
443
}
444
```
445

446
### Mask Filter
447

448
Filter-based masking system.
449

450
```typescript { .api }
451
/**
452
 * Mask filter for complex masking effects
453
 */
454
class MaskFilter extends Filter {
455
  constructor(maskObject: Container);
456
  
457
  /** Mask object */
458
  maskObject: Container;
459
  
460
  /** Invert mask */
461
  invert: boolean;
462
  
463
  /**
464
   * Update mask
465
   * @param maskObject - New mask object
466
   */
467
  updateMask(maskObject: Container): void;
468
}
469
```
470

471
**Usage Examples:**
472

473
```typescript
474
import { 
475
  BlurFilter, 
476
  ColorMatrixFilter, 
477
  DisplacementFilter, 
478
  NoiseFilter,
479
  AlphaFilter,
480
  Filter,
481
  Sprite,
482
  Container,
483
  Assets 
484
} from 'pixi.js';
485

486
// Basic blur filter
487
const blurFilter = new BlurFilter({
488
  strength: 8,
489
  quality: 4,
490
  resolution: 1
491
});
492

493
const sprite = new Sprite(await Assets.load('image.png'));
494
sprite.filters = [blurFilter];
495

496
// Animate blur
497
app.ticker.add(() => {
498
  blurFilter.blur = 5 + Math.sin(Date.now() * 0.001) * 3;
499
});
500

501
// Color matrix effects
502
const colorMatrix = new ColorMatrixFilter();
503

504
// Apply sepia effect
505
colorMatrix.sepia();
506

507
// Apply to container
508
const container = new Container();
509
container.filters = [colorMatrix];
510

511
// Chain multiple color effects
512
colorMatrix.contrast(1.2);
513
colorMatrix.saturate(1.5);
514
colorMatrix.brightness(0.1);
515

516
// Custom color matrix
517
const customMatrix = [
518
  1, 0, 0, 0, 0,  // Red channel
519
  0, 1, 0, 0, 0,  // Green channel  
520
  0, 0, 1, 0, 0,  // Blue channel
521
  0, 0, 0, 1, 0   // Alpha channel
522
];
523
colorMatrix.setMatrix(customMatrix);
524

525
// Displacement filter for distortion
526
const displacementTexture = await Assets.load('displacement.png');
527
const displacementSprite = new Sprite(displacementTexture);
528
const displacementFilter = new DisplacementFilter(displacementSprite, 20);
529

530
sprite.filters = [displacementFilter];
531

532
// Animate displacement
533
app.ticker.add(() => {
534
  displacementSprite.x += 1;
535
  displacementSprite.y += 0.5;
536
});
537

538
// Noise filter
539
const noiseFilter = new NoiseFilter(0.5, Math.random());
540
sprite.filters = [noiseFilter];
541

542
// Multiple filters
543
sprite.filters = [
544
  blurFilter,
545
  colorMatrix,
546
  noiseFilter
547
];
548

549
// Custom filter creation
550
const customFilter = new Filter({
551
  glProgram: GlProgram.from(`
552
    attribute vec2 aVertexPosition;
553
    attribute vec2 aTextureCoord;
554
    
555
    uniform mat3 projectionMatrix;
556
    varying vec2 vTextureCoord;
557
    
558
    void main(void) {
559
      gl_Position = vec4((projectionMatrix * vec3(aVertexPosition, 1.0)).xy, 0.0, 1.0);
560
      vTextureCoord = aTextureCoord;
561
    }
562
  `, `
563
    varying vec2 vTextureCoord;
564
    uniform sampler2D uSampler;
565
    uniform float time;
566
    uniform vec2 resolution;
567
    
568
    void main(void) {
569
      vec2 uv = vTextureCoord;
570
      
571
      // Wave distortion
572
      uv.x += sin(uv.y * 10.0 + time) * 0.02;
573
      uv.y += cos(uv.x * 10.0 + time) * 0.02;
574
      
575
      vec4 color = texture2D(uSampler, uv);
576
      
577
      // Add chromatic aberration
578
      float offset = 0.005;
579
      color.r = texture2D(uSampler, uv + vec2(offset, 0.0)).r;
580
      color.b = texture2D(uSampler, uv - vec2(offset, 0.0)).b;
581
      
582
      gl_FragColor = color;
583
    }
584
  `),
585
  resources: {
586
    uniforms: new UniformGroup({
587
      time: 0,
588
      resolution: [800, 600]
589
    })
590
  }
591
});
592

593
// Update custom filter uniforms
594
app.ticker.add(() => {
595
  customFilter.resources.uniforms.uniforms.time += 0.016;
596
});
597

598
// Filter performance optimization
599
const performantBlur = new BlurFilter({
600
  strength: 4,
601
  quality: 2,  // Lower quality for better performance
602
  resolution: 0.5  // Half resolution
603
});
604

605
// Conditional filter application
606
const screenEffects = new Container();
607
screenEffects.filters = [];
608

609
// Add filters based on settings
610
if (settings.enableBlur) {
611
  screenEffects.filters.push(new BlurFilter(2));
612
}
613

614
if (settings.enableColorGrading) {
615
  const grading = new ColorMatrixFilter();
616
  grading.contrast(1.1);
617
  grading.saturate(1.2);
618
  screenEffects.filters.push(grading);
619
}
620

621
// Filter with alpha blending
622
const overlayFilter = new AlphaFilter(0.8);
623
const overlaySprite = new Sprite(overlayTexture);
624
overlaySprite.filters = [overlayFilter];
625

626
// Complex masking with filters
627
const maskFilter = new MaskFilter(maskContainer);
628
maskFilter.invert = true;
629
sprite.filters = [maskFilter];
630

631
// Filter cleanup
632
sprite.on('destroyed', () => {
633
  if (sprite.filters) {
634
    sprite.filters.forEach(filter => filter.destroy());
635
  }
636
});
637
```