0
# Rendering
1

2
Core rendering functionality providing WebGL context management, render loops, and automatic renderer detection. The rendering system is the foundation of @pixi/core, handling the WebGL pipeline and providing fallback to Canvas when needed.
3

4
## Capabilities
5

6
### AbstractRenderer
7

8
Abstract base class that defines the common interface for all renderers, providing basic functionality like canvas management, resolution handling, and plugin support.
9

10
```typescript { .api }
11
/**
12
 * Abstract base class for renderers extending EventEmitter
13
 * Provides common functionality for WebGL and Canvas renderers
14
 */
15
abstract class AbstractRenderer extends EventEmitter {
16
  /** The resolution/device pixel ratio of the renderer */
17
  resolution: number;
18
  /** Whether to clear the canvas before rendering */
19
  clearBeforeRender?: boolean;
20
  /** Renderer configuration options */
21
  options: IRendererOptions;
22
  /** The renderer type (WEBGL or CANVAS) */
23
  type: RENDERER_TYPE;
24
  /** Screen dimensions as Rectangle */
25
  screen: Rectangle;
26
  /** The HTML canvas element */
27
  view: HTMLCanvasElement;
28
  /** Collection of renderer plugins */
29
  plugins: IRendererPlugins;
30
  /** Context alpha setting */
31
  useContextAlpha: boolean | 'notMultiplied';
32
  /** Auto-resize CSS dimensions flag */
33
  autoDensity: boolean;
34
  /** Preserve drawing buffer flag for screenshots */
35
  preserveDrawingBuffer: boolean;
36
  /** Background color as hex number */
37
  backgroundColor: number;
38
  /** Background alpha transparency (0-1) */
39
  backgroundAlpha: number;
40

41
  /**
42
   * Create a new AbstractRenderer
43
   * @param type - The renderer type
44
   * @param options - Renderer configuration options
45
   */
46
  constructor(type: RENDERER_TYPE, options?: IRendererOptions);
47

48
  /** Initialize plugins from static map */
49
  initPlugins(staticMap: IRendererPlugins): void;
50
  
51
  /** 
52
   * Resize the renderer and canvas 
53
   * @param desiredScreenWidth - Target width
54
   * @param desiredScreenHeight - Target height
55
   */
56
  resize(desiredScreenWidth: number, desiredScreenHeight: number): void;
57
  
58
  /**
59
   * Generate a texture from a display object
60
   * @param displayObject - Object to render to texture
61
   * @param options - Generation options
62
   */
63
  generateTexture(displayObject: IRenderableObject, options?: IGenerateTextureOptions): RenderTexture;
64
  
65
  /**
66
   * Destroy the renderer and cleanup resources
67
   * @param removeView - Remove canvas from DOM
68
   */
69
  destroy(removeView?: boolean): void;
70

71
  /** Abstract: Add a system to the renderer */
72
  abstract addSystem(ClassRef: ISystemConstructor, name: string): this;
73
  
74
  /** Abstract: Render a display object */
75
  abstract render(displayObject: IRenderableObject, options?: IRendererRenderOptions): void;
76
}
77

78
interface IRendererOptions {
79
  /** Canvas element to render to */
80
  view?: HTMLCanvasElement;
81
  /** Device pixel ratio */
82
  resolution?: number;
83
  /** Auto-resize canvas CSS */
84
  autoDensity?: boolean;
85
  /** Background color (hex) */
86
  backgroundColor?: number;
87
  /** Background alpha (0-1) */
88
  backgroundAlpha?: number;
89
  /** Clear before rendering */
90
  clearBeforeRender?: boolean;
91
  /** WebGL preserve drawing buffer */
92
  preserveDrawingBuffer?: boolean;
93
  /** Canvas width */
94
  width?: number;
95
  /** Canvas height */
96
  height?: number;
97
  /** Enable antialiasing */
98
  antialias?: boolean;
99
}
100

101
interface IRendererPlugins {
102
  [key: string]: any;
103
}
104

105
interface IRendererRenderOptions {
106
  /** Render texture to render to */
107
  renderTexture?: RenderTexture;
108
  /** Clear before rendering */
109
  clear?: boolean;
110
  /** Transform matrix to apply */
111
  transform?: Matrix;
112
  /** Skip updating transforms */
113
  skipUpdateTransform?: boolean;
114
}
115

116
interface IGenerateTextureOptions {
117
  /** Texture scale mode */
118
  scaleMode?: SCALE_MODES;
119
  /** Resolution for generated texture */
120
  resolution?: number;
121
  /** Region to capture */
122
  region?: Rectangle;
123
  /** Multisampling level */
124
  multisample?: MSAA_QUALITY;
125
}
126
```
127

128
### Renderer
129

130
WebGL-specific renderer implementation that extends AbstractRenderer with full WebGL rendering capabilities and system management.
131

132
```typescript { .api }
133
/**
134
 * WebGL renderer providing hardware-accelerated 2D rendering
135
 * Manages WebGL context, systems, and rendering pipeline
136
 */
137
class Renderer extends AbstractRenderer {
138
  /** WebGL rendering context */
139
  gl: IRenderingContext;
140
  /** Global shader uniforms */
141
  globalUniforms: UniformGroup;
142
  /** Unique WebGL context identifier */
143
  CONTEXT_UID: number;
144
  /** Flag indicating if rendering to screen */
145
  renderingToScreen: boolean;
146
  /** MSAA quality level */
147
  multisample: MSAA_QUALITY;
148
  /** Event runners for system communication */
149
  runners: {[key: string]: Runner};
150

151
  // Rendering systems (available as properties)
152
  /** Mask rendering system */
153
  mask: MaskSystem;
154
  /** WebGL context management system */
155
  context: ContextSystem;
156
  /** WebGL state management system */
157
  state: StateSystem;
158
  /** Shader compilation and management system */
159
  shader: ShaderSystem;
160
  /** Texture management system */
161
  texture: TextureSystem;
162
  /** Buffer management system */
163
  buffer: BufferSystem;
164
  /** Geometry rendering system */
165
  geometry: GeometrySystem;
166
  /** Framebuffer management system */
167
  framebuffer: FramebufferSystem;
168
  /** Scissor testing system */
169
  scissor: ScissorSystem;
170
  /** Stencil testing system */
171
  stencil: StencilSystem;
172
  /** Projection matrix system */
173
  projection: ProjectionSystem;
174
  /** Texture garbage collection system */
175
  textureGC: TextureGCSystem;
176
  /** Filter rendering system */
177
  filter: FilterSystem;
178
  /** Render texture system */
179
  renderTexture: RenderTextureSystem;
180
  /** Batch rendering system */
181
  batch: BatchSystem;
182

183
  /**
184
   * Create a new WebGL Renderer
185
   * @param options - Renderer configuration
186
   */
187
  constructor(options?: IRendererOptions);
188

189
  /**
190
   * Create renderer with WebGL support detection
191
   * @param options - Renderer options
192
   */
193
  static create(options?: IRendererOptions): AbstractRenderer;
194

195
  /**
196
   * Add a system to the renderer
197
   * @param ClassRef - System constructor
198
   * @param name - System name for access
199
   */
200
  addSystem(ClassRef: ISystemConstructor, name: string): this;
201

202
  /**
203
   * Render a display object to the canvas or render texture
204
   * @param displayObject - Object to render
205
   * @param options - Render options
206
   */
207
  render(displayObject: IRenderableObject, options?: IRendererRenderOptions): void;
208

209
  /**
210
   * Resize renderer and update systems
211
   * @param desiredScreenWidth - Target width
212
   * @param desiredScreenHeight - Target height  
213
   */
214
  resize(desiredScreenWidth: number, desiredScreenHeight: number): void;
215

216
  /** Reset WebGL state to defaults */
217
  reset(): this;
218

219
  /** Clear the frame buffer */
220
  clear(): void;
221

222
  /**
223
   * Destroy renderer and cleanup all resources
224
   * @param removeView - Remove canvas from DOM
225
   */
226
  destroy(removeView?: boolean): void;
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
import { Renderer } from "@pixi/core";
234

235
// Create WebGL renderer with options
236
const renderer = new Renderer({
237
  width: 800,
238
  height: 600,
239
  backgroundColor: 0x1099bb,
240
  resolution: window.devicePixelRatio,
241
  antialias: true
242
});
243

244
document.body.appendChild(renderer.view);
245

246
// Access rendering systems
247
console.log(renderer.gl); // WebGL context
248
renderer.state.setState(new State()); // Set WebGL state
249
renderer.clear(); // Clear framebuffer
250

251
// Render a display object
252
renderer.render(myDisplayObject);
253

254
// Resize renderer
255
renderer.resize(1024, 768);
256
```
257

258
### autoDetectRenderer
259

260
Utility function that automatically detects WebGL support and creates the appropriate renderer, falling back to Canvas if WebGL is unavailable.
261

262
```typescript { .api }
263
/**
264
 * Automatically detects and creates the best available renderer
265
 * Falls back to Canvas renderer if WebGL is not supported
266
 * @param options - Renderer configuration options
267
 * @returns AbstractRenderer instance (Renderer or CanvasRenderer)
268
 */
269
function autoDetectRenderer(options?: IRendererOptionsAuto): AbstractRenderer;
270

271
interface IRendererOptionsAuto extends IRendererOptions {
272
  /** Force canvas renderer even if WebGL is available */
273
  forceCanvas?: boolean;
274
}
275
```
276

277
**Usage Examples:**
278

279
```typescript
280
import { autoDetectRenderer } from "@pixi/core";
281

282
// Auto-detect best renderer
283
const renderer = autoDetectRenderer({
284
  width: 800,
285
  height: 600,
286
  backgroundColor: 0x1099bb
287
});
288

289
// Force Canvas renderer
290
const canvasRenderer = autoDetectRenderer({
291
  width: 800,
292
  height: 600,
293
  forceCanvas: true
294
});
295

296
// Check renderer type
297
if (renderer.type === RENDERER_TYPE.WEBGL) {
298
  console.log("Using WebGL renderer");
299
} else {
300
  console.log("Using Canvas renderer");
301
}
302
```
303

304
## Types
305

306
```typescript { .api }
307
interface ISystemConstructor<R = Renderer> {
308
  new (renderer: R): ISystem;
309
}
310

311
interface IRenderableObject {
312
  parent: IRenderableContainer;
313
  enableTempParent(): IRenderableContainer;
314
  updateTransform(): void;
315
  disableTempParent(parent: IRenderableContainer): void;
316
  render(renderer: Renderer): void;
317
}
318

319
interface IRenderingContext extends WebGL2RenderingContext {}
320

321
enum RENDERER_TYPE {
322
  UNKNOWN = 0,
323
  WEBGL = 1,
324
  CANVAS = 2
325
}
326

327
enum MSAA_QUALITY {
328
  NONE = 0,
329
  LOW = 2,
330
  MEDIUM = 4,
331
  HIGH = 8
332
}
333
```