0
# Framebuffers
1

2
Off-screen rendering capabilities with render textures and framebuffer management. The framebuffer system enables rendering to textures for post-processing effects, texture atlases, and advanced rendering techniques.
3

4
## Capabilities
5

6
### Framebuffer
7

8
Core framebuffer class that manages WebGL framebuffer objects for off-screen rendering.
9

10
```typescript { .api }
11
/**
12
 * Framebuffer manages WebGL framebuffer objects for off-screen rendering
13
 * Handles color and depth attachments for render-to-texture operations
14
 */
15
class Framebuffer {
16
  /** Framebuffer width in pixels */
17
  width: number;
18
  /** Framebuffer height in pixels */
19
  height: number;
20
  /** Multisampling quality level */
21
  multisample: MSAA_QUALITY;
22
  /** Whether stencil buffer is enabled */
23
  stencil: boolean;
24
  /** Whether depth buffer is enabled */
25
  depth: boolean;
26
  /** Depth texture attachment */
27
  depthTexture: BaseTexture;
28
  /** Color texture attachments */
29
  colorTextures: BaseTexture[];
30
  /** WebGL framebuffer objects cache */
31
  glFramebuffers: {[key: number]: GLFramebuffer};
32
  /** Dispose runner for cleanup */
33
  disposeRunner: Runner;
34

35
  /**
36
   * Create a new Framebuffer
37
   * @param width - Framebuffer width
38
   * @param height - Framebuffer height
39
   */
40
  constructor(width: number, height: number);
41

42
  /**
43
   * Add color texture attachment
44
   * @param index - Attachment index (0-7)
45
   * @param texture - BaseTexture to attach (auto-created if not provided)
46
   */
47
  addColorTexture(index?: number, texture?: BaseTexture<Resource>): this;
48

49
  /**
50
   * Add depth texture attachment
51
   * @param texture - Depth texture (auto-created if not provided)
52
   */
53
  addDepthTexture(texture?: BaseTexture<Resource>): this;
54

55
  /** Enable depth and stencil buffer */
56
  enableDepth(): this;
57

58
  /** Enable stencil buffer */
59
  enableStencil(): this;
60

61
  /**
62
   * Resize framebuffer and all attachments
63
   * @param width - New width
64
   * @param height - New height
65
   */
66
  resize(width: number, height: number): void;
67

68
  /** Dispose of WebGL resources */
69
  dispose(): void;
70

71
  /** Destroy framebuffer and cleanup resources */
72
  destroy(): void;
73

74
  /**
75
   * Get color texture at index
76
   * @param index - Attachment index
77
   */
78
  getColorTexture(index?: number): BaseTexture;
79
}
80
```
81

82
### GLFramebuffer
83

84
WebGL-specific framebuffer wrapper that manages GPU framebuffer objects.
85

86
```typescript { .api }
87
/**
88
 * GLFramebuffer wraps WebGL framebuffer objects
89
 * Manages GPU framebuffer state and attachments  
90
 */
91
class GLFramebuffer {
92
  /** WebGL framebuffer object */
93
  framebuffer: WebGLFramebuffer;
94
  /** Stencil attachment */
95
  stencil: WebGLRenderbuffer;
96
  /** Multisampled framebuffer */
97
  multisample: MSAA_QUALITY;
98
  /** MSAA render buffer */
99
  msaaBuffer: WebGLRenderbuffer;
100
  /** Blit framebuffer for MSAA resolve */
101
  blitFramebuffer: WebGLFramebuffer;
102
  /** Dirty ID for cache invalidation */
103
  dirtyId: number;
104
  /** Dirty format ID */
105
  dirtyFormat: number;
106
  /** Dirty size ID */
107
  dirtySize: number;
108

109
  /**
110
   * Create GLFramebuffer from Framebuffer
111
   * @param framebuffer - Source framebuffer  
112
   */
113
  constructor(framebuffer: Framebuffer);
114
}
115
```
116

117
### RenderTexture
118

119
Texture that can be rendered to, extending the base Texture class with framebuffer capabilities.
120

121
```typescript { .api }
122
/**
123
 * RenderTexture is a texture that can be rendered to
124
 * Combines texture and framebuffer for render-to-texture operations
125
 */
126
class RenderTexture extends Texture {
127
  /** Base render texture containing framebuffer */
128
  baseRenderTexture: BaseRenderTexture;
129
  /** Filter pool key for texture reuse */
130
  filterPoolKey: string | number | null;
131

132
  /**
133
   * Create a new RenderTexture
134
   * @param baseRenderTexture - Base render texture
135
   * @param frame - Texture frame
136
   */
137
  constructor(baseRenderTexture: BaseRenderTexture, frame?: Rectangle);
138

139
  /**
140
   * Resize render texture
141
   * @param desiredWidth - Target width
142
   * @param desiredHeight - Target height  
143
   * @param resizeBaseTexture - Also resize base texture
144
   */
145
  resize(desiredWidth: number, desiredHeight: number, resizeBaseTexture?: boolean): void;
146

147
  /**
148
   * Set the frame for this render texture
149
   * @param frame - New frame rectangle
150
   */
151
  setFrame(frame: Rectangle): void;
152

153
  /**
154
   * Create render texture with options
155
   * @param options - Creation options
156
   */
157
  static create(options: IBaseRenderTextureOptions): RenderTexture;
158
}
159
```
160

161
### BaseRenderTexture
162

163
Base render texture that manages the framebuffer and provides render-to-texture functionality.
164

165
```typescript { .api }
166
/**
167
 * BaseRenderTexture manages framebuffer for render-to-texture
168
 * Extends BaseTexture with framebuffer rendering capabilities
169
 */
170
class BaseRenderTexture extends BaseTexture {
171
  /** Framebuffer for rendering */
172
  framebuffer: Framebuffer;
173
  /** Filter pool key */
174
  filterPoolKey: string | number | null;
175

176
  /**
177
   * Create a new BaseRenderTexture
178
   * @param options - Creation options
179
   */
180
  constructor(options?: IBaseRenderTextureOptions);
181

182
  /**
183
   * Resize render texture and framebuffer
184
   * @param desiredWidth - Target width
185
   * @param desiredHeight - Target height
186
   */
187
  resize(desiredWidth: number, desiredHeight: number): void;
188

189
  /** Dispose of framebuffer resources */
190
  dispose(): void;
191

192
  /** Destroy render texture */
193
  destroy(): void;
194
}
195

196
interface IBaseRenderTextureOptions extends IBaseTextureOptions {
197
  /** Framebuffer width */
198
  width?: number;
199
  /** Framebuffer height */  
200
  height?: number;
201
  /** Multisampling level */
202
  multisample?: MSAA_QUALITY;
203
}
204
```
205

206
### RenderTexturePool
207

208
Pool for efficient reuse of render textures to minimize allocation overhead.
209

210
```typescript { .api }
211
/**
212
 * RenderTexturePool manages render texture reuse
213
 * Minimizes allocation overhead for temporary render textures
214
 */
215
class RenderTexturePool {
216
  /** Texture pool organized by key */
217
  texturePool: {[key: string | number]: RenderTexture[]};
218
  /** Options for pooled textures */
219
  textureOptions: IBaseRenderTextureOptions;
220
  /** Enable/disable the pool */
221
  enableFullScreen: boolean;
222

223
  /**
224
   * Create a new RenderTexturePool
225
   * @param textureOptions - Default options for pooled textures
226
   */
227
  constructor(textureOptions?: IBaseRenderTextureOptions);
228

229
  /**
230
   * Create key for texture pool lookup
231
   * @param pixelWidth - Width in pixels
232
   * @param pixelHeight - Height in pixels
233
   * @param multisample - MSAA level
234
   */
235
  createKey(pixelWidth: number, pixelHeight: number, multisample: MSAA_QUALITY): string;
236

237
  /**
238
   * Get render texture from pool
239
   * @param resolution - Texture resolution
240
   * @param width - Texture width
241
   * @param height - Texture height
242
   * @param multisample - MSAA level
243
   */
244
  getOptimalTexture(resolution: number, width: number, height: number, multisample?: MSAA_QUALITY): RenderTexture;
245

246
  /**
247
   * Get filter texture from pool
248
   * @param resolution - Texture resolution
249
   * @param multisample - MSAA level
250
   */
251
  getFilterTexture(resolution: number, multisample?: MSAA_QUALITY): RenderTexture;
252

253
  /**
254
   * Return texture to pool
255
   * @param renderTexture - Texture to return
256
   */
257
  returnTexture(renderTexture: RenderTexture): void;
258

259
  /**
260
   * Return filter texture to pool
261
   * @param renderTexture - Filter texture to return
262
   */
263
  returnFilterTexture(renderTexture: RenderTexture): void;
264

265
  /** Clear the texture pool */
266
  clear(destroyTextures?: boolean): void;
267

268
  /**
269
   * Set screen size for full-screen textures
270
   * @param size - Screen dimensions
271
   */
272
  setScreenSize(size: ISize): void;
273
}
274
```
275

276
**Usage Examples:**
277

278
```typescript
279
import { Framebuffer, RenderTexture, BaseRenderTexture } from "@pixi/core";
280

281
// Create basic framebuffer
282
const framebuffer = new Framebuffer(256, 256);
283
framebuffer.addColorTexture(); // Auto-creates color attachment
284
framebuffer.enableDepth();     // Add depth buffer
285

286
// Create render texture
287
const renderTexture = RenderTexture.create({
288
  width: 512,
289
  height: 512,
290
  scaleMode: SCALE_MODES.LINEAR,
291
  resolution: 1
292
});
293

294
// Render to texture
295
renderer.render(mySprite, {
296
  renderTexture: renderTexture,
297
  clear: true
298
});
299

300
// Use rendered texture
301
const sprite = new Sprite(renderTexture);
302

303
// Multi-target rendering (MRT)
304
const multiTargetFramebuffer = new Framebuffer(256, 256);
305
multiTargetFramebuffer.addColorTexture(0); // Color attachment 0
306
multiTargetFramebuffer.addColorTexture(1); // Color attachment 1
307
multiTargetFramebuffer.addDepthTexture();  // Depth attachment
308

309
// High-quality render texture with MSAA
310
const hqRenderTexture = RenderTexture.create({
311
  width: 1024,
312
  height: 1024,
313
  multisample: MSAA_QUALITY.HIGH,
314
  resolution: 2
315
});
316

317
// Render texture pool usage
318
const pool = new RenderTexturePool();
319
const pooledTexture = pool.getOptimalTexture(1, 256, 256, MSAA_QUALITY.MEDIUM);
320

321
// Use pooled texture
322
renderer.render(scene, {
323
  renderTexture: pooledTexture,
324
  clear: true
325
});
326

327
// Return to pool when done
328
pool.returnTexture(pooledTexture);
329

330
// Filter texture from pool
331
const filterTexture = pool.getFilterTexture(1, MSAA_QUALITY.LOW);
332
// ... use for filtering ...
333
pool.returnFilterTexture(filterTexture);
334

335
// Render-to-texture pipeline
336
function createMipmappedTexture(sprite) {
337
  const baseSize = 512;
338
  const levels = [];
339
  
340
  for (let i = 0; i < 4; i++) {
341
    const size = baseSize >> i;
342
    const mipTexture = RenderTexture.create({
343
      width: size,
344
      height: size,
345
      scaleMode: SCALE_MODES.LINEAR
346
    });
347
    
348
    // Render previous level or original sprite
349
    const source = i === 0 ? sprite : levels[i - 1];
350
    renderer.render(source, {
351
      renderTexture: mipTexture,
352
      clear: true
353
    });
354
    
355
    levels.push(mipTexture);
356
  }
357
  
358
  return levels;
359
}
360

361
// Off-screen composition
362
const compositeTexture = RenderTexture.create({ width: 800, height: 600 });
363

364
// Render background
365
renderer.render(background, {
366
  renderTexture: compositeTexture,
367
  clear: true
368
});
369

370
// Render foreground with blend mode
371
foreground.blendMode = BLEND_MODES.ADD;
372
renderer.render(foreground, {
373
  renderTexture: compositeTexture,
374
  clear: false
375
});
376

377
// Use composite result
378
const finalSprite = new Sprite(compositeTexture);
379

380
// Resize render texture
381
renderTexture.resize(1024, 768);
382

383
// Custom framebuffer setup
384
const customFramebuffer = new Framebuffer(256, 256);
385
const colorTexture = new BaseTexture(null, {
386
  format: FORMATS.RGBA,
387
  type: TYPES.UNSIGNED_BYTE,
388
  width: 256,
389
  height: 256
390
});
391
customFramebuffer.addColorTexture(0, colorTexture);
392
```
393

394
## Types
395

396
```typescript { .api }
397
enum MSAA_QUALITY {
398
  NONE = 0,
399
  LOW = 2,  
400
  MEDIUM = 4,
401
  HIGH = 8
402
}
403

404
interface IBaseRenderTextureOptions extends IBaseTextureOptions {
405
  width?: number;
406
  height?: number;
407
  multisample?: MSAA_QUALITY;
408
}
409

410
interface ISize {
411
  width: number;
412
  height: number;
413
}
414
```