0
# Display Objects
1

2
The display object system forms the core rendering hierarchy of PIXI.js, implementing a scene graph where visual elements can be transformed, nested, and rendered. All visual elements in PIXI.js inherit from the DisplayObject base class and can be organized in a tree structure using Container objects.
3

4
## Scene Graph Architecture
5

6
The display object system uses a hierarchical scene graph where:
7
- **DisplayObject** is the abstract base class for all renderable objects
8
- **Container** extends DisplayObject and can hold child objects
9
- **Sprite**, **Graphics**, **AnimatedSprite**, and **TilingSprite** extend Container for specific rendering use cases
10
- Parent-child relationships enable nested transformations and coordinate spaces
11
- Objects are rendered recursively from root to leaves in the scene graph
12

13
## API Reference
14

15
### DisplayObject { .api }
16

17
The abstract base class for all objects that are rendered on the screen.
18

19
```typescript
20
abstract class DisplayObject extends EventEmitter
21
```
22

23
#### Properties
24

25
- **`parent: Container`** - The display object container that contains this display object
26
- **`worldAlpha: number`** - The multiplied alpha of the displayObject (readonly)
27
- **`transform: Transform`** - World transform and local transform of this object
28
- **`alpha: number`** - The opacity of the object (0-1)
29
- **`visible: boolean`** - The visibility of the object
30
- **`renderable: boolean`** - Can this object be rendered
31
- **`cullable: boolean`** - Should this object be rendered if bounds are out of frame
32
- **`cullArea: Rectangle`** - Custom culling area in local space
33
- **`filterArea: Rectangle`** - The area the filter is applied to
34
- **`filters: Filter[] | null`** - Sets the filters for the displayObject (WebGL only)
35
- **`mask: Container | MaskData | null`** - Sets a mask for the displayObject
36
- **`zIndex: number`** - The zIndex of the displayObject for sorting
37
- **`isSprite: boolean`** - Used to fast check if a sprite is a sprite
38
- **`isMask: boolean`** - Does any other displayObject use this object as a mask
39

40
#### Transform Properties
41

42
- **`x: number`** - The position on the x axis relative to parent
43
- **`y: number`** - The position on the y axis relative to parent  
44
- **`position: ObservablePoint`** - The coordinate relative to parent local coordinates
45
- **`scale: ObservablePoint`** - The scale factors along local coordinate axes
46
- **`pivot: ObservablePoint`** - The center of rotation, scaling, and skewing
47
- **`skew: ObservablePoint`** - The skew factor in radians
48
- **`rotation: number`** - The rotation in radians
49
- **`angle: number`** - The angle in degrees (alias for rotation)
50
- **`worldTransform: Matrix`** - Current transform based on world factors (readonly)
51
- **`localTransform: Matrix`** - Current transform based on local factors (readonly)
52
- **`worldVisible: boolean`** - Indicates if the object is globally visible (readonly)
53
- **`destroyed: boolean`** - Readonly flag for destroyed display objects
54

55
#### Methods
56

57
- **`updateTransform(): void`** - Updates the object transform for rendering
58
- **`getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle`** - Calculates and returns the world bounds
59
- **`getLocalBounds(rect?: Rectangle): Rectangle`** - Retrieves the local bounds as a rectangle
60
- **`toGlobal<P>(position: IPointData, point?: P, skipUpdate?: boolean): P`** - Calculates global position
61
- **`toLocal<P>(position: IPointData, from?: DisplayObject, point?: P, skipUpdate?: boolean): P`** - Calculates local position
62
- **`setParent(container: Container): Container`** - Set the parent Container
63
- **`removeFromParent(): void`** - Remove from parent Container
64
- **`setTransform(x?, y?, scaleX?, scaleY?, rotation?, skewX?, skewY?, pivotX?, pivotY?): this`** - Convenience function to set transform properties
65
- **`destroy(options?: IDestroyOptions | boolean): void`** - Destroys the display object
66

67
#### Events
68

69
- **`added`** - Fired when added to a Container
70
- **`removed`** - Fired when removed from a Container  
71
- **`destroyed`** - Fired when destroy is finished
72

73
### Container { .api }
74

75
General-purpose display object that holds children with built-in support for advanced rendering features.
76

77
```typescript
78
class Container<T extends DisplayObject = DisplayObject> extends DisplayObject
79
```
80

81
#### Properties
82

83
- **`children: T[]`** - The array of children (readonly)
84
- **`sortableChildren: boolean`** - If true, container will sort children by zIndex
85
- **`sortDirty: boolean`** - Should children be sorted at next updateTransform call
86

87
#### Dimension Properties
88

89
- **`width: number`** - The width of the Container (modifies scale to achieve value)
90
- **`height: number`** - The height of the Container (modifies scale to achieve value)
91

92
#### Methods
93

94
##### Child Management
95
- **`addChild<U>(...children: U[]): U[0]`** - Adds one or more children to the container
96
- **`addChildAt<U>(child: U, index: number): U`** - Adds a child at a specified index
97
- **`removeChild<U>(...children: U[]): U[0]`** - Removes one or more children from the container
98
- **`removeChildAt(index: number): T`** - Removes a child at a specified index
99
- **`removeChildren(beginIndex?: number, endIndex?: number): T[]`** - Removes children in the specified range
100
- **`getChildAt(index: number): T`** - Returns the child at the specified index
101
- **`getChildIndex(child: T): number`** - Returns the index position of a child
102
- **`setChildIndex(child: T, index: number): void`** - Changes the position of an existing child
103
- **`getChildByName(name: string, deep?: boolean): T`** - Returns the child with the specified name
104

105
##### Utility Methods
106
- **`swapChildren(child1: T, child2: T): void`** - Swaps the position of 2 children
107
- **`sortChildren(): void`** - Sorts children by zIndex
108
- **`calculateBounds(): void`** - Recalculates the bounds of the container
109

110
### Sprite { .api }
111

112
The base for all textured objects that are rendered to the screen.
113

114
```typescript
115
class Sprite extends Container
116
```
117

118
#### Properties
119

120
- **`texture: Texture`** - The texture that the sprite is using
121
- **`anchor: ObservablePoint`** - The anchor point defines normalized coordinates in the texture
122
- **`tint: ColorSource`** - The tint applied to the sprite
123
- **`blendMode: BLEND_MODES`** - The blend mode to be applied to the sprite
124
- **`pluginName: string`** - Plugin responsible for rendering ('batch' by default)
125
- **`roundPixels: boolean`** - If true, rounds position values to integers
126

127
#### Dimension Properties
128

129
- **`width: number`** - The width of the sprite
130
- **`height: number`** - The height of the sprite
131

132
#### Methods
133

134
- **`static from(source: TextureSource | string, options?: IBaseTextureOptions): Sprite`** - Helper function to create a sprite from a source
135
- **`calculateBounds(): void`** - Calculates the bounds of the sprite
136
- **`containsPoint(point: IPointData): boolean`** - Tests if a point is inside the sprite
137
- **`destroy(options?: IDestroyOptions): void`** - Destroys the sprite
138

139
### Graphics { .api }
140

141
Used to render primitive shapes such as lines, circles and rectangles, and to color and fill them.
142

143
```typescript
144
class Graphics extends Container
145
```
146

147
#### Properties
148

149
- **`blendMode: BLEND_MODES`** - The blend mode to be applied
150
- **`pluginName: string`** - Renderer plugin for batching ('batch' by default)
151
- **`shader: Shader`** - Represents the vertex and fragment shaders
152
- **`tint: ColorSource`** - The tint applied to the graphic shape
153
- **`currentPath: Polygon`** - Current path (readonly)
154

155
#### Drawing State Methods
156

157
- **`lineStyle(width?: number, color?: ColorSource, alpha?: number, alignment?: number, native?: boolean): this`** - Specifies the line style used for subsequent calls to Graphics methods
158
- **`lineStyle(options?: ILineStyleOptions): this`** - Alternative line style with options object  
159
- **`beginFill(color?: ColorSource, alpha?: number): this`** - Begin adding a simple color fill
160
- **`beginTextureFill(options?: IFillStyleOptions): this`** - Begin adding a texture fill
161
- **`endFill(): this`** - Applies the current fill to the current drawing path
162
- **`clear(): this`** - Clears the graphics that were drawn to this Graphics object
163
- **`closePath(): this`** - Closes the current path
164

165
#### Shape Drawing Methods
166

167
- **`moveTo(x: number, y: number): this`** - Moves the current drawing position to x, y
168
- **`lineTo(x: number, y: number): this`** - Draws a line using the current line style from current drawing position to (x, y)
169
- **`bezierCurveTo(cpX: number, cpY: number, cpX2: number, cpY2: number, toX: number, toY: number): this`** - Calculate the points for a bezier curve and draw it
170
- **`quadraticCurveTo(cpX: number, cpY: number, toX: number, toY: number): this`** - Calculate the points for a quadratic bezier curve and draw it
171
- **`arc(cx: number, cy: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): this`** - Draw an arc
172
- **`arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): this`** - Draw an arc to a point
173

174
##### Rectangle Methods
175
- **`drawRect(x: number, y: number, width: number, height: number): this`** - Draws a rectangle shape
176
- **`drawRoundedRect(x: number, y: number, width: number, height: number, radius: number): this`** - Draws a rounded rectangle
177

178
##### Circle Methods  
179
- **`drawCircle(x: number, y: number, radius: number): this`** - Draws a circle
180
- **`drawEllipse(x: number, y: number, width: number, height: number): this`** - Draws an ellipse
181

182
##### Complex Shape Methods
183
- **`drawPolygon(path: IPointData[] | number[]): this`** - Draws a polygon using the given path
184
- **`drawStar(x: number, y: number, points: number, radius: number, innerRadius: number, rotation?: number): this`** - Draw a star shape
185

186
#### Utility Methods
187

188
- **`generateCanvasTexture(scaleMode?: SCALE_MODES, resolution?: number): Texture`** - Generates a canvas texture
189
- **`containsPoint(point: IPointData): boolean`** - Tests if a point is inside any of the graphic shapes
190
- **`calculateBounds(): void`** - Recalculates the bounds of the graphics
191
- **`clone(): Graphics`** - Creates a new Graphics object with identical properties
192

193
### AnimatedSprite { .api }
194

195
A simple way to display an animation depicted by a list of textures.
196

197
```typescript
198
class AnimatedSprite extends Sprite  
199
```
200

201
#### Properties
202

203
- **`animationSpeed: number`** - The speed that the AnimatedSprite will play at (default: 1)
204
- **`loop: boolean`** - Whether or not the animate sprite repeats after playing (default: true)
205
- **`updateAnchor: boolean`** - Update anchor to Texture's defaultAnchor when frame changes (default: false)
206
- **`onComplete?: () => void`** - User-assigned function to call when animation finishes
207
- **`onFrameChange?: (currentFrame: number) => void`** - User-assigned function to call when texture changes
208
- **`onLoop?: () => void`** - User-assigned function to call when animation loops
209
- **`currentFrame: number`** - The currently displayed frame index
210
- **`totalFrames: number`** - The total number of frames in the AnimatedSprite (readonly)
211
- **`textures: Texture[]`** - The array of textures used for the AnimatedSprite
212
- **`playing: boolean`** - Whether or not the AnimatedSprite is currently playing (readonly)
213

214
#### Methods
215

216
- **`stop(): void`** - Stops the AnimatedSprite
217
- **`play(): void`** - Plays the AnimatedSprite
218
- **`gotoAndStop(frameNumber: number): void`** - Stops animation and goes to a specific frame
219
- **`gotoAndPlay(frameNumber: number): void`** - Goes to a specific frame and begins playing the AnimatedSprite
220
- **`update(deltaTime: number): void`** - Updates the object transform for rendering
221
- **`destroy(options?: IDestroyOptions): void`** - Destroys the AnimatedSprite
222

223
#### Static Methods
224

225
- **`static fromFrames(frames: string[]): AnimatedSprite`** - A short hand way of creating an AnimatedSprite from an array of frame ids
226
- **`static fromImages(images: string[]): AnimatedSprite`** - A short hand way of creating an AnimatedSprite from an array of image ids
227

228
### TilingSprite { .api }
229

230
A fast way of rendering a tiling image.
231

232
```typescript  
233
class TilingSprite extends Sprite
234
```
235

236
#### Properties
237

238
- **`tileTransform: Transform`** - Tile transform
239
- **`uvMatrix: TextureMatrix`** - Matrix applied to UV to get coords in Texture normalized space
240
- **`uvRespectAnchor: boolean`** - Whether tiling pattern should originate from origin instead of top-left (default: false)
241
- **`clampMargin: number`** - Changes frame clamping in textureTransform (default: 0.5)
242

243
#### Tile Properties
244

245
- **`tileScale: ObservablePoint`** - The scaling of the image that is being tiled
246
- **`tilePosition: ObservablePoint`** - The offset of the image that is being tiled
247

248
#### Methods
249

250
- **`static from(source: TextureSource, options: ISize): TilingSprite`** - Helper function to create a TilingSprite from a source
251
- **`calculateBounds(): void`** - Calculates the bounds of the TilingSprite
252

253
## Type Definitions
254

255
```typescript
256
interface IDestroyOptions {
257
    children?: boolean;
258
    texture?: boolean;
259
    baseTexture?: boolean;
260
}
261

262
interface IPointData {
263
    x: number;
264
    y: number;
265
}
266

267
interface ISize {
268
    width: number;
269
    height: number;
270
}
271

272
interface IFillStyleOptions {
273
    color?: ColorSource;
274
    alpha?: number;
275
    texture?: Texture;
276
    matrix?: Matrix;
277
}
278

279
interface ILineStyleOptions extends IFillStyleOptions {
280
    width?: number;
281
    alignment?: number;
282
    native?: boolean;
283
    cap?: LINE_CAP;
284
    join?: LINE_JOIN;
285
    miterLimit?: number;
286
}
287

288
type ColorSource = number | string | number[] | Color;
289
type TextureSource = string | BaseTexture | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement;
290

291
enum BLEND_MODES {
292
    NORMAL = 0,
293
    ADD = 1,
294
    MULTIPLY = 2,
295
    SCREEN = 3,
296
    // ... additional blend modes
297
}
298

299
enum SCALE_MODES {
300
    NEAREST = 0,
301
    LINEAR = 1
302
}
303
```
304

305
## Common Usage Examples
306

307
### Basic Container and Children
308

309
```javascript
310
import { Application, Container, Sprite } from 'pixi.js';
311

312
const app = new Application();
313
const container = new Container();
314

315
// Add sprites to container
316
const sprite1 = Sprite.from('image1.png');
317
const sprite2 = Sprite.from('image2.png');
318

319
sprite1.x = 100;
320
sprite2.x = 200;
321

322
container.addChild(sprite1, sprite2);
323
app.stage.addChild(container);
324

325
// Transform entire container
326
container.scale.set(2, 2);
327
container.rotation = Math.PI / 4;
328
```
329

330
### Graphics Drawing
331

332
```javascript
333
import { Graphics } from 'pixi.js';
334

335
const graphics = new Graphics();
336

337
// Draw a red circle
338
graphics.beginFill(0xff0000, 1);
339
graphics.drawCircle(0, 0, 50);
340
graphics.endFill();
341

342
// Draw a green rectangle with blue outline
343
graphics.lineStyle(4, 0x0000ff, 1);
344
graphics.beginFill(0x00ff00, 0.8);
345
graphics.drawRect(100, 100, 150, 100);
346
graphics.endFill();
347

348
app.stage.addChild(graphics);
349
```
350

351
### Sprite with Transformations
352

353
```javascript
354
import { Sprite } from 'pixi.js';
355

356
const sprite = Sprite.from('character.png');
357

358
// Set anchor to center for rotation
359
sprite.anchor.set(0.5);
360

361
// Position and transform
362
sprite.x = 400;
363
sprite.y = 300;
364
sprite.scale.set(1.5);
365
sprite.rotation = Math.PI / 6;
366
sprite.tint = 0xff9999;
367

368
app.stage.addChild(sprite);
369
```
370

371
### AnimatedSprite Setup
372

373
```javascript
374
import { AnimatedSprite, Texture } from 'pixi.js';
375

376
// Create array of textures for animation
377
const textures = [];
378
for (let i = 0; i < 30; i++) {
379
    textures.push(Texture.from(`explosion${i}.png`));
380
}
381

382
const explosion = new AnimatedSprite(textures);
383
explosion.anchor.set(0.5);
384
explosion.x = app.screen.width / 2;
385
explosion.y = app.screen.height / 2;
386
explosion.animationSpeed = 0.5;
387
explosion.loop = false;
388

389
explosion.onComplete = () => {
390
    explosion.destroy();
391
};
392

393
explosion.play();
394
app.stage.addChild(explosion);
395
```
396

397
### TilingSprite for Backgrounds
398

399
```javascript
400
import { TilingSprite } from 'pixi.js';
401

402
const tilingSprite = TilingSprite.from('background-tile.png', {
403
    width: app.screen.width,
404
    height: app.screen.height
405
});
406

407
// Animate the tiling
408
app.ticker.add(() => {
409
    tilingSprite.tilePosition.x -= 2;
410
    tilingSprite.tilePosition.y -= 1;
411
});
412

413
app.stage.addChild(tilingSprite);
414
```
415

416
### Masking with Graphics
417

418
```javascript
419
import { Graphics, Sprite } from 'pixi.js';
420

421
const sprite = Sprite.from('photo.jpg');
422
const mask = new Graphics();
423

424
// Create circular mask
425
mask.beginFill(0xffffff);
426
mask.drawCircle(0, 0, 100);
427
mask.endFill();
428

429
// Position mask
430
mask.x = sprite.width / 2;
431
mask.y = sprite.height / 2;
432

433
// Apply mask
434
sprite.mask = mask;
435
sprite.addChild(mask); // Mask must be child of masked object
436

437
app.stage.addChild(sprite);
438
```
439

440
### Nested Containers with Transforms
441

442
```javascript
443
import { Container, Graphics } from 'pixi.js';
444

445
const outerContainer = new Container();
446
const innerContainer = new Container();
447

448
// Create some graphics
449
const circle = new Graphics()
450
    .beginFill(0xff0000)
451
    .drawCircle(0, 0, 25)
452
    .endFill();
453

454
const rect = new Graphics()
455
    .beginFill(0x00ff00)
456
    .drawRect(-25, -25, 50, 50)
457
    .endFill();
458

459
// Build hierarchy
460
innerContainer.addChild(circle, rect);
461
outerContainer.addChild(innerContainer);
462

463
// Transform containers independently
464
innerContainer.rotation = Math.PI / 4;
465
outerContainer.scale.set(2);
466
outerContainer.x = 200;
467
outerContainer.y = 150;
468

469
app.stage.addChild(outerContainer);
470
```
471

472
## Transform Order and Coordinate Spaces
473

474
Transform properties are applied in the following order:
475
1. **Scale** - Applied first around the pivot point
476
2. **Rotation** - Applied around the pivot point  
477
3. **Skew** - Applied around the pivot point
478
4. **Translation** - The position property moves the pivot point
479

480
Each display object maintains its own local coordinate space that is transformed to its parent's coordinate space through the transform chain. The `worldTransform` matrix represents the accumulated transform from the root to the current object.
481

482
## Performance Considerations
483

484
- Use `Container.sortableChildren = false` when z-ordering is not needed for better performance
485
- Set `renderable = false` instead of `visible = false` when you want to keep transforms updating
486
- Use object pooling for frequently created/destroyed display objects like particles
487
- Minimize deep nesting hierarchies for better transform update performance
488
- Use `cullable = true` and set appropriate `cullArea` for off-screen culling
489
- Batch sprite rendering by using similar textures and blend modes