0
# Application Framework
1
2
The PixiJS Application Framework provides a convenient, high-level interface for creating and managing a complete PixiJS rendering setup. The `Application` class automatically handles renderer creation, provides a root display container, and integrates with the plugin system to add additional functionality like automatic rendering loops and responsive resizing.
3
4
## Core Classes
5
6
### Application Class { .api }
7
8
```typescript
9
class Application<VIEW extends ICanvas = ICanvas> {
10
// Static properties
11
static _plugins: IApplicationPlugin[];
12
13
// Instance properties
14
stage: Container;
15
renderer: IRenderer<VIEW>;
16
17
// Constructor
18
constructor(options?: Partial<IApplicationOptions>);
19
20
// Methods
21
render(): void;
22
destroy(removeView?: boolean, stageOptions?: IDestroyOptions | boolean): void;
23
24
// Getters
25
get view(): VIEW;
26
get screen(): Rectangle;
27
}
28
```
29
30
Creates a new PixiJS application instance that automatically sets up a renderer and root container.
31
32
**Parameters:**
33
- `options` *(Partial<IApplicationOptions>, optional)*: Configuration options for the application and renderer
34
35
**Properties:**
36
- `stage` *(Container)*: The root display container that serves as the scene graph root
37
- `renderer` *(IRenderer<VIEW>)*: The renderer instance (WebGL or Canvas) used for drawing
38
- `view` *(VIEW, readonly)*: Reference to the renderer's canvas element
39
- `screen` *(Rectangle, readonly)*: Reference to the renderer's screen rectangle, safe to use as filterArea or hitArea
40
41
**Methods:**
42
43
#### render() { .api }
44
```typescript
45
render(): void
46
```
47
Renders the current stage to the canvas. Called automatically when using ticker plugin.
48
49
#### destroy(removeView?, stageOptions?) { .api }
50
```typescript
51
destroy(removeView?: boolean, stageOptions?: IDestroyOptions | boolean): void
52
```
53
Destroys the application and cleans up all resources.
54
55
**Parameters:**
56
- `removeView` *(boolean, optional)*: Whether to automatically remove canvas from DOM
57
- `stageOptions` *(IDestroyOptions | boolean, optional)*: Options for destroying stage children, or boolean for all options
58
59
## Configuration Interfaces
60
61
### IApplicationOptions { .api }
62
63
```typescript
64
interface IApplicationOptions extends IRendererOptionsAuto, GlobalMixins.IApplicationOptions {
65
// Inherited from IRendererOptionsAuto
66
forceCanvas?: boolean;
67
68
// Inherited from IRendererOptions via IRendererOptionsAuto
69
// View options
70
view?: ICanvas;
71
width?: number;
72
height?: number;
73
resolution?: number;
74
autoDensity?: boolean;
75
76
// Background options
77
backgroundColor?: ColorSource;
78
background?: ColorSource;
79
backgroundAlpha?: number;
80
clearBeforeRender?: boolean;
81
82
// Context options (WebGL)
83
useContextAlpha?: boolean | 'notMultiplied';
84
context?: IRenderingContext | null;
85
antialias?: boolean;
86
powerPreference?: WebGLPowerPreference;
87
premultipliedAlpha?: boolean;
88
preserveDrawingBuffer?: boolean;
89
90
// Startup options
91
hello?: boolean;
92
93
// Plugin-added options (when using full pixi.js bundle)
94
resizeTo?: Window | HTMLElement;
95
autoStart?: boolean;
96
sharedTicker?: boolean;
97
}
98
```
99
100
Configuration interface for Application constructor. Combines renderer options with plugin-specific options.
101
102
**Core Options:**
103
- `forceCanvas` *(boolean)*: Force use of CanvasRenderer even if WebGL is available
104
- `view` *(ICanvas)*: Existing canvas element to use, creates new one if omitted
105
- `width` *(number)*: Width of the renderer's view
106
- `height` *(number)*: Height of the renderer's view
107
- `resolution` *(number)*: Device pixel ratio for the renderer
108
- `autoDensity` *(boolean)*: Whether CSS dimensions should resize automatically
109
110
**Background Options:**
111
- `backgroundColor` *(ColorSource)*: Background color for clearing the canvas
112
- `background` *(ColorSource)*: Alias for backgroundColor
113
- `backgroundAlpha` *(number)*: Background transparency (0-1)
114
- `clearBeforeRender` *(boolean)*: Whether to clear canvas before each render
115
116
**WebGL Context Options:**
117
- `antialias` *(boolean)*: Whether to enable anti-aliasing
118
- `premultipliedAlpha` *(boolean)*: Whether drawing buffer has premultiplied alpha
119
- `preserveDrawingBuffer` *(boolean)*: Whether to preserve drawing buffer for toDataURL
120
- `powerPreference` *(WebGLPowerPreference)*: GPU performance hint ('default', 'high-performance', 'low-power')
121
122
**Plugin Options (available with full bundle):**
123
- `resizeTo` *(Window | HTMLElement)*: Element to automatically resize to
124
- `autoStart` *(boolean)*: Whether to automatically start the render loop
125
- `sharedTicker` *(boolean)*: Whether to use the shared ticker instance
126
127
### IApplicationPlugin { .api }
128
129
```typescript
130
interface IApplicationPlugin {
131
init(options: Partial<IApplicationOptions>): void;
132
destroy(): void;
133
}
134
```
135
136
Interface for Application plugins. Plugins extend Application functionality through the extension system.
137
138
**Methods:**
139
- `init()`: Called during Application construction with the provided options
140
- `destroy()`: Called when Application is destroyed for cleanup
141
142
## Extended Functionality (Available with Plugins)
143
144
When using the full pixi.js bundle, the Application class is extended with additional functionality through plugins:
145
146
### Resize Plugin Methods { .api }
147
148
```typescript
149
interface Application {
150
resizeTo: Window | HTMLElement;
151
resize(): void;
152
queueResize(): void;
153
cancelResize(): void;
154
}
155
```
156
157
**Properties:**
158
- `resizeTo` *(Window | HTMLElement)*: Element to automatically resize the renderer to match
159
160
**Methods:**
161
162
#### resize() { .api }
163
```typescript
164
resize(): void
165
```
166
Execute immediate resize based on `resizeTo` element dimensions. Not throttled.
167
168
#### queueResize() { .api }
169
```typescript
170
queueResize(): void
171
```
172
Queue a throttled resize using requestAnimationFrame. Safe to call multiple times per frame.
173
174
#### cancelResize() { .api }
175
```typescript
176
cancelResize(): void
177
```
178
Cancel any queued resize operation.
179
180
### Ticker Plugin Methods { .api }
181
182
```typescript
183
interface Application {
184
ticker: Ticker;
185
start(): void;
186
stop(): void;
187
}
188
```
189
190
**Properties:**
191
- `ticker` *(Ticker)*: Ticker instance used for the render loop
192
193
**Methods:**
194
195
#### start() { .api }
196
```typescript
197
start(): void
198
```
199
Start the automatic rendering loop.
200
201
#### stop() { .api }
202
```typescript
203
stop(): void
204
```
205
Stop the automatic rendering loop.
206
207
## Type Definitions
208
209
### ICanvas { .api }
210
211
```typescript
212
interface ICanvas extends Partial<EventTarget> {
213
width: number;
214
height: number;
215
style?: ICanvasStyle;
216
217
getContext(contextId: '2d', options?: ICanvasRenderingContext2DSettings): ICanvasRenderingContext2D | null;
218
getContext(contextId: 'webgl' | 'experimental-webgl', options?: WebGLContextAttributes): WebGLRenderingContext | null;
219
getContext(contextId: 'webgl2' | 'experimental-webgl2', options?: WebGLContextAttributes): WebGL2RenderingContext | null;
220
}
221
```
222
223
Canvas interface supporting both HTML canvas and OffscreenCanvas.
224
225
### IDestroyOptions { .api }
226
227
```typescript
228
interface IDestroyOptions {
229
children?: boolean;
230
texture?: boolean;
231
baseTexture?: boolean;
232
}
233
```
234
235
Options for destroying display objects and their resources.
236
237
### Rectangle { .api }
238
239
```typescript
240
class Rectangle {
241
x: number;
242
y: number;
243
width: number;
244
height: number;
245
}
246
```
247
248
Rectangle class representing a rectangular area with position and dimensions.
249
250
### Container { .api }
251
252
```typescript
253
class Container<T extends DisplayObject = DisplayObject> extends DisplayObject {
254
// Display container for organizing and managing display objects
255
}
256
```
257
258
Root container class that serves as the scene graph root in Application.stage.
259
260
## Usage Examples
261
262
### Basic Application Setup
263
264
```typescript
265
import { Application } from 'pixi.js';
266
267
// Create application with default options
268
const app = new Application();
269
270
// Add canvas to DOM
271
document.body.appendChild(app.view);
272
273
// Add content to the stage
274
const graphics = new Graphics();
275
graphics.beginFill(0xff0000);
276
graphics.drawRect(0, 0, 100, 100);
277
app.stage.addChild(graphics);
278
279
// Manual render (if not using ticker plugin)
280
app.render();
281
```
282
283
### Application with Custom Options
284
285
```typescript
286
import { Application } from 'pixi.js';
287
288
const app = new Application({
289
width: 800,
290
height: 600,
291
backgroundColor: 0x1099bb,
292
resolution: window.devicePixelRatio || 1,
293
autoDensity: true,
294
antialias: true,
295
powerPreference: 'high-performance'
296
});
297
298
document.body.appendChild(app.view);
299
```
300
301
### Responsive Application with Auto-Resize
302
303
```typescript
304
import { Application } from 'pixi.js';
305
306
// Create application that resizes to window
307
const app = new Application({
308
resizeTo: window,
309
backgroundColor: 0x2c3e50
310
});
311
312
// Alternative: resize to specific container
313
const container = document.getElementById('game-container');
314
const app2 = new Application({
315
resizeTo: container
316
});
317
```
318
319
### Application with Custom Canvas
320
321
```typescript
322
import { Application } from 'pixi.js';
323
324
// Use existing canvas element
325
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;
326
const app = new Application({
327
view: canvas,
328
width: canvas.width,
329
height: canvas.height
330
});
331
332
// Or use OffscreenCanvas for web workers
333
const offscreenCanvas = new OffscreenCanvas(800, 600);
334
const offscreenApp = new Application({
335
view: offscreenCanvas,
336
width: 800,
337
height: 600
338
});
339
```
340
341
### Application with Render Loop Control
342
343
```typescript
344
import { Application, Ticker } from 'pixi.js';
345
346
const app = new Application({
347
autoStart: false, // Don't start automatically
348
sharedTicker: false // Use dedicated ticker
349
});
350
351
// Custom render loop
352
const gameLoop = (delta: number) => {
353
// Update game logic
354
updateGame(delta);
355
356
// Render the scene
357
app.render();
358
};
359
360
// Start custom loop
361
app.ticker.add(gameLoop);
362
app.start();
363
364
// Later: stop the loop
365
app.stop();
366
```
367
368
### Proper Application Cleanup
369
370
```typescript
371
import { Application } from 'pixi.js';
372
373
const app = new Application();
374
375
// When done with the application
376
const cleanup = () => {
377
// Remove from DOM and destroy all children
378
app.destroy(true, {
379
children: true,
380
texture: true,
381
baseTexture: true
382
});
383
};
384
385
// Call cleanup on page unload or component unmount
386
window.addEventListener('beforeunload', cleanup);
387
```
388
389
### Plugin Integration
390
391
```typescript
392
import { Application, extensions } from 'pixi.js';
393
394
// Custom plugin example
395
class MyPlugin {
396
static init(options) {
397
this.myProperty = options.myOption || 'default';
398
console.log('Plugin initialized');
399
}
400
401
static destroy() {
402
console.log('Plugin destroyed');
403
this.myProperty = null;
404
}
405
}
406
407
// Register plugin
408
extensions.add({
409
type: 'Application',
410
ref: MyPlugin
411
});
412
413
// Use application with plugin
414
const app = new Application({
415
myOption: 'custom value'
416
});
417
```
418
419
## Performance Considerations
420
421
- Use `autoStart: false` and manual rendering for frame rate control
422
- Set appropriate `resolution` based on device pixel ratio and performance requirements
423
- Use `clearBeforeRender: false` if rendering opaque backgrounds to skip clear operations
424
- Consider `powerPreference: 'low-power'` for battery-conscious applications
425
- Properly destroy applications to prevent memory leaks
426
- Use shared ticker (`sharedTicker: true`) when running multiple applications
427
428
## Common Patterns
429
430
### Multi-Scene Applications
431
```typescript
432
// Create application once
433
const app = new Application({ resizeTo: window });
434
435
// Swap scenes by changing stage children
436
const showScene = (scene: Container) => {
437
app.stage.removeChildren();
438
app.stage.addChild(scene);
439
};
440
```
441
442
### Responsive Fullscreen
443
```typescript
444
const app = new Application({
445
resizeTo: window,
446
autoDensity: true,
447
resolution: Math.min(window.devicePixelRatio, 2) // Cap at 2x for performance
448
});
449
450
// Handle orientation changes
451
screen.orientation?.addEventListener('change', () => {
452
app.queueResize();
453
});
454
```
455
456
### Canvas Integration
457
```typescript
458
// Get canvas for additional 2D context operations
459
const canvas = app.view as HTMLCanvasElement;
460
const ctx = canvas.getContext('2d');
461
462
// Draw over PixiJS content (after render)
463
app.ticker.add(() => {
464
app.render(); // PixiJS content
465
466
// Additional 2D context drawing
467
ctx.fillStyle = 'rgba(255, 0, 0, 0.5)';
468
ctx.fillRect(10, 10, 100, 50);
469
});
470
```