0
# @pixi/core
1
2
@pixi/core is the foundational WebGL rendering library of PixiJS, providing essential 2D graphics infrastructure and hardware-accelerated rendering capabilities. It offers comprehensive WebGL context management, texture systems, geometry handling, shader management, and renderer abstraction layers with automatic Canvas fallback.
3
4
## Package Information
5
6
- **Package Name**: @pixi/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pixi/core`
10
11
## Core Imports
12
13
```typescript
14
import {
15
Renderer,
16
AbstractRenderer,
17
autoDetectRenderer,
18
Texture,
19
BaseTexture,
20
Geometry,
21
Shader,
22
Filter,
23
Resource,
24
BufferResource,
25
ImageResource,
26
CanvasResource,
27
TextureMatrix,
28
RenderTexture,
29
Framebuffer
30
} from "@pixi/core";
31
```
32
33
For CommonJS:
34
35
```javascript
36
const {
37
Renderer,
38
AbstractRenderer,
39
autoDetectRenderer,
40
Texture,
41
BaseTexture,
42
Geometry,
43
Shader,
44
Filter,
45
Resource,
46
BufferResource,
47
ImageResource,
48
CanvasResource,
49
TextureMatrix,
50
RenderTexture,
51
Framebuffer
52
} = require("@pixi/core");
53
```
54
55
## Basic Usage
56
57
```typescript
58
import { autoDetectRenderer, Texture, Geometry, Shader } from "@pixi/core";
59
60
// Create a renderer that auto-detects WebGL support
61
const renderer = autoDetectRenderer({
62
width: 800,
63
height: 600,
64
backgroundColor: 0x1099bb
65
});
66
67
// Add canvas to DOM
68
document.body.appendChild(renderer.view);
69
70
// Create a texture from an image
71
const texture = Texture.from('/path/to/image.png');
72
73
// Create geometry for a quad
74
const geometry = new Geometry()
75
.addAttribute('aVertexPosition', [-1, -1, 1, -1, 1, 1, -1, 1], 2)
76
.addAttribute('aTextureCoord', [0, 0, 1, 0, 1, 1, 0, 1], 2)
77
.addIndex([0, 1, 2, 0, 2, 3]);
78
79
// Basic shader
80
const shader = Shader.from(`
81
attribute vec2 aVertexPosition;
82
attribute vec2 aTextureCoord;
83
varying vec2 vTextureCoord;
84
85
void main() {
86
gl_Position = vec4(aVertexPosition, 0.0, 1.0);
87
vTextureCoord = aTextureCoord;
88
}
89
`, `
90
precision mediump float;
91
varying vec2 vTextureCoord;
92
uniform sampler2D uSampler;
93
94
void main() {
95
gl_FragColor = texture2D(uSampler, vTextureCoord);
96
}
97
`);
98
99
// Clear and render
100
renderer.clear();
101
```
102
103
## Architecture
104
105
@pixi/core is built around several key architectural components:
106
107
- **Renderer System**: `AbstractRenderer` and `Renderer` provide the core rendering pipeline with WebGL context management
108
- **Texture System**: `Texture`, `BaseTexture`, and texture resources handle all image data and GPU texture management
109
- **Geometry System**: `Geometry`, `Buffer`, and `Attribute` classes manage vertex data and GPU buffers
110
- **Shader System**: `Shader`, `Program`, and `UniformGroup` provide shader compilation and management
111
- **Rendering Systems**: Modular systems handle specific rendering aspects (masks, filters, state, etc.)
112
- **State Management**: WebGL state tracking and optimization through the `State` system
113
- **Framebuffer System**: Off-screen rendering capabilities with `Framebuffer` and `RenderTexture`
114
115
## Capabilities
116
117
### Rendering
118
119
Core rendering functionality including WebGL context management, render loops, and automatic renderer detection.
120
121
```typescript { .api }
122
abstract class AbstractRenderer extends EventEmitter {
123
resolution: number;
124
screen: Rectangle;
125
view: HTMLCanvasElement;
126
plugins: IRendererPlugins;
127
clearBeforeRender?: boolean;
128
options: IRendererOptions;
129
type: RENDERER_TYPE;
130
useContextAlpha: boolean | 'notMultiplied';
131
autoDensity: boolean;
132
preserveDrawingBuffer: boolean;
133
134
resize(desiredScreenWidth: number, desiredScreenHeight: number): void;
135
render(displayObject: IRenderableObject, options?: IRendererRenderOptions): void;
136
generateTexture(displayObject: IRenderableObject, options?: IGenerateTextureOptions): RenderTexture;
137
addSystem(ClassRef: ISystemConstructor, name?: string): this;
138
destroy(removeView?: boolean): void;
139
}
140
141
class Renderer extends AbstractRenderer {
142
gl: IRenderingContext;
143
globalUniforms: UniformGroup;
144
145
constructor(options?: IRendererOptions);
146
reset(): this;
147
clear(): void;
148
}
149
150
function autoDetectRenderer(options?: IRendererOptionsAuto): AbstractRenderer;
151
```
152
153
[Rendering](./rendering.md)
154
155
### Textures
156
157
Comprehensive texture management system supporting multiple resource types, texture atlases, and GPU texture optimization.
158
159
```typescript { .api }
160
class Texture<R = Resource> extends EventEmitter {
161
static EMPTY: Texture;
162
static WHITE: Texture;
163
164
baseTexture: BaseTexture<R>;
165
frame: Rectangle;
166
orig: Rectangle;
167
trim: Rectangle;
168
valid: boolean;
169
noFrame: boolean;
170
defaultAnchor: Point;
171
uvMatrix: TextureMatrix;
172
rotate: number;
173
174
constructor(baseTexture: BaseTexture<R>, frame?: Rectangle, orig?: Rectangle, trim?: Rectangle, rotate?: number, anchor?: IPointData);
175
static from<R extends Resource = Resource>(source: TextureSource | TextureSource[], options?: IBaseTextureOptions): Texture<R>;
176
static fromURL<R extends Resource = Resource>(url: string, options?: IBaseTextureOptions): Promise<Texture<R>>;
177
static fromBuffer(buffer: Float32Array | Uint8Array, width: number, height: number): Texture<BufferResource>;
178
static fromLoader<R extends Resource = Resource>(source: HTMLImageElement | HTMLCanvasElement | string, imageUrl: string, name?: string, options?: IBaseTextureOptions): Promise<Texture<R>>;
179
static addToCache(texture: Texture, id: string): void;
180
static removeFromCache(texture: string | Texture): Texture | null;
181
clone(): Texture;
182
update(): void;
183
destroy(destroyBase?: boolean): void;
184
}
185
186
class BaseTexture<R = Resource> extends EventEmitter {
187
width: number;
188
height: number;
189
resolution: number;
190
resource: R;
191
192
update(): void;
193
setSize(desiredWidth: number, desiredHeight: number, resolution?: number): this;
194
destroy(): void;
195
}
196
```
197
198
[Textures](./textures.md)
199
200
### Geometry
201
202
Vertex data management with GPU buffer optimization, attribute handling, and efficient geometry rendering.
203
204
```typescript { .api }
205
class Geometry extends EventEmitter {
206
buffers: Buffer[];
207
indexBuffer: Buffer;
208
attributes: {[key: string]: Attribute};
209
210
addAttribute(id: string, buffer: ArrayLike<number> | Buffer | Attribute, size?: number): this;
211
addIndex(buffer: ArrayLike<number> | Buffer): this;
212
getAttribute(id: string): Attribute;
213
getBuffer(id: string): Buffer;
214
clone(): Geometry;
215
destroy(): void;
216
}
217
218
class Buffer {
219
data: IArrayBuffer;
220
type: BUFFER_TYPE;
221
222
constructor(data?: IArrayBuffer, _static?: boolean, index?: boolean);
223
update(data?: IArrayBuffer): void;
224
destroy(): void;
225
}
226
```
227
228
[Geometry](./geometry.md)
229
230
### Shaders
231
232
Shader compilation, uniform management, and program linking with full WebGL shader support.
233
234
```typescript { .api }
235
class Shader extends EventEmitter {
236
program: Program;
237
uniforms: Dict<any>;
238
239
constructor(program: Program, uniforms?: Dict<any>);
240
static from(vertexSrc?: string, fragmentSrc?: string, uniforms?: Dict<any>): Shader;
241
destroy(): void;
242
}
243
244
class Program {
245
vertexSrc: string;
246
fragmentSrc: string;
247
248
constructor(vertexSrc?: string, fragmentSrc?: string, name?: string);
249
static from(vertexSrc?: string, fragmentSrc?: string, name?: string): Program;
250
}
251
252
class UniformGroup<LAYOUT = Dict<any>> extends EventEmitter {
253
uniforms: LAYOUT;
254
255
constructor(uniforms: LAYOUT | Buffer, _static?: boolean, _id?: number);
256
update(): void;
257
}
258
```
259
260
[Shaders](./shaders.md)
261
262
### Systems
263
264
Modular rendering systems that handle specific aspects of the WebGL rendering pipeline.
265
266
```typescript { .api }
267
interface ISystem {
268
destroy(): void;
269
}
270
271
// Core systems available on Renderer
272
interface RendererSystems {
273
mask: MaskSystem;
274
context: ContextSystem;
275
state: StateSystem;
276
shader: ShaderSystem;
277
texture: TextureSystem;
278
buffer: BufferSystem;
279
geometry: GeometrySystem;
280
framebuffer: FramebufferSystem;
281
filter: FilterSystem;
282
batch: BatchSystem;
283
// ... additional systems
284
}
285
```
286
287
[Systems](./systems.md)
288
289
### Filters
290
291
Post-processing effects and rendering filters for advanced visual effects.
292
293
```typescript { .api }
294
class Filter extends Shader {
295
padding: number;
296
multisample: MSAA_QUALITY;
297
enabled: boolean;
298
autoFit: boolean;
299
300
constructor(vertexSrc?: string, fragmentSrc?: string, uniforms?: Dict<any>);
301
apply(filterManager: FilterSystem, input: RenderTexture, output: RenderTexture, clearMode?: CLEAR_MODES): void;
302
}
303
304
class FilterState {
305
renderTexture: RenderTexture;
306
target: IRenderableObject;
307
filters: Filter[];
308
309
constructor();
310
clear(): void;
311
}
312
```
313
314
[Filters](./filters.md)
315
316
### State Management
317
318
WebGL state tracking and optimization to minimize state changes and improve performance.
319
320
```typescript { .api }
321
class State {
322
data: number;
323
blendMode: BLEND_MODES;
324
polygonOffset: number;
325
326
constructor();
327
clone(): State;
328
reset(): void;
329
}
330
```
331
332
[State Management](./state.md)
333
334
### Framebuffers
335
336
Off-screen rendering capabilities with render textures and framebuffer management.
337
338
```typescript { .api }
339
class Framebuffer {
340
width: number;
341
height: number;
342
multisample: MSAA_QUALITY;
343
stencil: boolean;
344
depth: boolean;
345
346
constructor(width: number, height: number);
347
addColorTexture(index?: number, texture?: BaseTexture<Resource>): this;
348
resize(width: number, height: number): void;
349
destroy(): void;
350
}
351
352
class RenderTexture extends Texture {
353
static create(options: IBaseRenderTextureOptions): RenderTexture;
354
355
resize(desiredWidth: number, desiredHeight: number, resizeBaseTexture?: boolean): void;
356
}
357
```
358
359
[Framebuffers](./framebuffers.md)
360
361
## Types
362
363
Common types and interfaces used throughout the @pixi/core API:
364
365
```typescript { .api }
366
interface IRenderableObject {
367
parent: IRenderableContainer;
368
enableTempParent(): IRenderableContainer;
369
updateTransform(): void;
370
disableTempParent(parent: IRenderableContainer): void;
371
render(renderer: Renderer): void;
372
}
373
374
interface IRenderableContainer extends IRenderableObject {
375
children: IRenderableObject[];
376
addChild(child: IRenderableObject): IRenderableObject;
377
removeChild(child: IRenderableObject): IRenderableObject;
378
}
379
380
interface IRenderingContext extends WebGL2RenderingContext {}
381
382
interface IRendererRenderOptions {
383
renderTexture?: RenderTexture;
384
clear?: boolean;
385
transform?: Matrix;
386
skipUpdateTransform?: boolean;
387
}
388
389
interface IGenerateTextureOptions {
390
scaleMode?: SCALE_MODES;
391
resolution?: number;
392
region?: Rectangle;
393
multisample?: MSAA_QUALITY;
394
}
395
396
interface ISystemConstructor {
397
new (renderer: Renderer): ISystem;
398
}
399
400
interface ISystem {
401
destroy(): void;
402
}
403
404
interface IRendererOptions {
405
view?: HTMLCanvasElement;
406
resolution?: number;
407
autoDensity?: boolean;
408
backgroundColor?: number;
409
backgroundAlpha?: number;
410
clearBeforeRender?: boolean;
411
preserveDrawingBuffer?: boolean;
412
width?: number;
413
height?: number;
414
antialias?: boolean;
415
useContextAlpha?: boolean | 'notMultiplied';
416
powerPreference?: WebGLPowerPreference;
417
context?: IRenderingContext;
418
transparent?: boolean; // deprecated since 6.0.0
419
}
420
421
interface IRendererOptionsAuto extends IRendererOptions {
422
forceCanvas?: boolean;
423
}
424
425
interface IBaseTextureOptions {
426
scaleMode?: SCALE_MODES;
427
resolution?: number;
428
mipmap?: MIPMAP_MODES;
429
anisotropicLevel?: number;
430
wrapMode?: WRAP_MODES;
431
format?: FORMATS;
432
type?: TYPES;
433
target?: TARGETS;
434
alphaMode?: ALPHA_MODES;
435
}
436
437
interface IPointData {
438
x: number;
439
y: number;
440
}
441
442
abstract class Resource {
443
width: number;
444
height: number;
445
valid: boolean;
446
447
bind(baseTexture: BaseTexture): void;
448
unbind(baseTexture: BaseTexture): void;
449
resize(width: number, height: number): void;
450
update(): void;
451
destroy(): void;
452
}
453
454
class BufferResource extends Resource {
455
constructor(source: Float32Array | Uint8Array, options: { width: number; height: number });
456
}
457
458
class ImageResource extends Resource {
459
url: string;
460
461
constructor(source: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap | string);
462
}
463
464
class CanvasResource extends Resource {
465
canvas: HTMLCanvasElement;
466
467
constructor(source: HTMLCanvasElement);
468
}
469
470
class TextureMatrix {
471
mapCoord: Matrix;
472
uClampFrame: Float32Array;
473
uClampOffset: Float32Array;
474
475
constructor(texture?: Texture, clampMargin?: number);
476
update(forceUpdate?: boolean): boolean;
477
}
478
479
type TextureSource = string | BaseTexture | ImageSource;
480
type ImageSource = HTMLImageElement | HTMLVideoElement | ImageBitmap | HTMLCanvasElement;
481
482
// Constants from @pixi/constants package
483
enum RENDERER_TYPE {
484
UNKNOWN = 0,
485
WEBGL = 1,
486
CANVAS = 2
487
}
488
489
enum BLEND_MODES {
490
NORMAL = 0,
491
ADD = 1,
492
MULTIPLY = 2,
493
SCREEN = 3,
494
// ... additional blend modes
495
}
496
497
enum SCALE_MODES {
498
NEAREST = 0,
499
LINEAR = 1
500
}
501
502
enum MSAA_QUALITY {
503
NONE = 0,
504
LOW = 2,
505
MEDIUM = 4,
506
HIGH = 8
507
}
508
509
enum MIPMAP_MODES {
510
OFF = 0,
511
POW2 = 1,
512
ON = 2,
513
ON_MANUAL = 3
514
}
515
516
enum WRAP_MODES {
517
CLAMP = 33071,
518
REPEAT = 10497,
519
MIRRORED_REPEAT = 33648
520
}
521
522
enum FORMATS {
523
RGBA = 6408,
524
RGB = 6407,
525
ALPHA = 6406,
526
LUMINANCE = 6409,
527
LUMINANCE_ALPHA = 6410
528
}
529
530
enum TYPES {
531
UNSIGNED_BYTE = 5121,
532
UNSIGNED_SHORT = 5123,
533
UNSIGNED_SHORT_5_6_5 = 33635,
534
UNSIGNED_SHORT_4_4_4_4 = 32819,
535
UNSIGNED_SHORT_5_5_5_1 = 32820,
536
FLOAT = 5126
537
}
538
539
enum TARGETS {
540
TEXTURE_2D = 3553,
541
TEXTURE_CUBE_MAP = 34067,
542
TEXTURE_2D_ARRAY = 35866,
543
TEXTURE_CUBE_MAP_POSITIVE_X = 34069
544
}
545
546
enum ALPHA_MODES {
547
NPM = 0,
548
UNPACK = 1,
549
PMA = 2,
550
NO_PREMULTIPLIED_ALPHA = 0,
551
PREMULTIPLY_ON_UPLOAD = 1,
552
PREMULTIPLIED_ALPHA = 2
553
}
554
```