0
# Textures and Materials
1

2
Texture creation, management, and manipulation including texture sources, render textures, texture atlases, and texture optimization. Textures are the foundation for all visual content in PixiJS, providing efficient GPU-based image rendering.
3

4
## Capabilities
5

6
### Texture Class
7

8
Core texture class representing a rectangular area of a texture source.
9

10
```typescript { .api }
11
/**
12
 * Texture representing a rectangular area of a texture source
13
 */
14
class Texture {
15
  constructor(options?: TextureOptions);
16
  
17
  /** Texture source containing the actual image data */
18
  readonly source: TextureSource;
19
  
20
  /** Rectangle defining the area of the source to use */
21
  frame: Rectangle;
22
  
23
  /** Original texture frame before any transformations */
24
  orig: Rectangle;
25
  
26
  /** Trim rectangle for removing transparent pixels */
27
  trim: Rectangle;
28
  
29
  /** Rotation of texture (0, 90, 180, 270 degrees) */
30
  rotate: number;
31
  
32
  /** Default anchor point */
33
  defaultAnchor: Point;
34
  
35
  /** Default borders for 9-slice */
36
  defaultBorders: Rectangle;
37
  
38
  /** Texture label for debugging */
39
  label: string;
40
  
41
  /** Update ID for change detection */
42
  readonly updateId: number;
43
  
44
  /** Texture width */
45
  readonly width: number;
46
  
47
  /** Texture height */
48
  readonly height: number;
49
  
50
  /** Texture resolution */
51
  readonly resolution: number;
52
  
53
  /** Base texture width */
54
  readonly baseWidth: number;
55
  
56
  /** Base texture height */
57
  readonly baseHeight: number;
58
  
59
  /**
60
   * Update texture uvs based on frame
61
   */
62
  updateUvs(): void;
63
  
64
  /**
65
   * Destroy texture and clean up resources
66
   * @param destroySource - Also destroy the texture source
67
   */
68
  destroy(destroySource?: boolean): void;
69
  
70
  /**
71
   * Clone texture
72
   * @returns New texture with same source
73
   */
74
  clone(): Texture;
75
  
76
  /**
77
   * Create texture from various sources
78
   * @param source - Source to create texture from
79
   * @param options - Creation options
80
   * @returns New texture
81
   */
82
  static from(source: TextureSourceLike, options?: TextureOptions): Texture;
83
  
84
  /**
85
   * Create texture from URL
86
   * @param url - Image URL
87
   * @param options - Creation options
88
   * @returns Promise resolving to texture
89
   */
90
  static fromURL(url: string, options?: TextureOptions): Promise<Texture>;
91
  
92
  /**
93
   * Create texture from buffer
94
   * @param buffer - Image buffer data
95
   * @param width - Buffer width
96
   * @param height - Buffer height
97
   * @param options - Creation options
98
   * @returns New texture
99
   */
100
  static fromBuffer(buffer: TypedArray, width: number, height: number, options?: TextureOptions): Texture;
101
  
102
  /** Empty 1x1 white texture */
103
  static readonly EMPTY: Texture;
104
  
105
  /** 1x1 white texture */
106
  static readonly WHITE: Texture;
107
}
108

109
interface TextureOptions {
110
  /** Texture source */
111
  source?: TextureSource;
112
  
113
  /** Texture label */
114
  label?: string;
115
  
116
  /** Source frame rectangle */
117
  frame?: Rectangle;
118
  
119
  /** Original frame rectangle */
120
  orig?: Rectangle;
121
  
122
  /** Trim rectangle */
123
  trim?: Rectangle;
124
  
125
  /** Default anchor */
126
  defaultAnchor?: PointData;
127
  
128
  /** Default borders */
129
  defaultBorders?: Rectangle;
130
  
131
  /** Rotation */
132
  rotate?: number;
133
}
134

135
type TextureSourceLike = 
136
  | string 
137
  | HTMLImageElement 
138
  | HTMLCanvasElement 
139
  | HTMLVideoElement 
140
  | ImageBitmap 
141
  | OffscreenCanvas 
142
  | VideoFrame 
143
  | TextureSource;
144
```
145

146
### Texture Sources
147

148
Various texture source types for different image data formats.
149

150
```typescript { .api }
151
/**
152
 * Base texture source class
153
 */
154
abstract class TextureSource {
155
  constructor(options?: TextureSourceOptions);
156
  
157
  /** Source label */
158
  label: string;
159
  
160
  /** Source resource */
161
  resource: any;
162
  
163
  /** Source width */
164
  width: number;
165
  
166
  /** Source height */
167
  height: number;
168
  
169
  /** Source resolution */
170
  resolution: number;
171
  
172
  /** Source format */
173
  format: FORMATS;
174
  
175
  /** Source type */
176
  type: TYPES;
177
  
178
  /** Alpha mode */
179
  alphaMode: ALPHA_MODES;
180
  
181
  /** Mipmap mode */
182
  mipmap: MIPMAP_MODES;
183
  
184
  /** Wrap mode */
185
  wrapMode: WRAP_MODES;
186
  
187
  /** Scale mode */
188
  scaleMode: SCALE_MODES;
189
  
190
  /** Upload ID for change tracking */
191
  readonly uploadId: number;
192
  
193
  /** Destroyed flag */
194
  destroyed: boolean;
195
  
196
  /**
197
   * Update source
198
   */
199
  update(): void;
200
  
201
  /**
202
   * Destroy source
203
   */
204
  destroy(): void;
205
  
206
  /**
207
   * Resize source
208
   * @param width - New width
209
   * @param height - New height
210
   * @param resolution - New resolution
211
   */
212
  resize(width: number, height: number, resolution?: number): void;
213
}
214

215
/**
216
 * Image-based texture source
217
 */
218
class ImageSource extends TextureSource {
219
  constructor(options?: ImageSourceOptions);
220
  
221
  /** Image element or data */
222
  resource: HTMLImageElement | ImageBitmap;
223
  
224
  /** Auto garbage collection */
225
  autoGarbageCollect: boolean;
226
  
227
  /**
228
   * Create from URL
229
   * @param url - Image URL
230
   * @param options - Source options
231
   * @returns Promise resolving to image source
232
   */
233
  static fromUrl(url: string, options?: ImageSourceOptions): Promise<ImageSource>;
234
  
235
  /**
236
   * Test if source can be created from input
237
   * @param source - Source to test
238
   * @returns True if compatible
239
   */
240
  static test(source: any): boolean;
241
}
242

243
/**
244
 * Canvas-based texture source
245
 */
246
class CanvasSource extends TextureSource {
247
  constructor(options?: CanvasSourceOptions);
248
  
249
  /** Canvas element */
250
  resource: HTMLCanvasElement | OffscreenCanvas;
251
  
252
  /**
253
   * Test if source can be created from canvas
254
   * @param source - Source to test
255
   * @returns True if canvas
256
   */
257
  static test(source: any): boolean;
258
}
259

260
/**
261
 * Video-based texture source
262
 */
263
class VideoSource extends TextureSource {
264
  constructor(options?: VideoSourceOptions);
265
  
266
  /** Video element */
267
  resource: HTMLVideoElement;
268
  
269
  /** Auto update flag */
270
  autoUpdate: boolean;
271
  
272
  /** Update FPS */
273
  updateFPS: number;
274
  
275
  /**
276
   * Test if source can be created from video
277
   * @param source - Source to test
278
   * @returns True if video
279
   */
280
  static test(source: any): boolean;
281
}
282

283
/**
284
 * Buffer-based texture source
285
 */
286
class BufferImageSource extends TextureSource {
287
  constructor(options?: BufferImageSourceOptions);
288
  
289
  /** Image buffer data */
290
  resource: TypedArray;
291
  
292
  /**
293
   * Test if source can be created from buffer
294
   * @param source - Source to test
295
   * @returns True if buffer
296
   */
297
  static test(source: any): boolean;
298
}
299

300
/**
301
 * Compressed texture source
302
 */
303
class CompressedSource extends TextureSource {
304
  constructor(options?: CompressedSourceOptions);
305
  
306
  /** Compressed data */
307
  resource: CompressedTextureResource;
308
  
309
  /** Number of levels */
310
  levels: number;
311
  
312
  /** Internal format */
313
  internalFormat: number;
314
}
315
```
316

317
### Render Textures
318

319
Textures that can be rendered to, useful for dynamic content and post-processing.
320

321
```typescript { .api }
322
/**
323
 * Texture that can be rendered to
324
 */
325
class RenderTexture extends Texture {
326
  constructor(options?: RenderTextureOptions);
327
  
328
  /** Base render texture */
329
  baseTexture: RenderTexture;
330
  
331
  /** Framebuffer for rendering */
332
  framebuffer: Framebuffer;
333
  
334
  /** Multisample level */
335
  multisample: MSAA_QUALITY;
336
  
337
  /**
338
   * Resize render texture
339
   * @param width - New width
340
   * @param height - New height
341
   * @param resolution - New resolution
342
   */
343
  resize(width: number, height: number, resolution?: number): void;
344
  
345
  /**
346
   * Set real size
347
   * @param realWidth - Real width
348
   * @param realHeight - Real height
349
   * @param resolution - Resolution
350
   */
351
  setRealSize(realWidth: number, realHeight: number, resolution?: number): void;
352
  
353
  /**
354
   * Create render texture
355
   * @param options - Creation options
356
   * @returns New render texture
357
   */
358
  static create(options?: RenderTextureOptions): RenderTexture;
359
}
360

361
interface RenderTextureOptions {
362
  /** Texture width */
363
  width?: number;
364
  
365
  /** Texture height */
366
  height?: number;
367
  
368
  /** Texture resolution */
369
  resolution?: number;
370
  
371
  /** Scale mode */
372
  scaleMode?: SCALE_MODES;
373
  
374
  /** Multisample quality */
375
  multisample?: MSAA_QUALITY;
376
}
377
```
378

379
### Texture Style
380

381
Style configuration for texture sampling and filtering.
382

383
```typescript { .api }
384
/**
385
 * Texture style for sampling configuration
386
 */
387
class TextureStyle {
388
  constructor(options?: TextureStyleOptions);
389
  
390
  /** Scale mode for magnification */
391
  scaleMode: SCALE_MODES;
392
  
393
  /** Address mode for U coordinate */
394
  addressModeU: ADDRESS_MODES;
395
  
396
  /** Address mode for V coordinate */
397
  addressModeV: ADDRESS_MODES;
398
  
399
  /** Address mode for W coordinate */
400
  addressModeW: ADDRESS_MODES;
401
  
402
  /** Magnification filter */
403
  magFilter: SCALE_MODES;
404
  
405
  /** Minification filter */
406
  minFilter: SCALE_MODES;
407
  
408
  /** Mipmap filter */
409
  mipmapFilter: MIPMAP_MODES;
410
  
411
  /** Anisotropic filtering level */
412
  maxAnisotropy: number;
413
  
414
  /**
415
   * Clone style
416
   * @returns New texture style
417
   */
418
  clone(): TextureStyle;
419
}
420

421
interface TextureStyleOptions {
422
  scaleMode?: SCALE_MODES;
423
  addressModeU?: ADDRESS_MODES;
424
  addressModeV?: ADDRESS_MODES;
425
  addressModeW?: ADDRESS_MODES;
426
  magFilter?: SCALE_MODES;
427
  minFilter?: SCALE_MODES;
428
  mipmapFilter?: MIPMAP_MODES;
429
  maxAnisotropy?: number;
430
}
431
```
432

433
### Texture Matrix
434

435
Matrix for texture coordinate transformations.
436

437
```typescript { .api }
438
/**
439
 * Matrix for texture coordinate transformations
440
 */
441
class TextureMatrix {
442
  constructor(texture?: Texture, clampMargin?: number);
443
  
444
  /** Transformation matrix */
445
  matrix: Matrix;
446
  
447
  /** UV matrix */
448
  uClampFrame: Float32Array;
449
  
450
  /** UV clamping */
451
  uClampOffset: Float32Array;
452
  
453
  /** Associated texture */
454
  texture: Texture;
455
  
456
  /** Clamp margin */
457
  clampMargin: number;
458
  
459
  /** Offset for clamping */
460
  clampOffset: number;
461
  
462
  /**
463
   * Update matrix based on texture
464
   * @param forceUpdate - Force update even if not changed
465
   */
466
  update(forceUpdate?: boolean): boolean;
467
  
468
  /**
469
   * Multiply with another matrix
470
   * @param matrix - Matrix to multiply
471
   * @param out - Output texture matrix
472
   * @returns Result matrix
473
   */
474
  multiplyUvs(matrix: Matrix, out?: Float32Array): Float32Array;
475
}
476
```
477

478
### Texture Pool
479

480
Texture pooling system for efficient memory management.
481

482
```typescript { .api }
483
/**
484
 * Texture pool for memory management
485
 */
486
class TexturePool {
487
  constructor();
488
  
489
  /** Pool of textures by key */
490
  texturePool: Record<string, Texture[]>;
491
  
492
  /** Pool options by key */
493
  textureOptions: Record<string, any>;
494
  
495
  /**
496
   * Get pooled texture
497
   * @param key - Pool key
498
   * @param ...args - Creation arguments
499
   * @returns Pooled texture
500
   */
501
  getOptimalTexture(key: string, ...args: any[]): Texture;
502
  
503
  /**
504
   * Return texture to pool
505
   * @param key - Pool key
506
   * @param texture - Texture to return
507
   */
508
  returnTexture(key: string, texture: Texture): void;
509
  
510
  /**
511
   * Clear pool
512
   * @param destroyTextures - Destroy textures
513
   */
514
  clear(destroyTextures?: boolean): void;
515
}
516
```
517

518
### Constants and Enums
519

520
Texture-related constants and enumerations.
521

522
```typescript { .api }
523
/**
524
 * Scale modes for texture filtering
525
 */
526
enum SCALE_MODES {
527
  NEAREST = 0,
528
  LINEAR = 1
529
}
530

531
/**
532
 * Wrap modes for texture addressing
533
 */
534
enum WRAP_MODES {
535
  CLAMP = 0,
536
  REPEAT = 1,
537
  MIRRORED_REPEAT = 2
538
}
539

540
/**
541
 * Mipmap modes
542
 */
543
enum MIPMAP_MODES {
544
  OFF = 0,
545
  POW2 = 1,
546
  ON = 2,
547
  ON_MANUAL = 3
548
}
549

550
/**
551
 * Alpha modes
552
 */
553
enum ALPHA_MODES {
554
  NPM = 0,        // Non-premultiplied
555
  UNPACK = 1,     // Unpack
556
  PMA = 2,        // Premultiplied alpha
557
  NO_PREMULTIPLIED_ALPHA = 0,
558
  PREMULTIPLY_ON_UPLOAD = 1,
559
  PREMULTIPLIED_ALPHA = 2
560
}
561

562
/**
563
 * Texture formats
564
 */
565
enum FORMATS {
566
  RGBA = 6408,
567
  RGB = 6407,
568
  RG = 33319,
569
  RED = 6403,
570
  RGBA_INTEGER = 36249,
571
  RGB_INTEGER = 36248,
572
  RG_INTEGER = 33320,
573
  RED_INTEGER = 36244,
574
  ALPHA = 6406,
575
  LUMINANCE = 6409,
576
  LUMINANCE_ALPHA = 6410,
577
  DEPTH_COMPONENT = 6402,
578
  DEPTH_STENCIL = 34041
579
}
580

581
/**
582
 * Texture types
583
 */
584
enum TYPES {
585
  UNSIGNED_BYTE = 5121,
586
  UNSIGNED_SHORT = 5123,
587
  UNSIGNED_SHORT_5_6_5 = 33635,
588
  UNSIGNED_SHORT_4_4_4_4 = 32819,
589
  UNSIGNED_SHORT_5_5_5_1 = 32820,
590
  UNSIGNED_INT = 5125,
591
  UNSIGNED_INT_10F_11F_11F_REV = 35899,
592
  UNSIGNED_INT_2_10_10_10_REV = 33640,
593
  UNSIGNED_INT_24_8 = 34042,
594
  UNSIGNED_INT_5_9_9_9_REV = 35902,
595
  BYTE = 5120,
596
  SHORT = 5122,
597
  INT = 5124,
598
  HALF_FLOAT = 5131,
599
  FLOAT = 5126,
600
  FLOAT_32_UNSIGNED_INT_24_8_REV = 36269
601
}
602
```
603

604
**Usage Examples:**
605

606
```typescript
607
import { Texture, RenderTexture, TextureStyle, Assets, Sprite, Graphics } from 'pixi.js';
608

609
// Load texture from URL
610
const texture = await Assets.load('character.png');
611
const sprite = new Sprite(texture);
612

613
// Create texture from canvas
614
const canvas = document.createElement('canvas');
615
canvas.width = 256;
616
canvas.height = 256;
617
const ctx = canvas.getContext('2d');
618
ctx.fillStyle = '#ff0000';
619
ctx.fillRect(0, 0, 256, 256);
620

621
const canvasTexture = Texture.from(canvas);
622

623
// Create texture from video
624
const video = document.createElement('video');
625
video.src = 'video.mp4';
626
video.autoplay = true;
627
video.loop = true;
628

629
const videoTexture = Texture.from(video, {
630
  scaleMode: SCALE_MODES.LINEAR,
631
  resolution: 1
632
});
633

634
// Render texture for dynamic content
635
const renderTexture = RenderTexture.create({
636
  width: 512,
637
  height: 512,
638
  resolution: 2
639
});
640

641
// Render graphics to texture
642
const graphics = new Graphics();
643
graphics.rect(0, 0, 100, 100).fill(0x00ff00);
644

645
app.renderer.render({
646
  container: graphics,
647
  target: renderTexture
648
});
649

650
// Use render texture
651
const renderSprite = new Sprite(renderTexture);
652

653
// Texture style configuration
654
const pixelArtStyle = new TextureStyle({
655
  scaleMode: SCALE_MODES.NEAREST, // Pixel-perfect scaling
656
  addressModeU: WRAP_MODES.CLAMP,
657
  addressModeV: WRAP_MODES.CLAMP
658
});
659

660
texture.source.style = pixelArtStyle;
661

662
// Texture frame manipulation (sprite sheets)
663
const spriteSheetTexture = await Assets.load('spritesheet.png');
664

665
// Create sub-textures from sprite sheet
666
const frame1 = new Texture({
667
  source: spriteSheetTexture.source,
668
  frame: new Rectangle(0, 0, 64, 64)    // First frame
669
});
670

671
const frame2 = new Texture({
672
  source: spriteSheetTexture.source,
673
  frame: new Rectangle(64, 0, 64, 64)   // Second frame
674
});
675

676
// Animated sprite using frames
677
const animatedSprite = new AnimatedSprite([frame1, frame2]);
678
animatedSprite.play();
679

680
// Texture trimming for optimization
681
const trimmedTexture = new Texture({
682
  source: spriteSheetTexture.source,
683
  frame: new Rectangle(10, 10, 44, 44), // Actual image area
684
  trim: new Rectangle(10, 10, 44, 44),  // Trim area
685
  orig: new Rectangle(0, 0, 64, 64)     // Original size
686
});
687

688
// High-DPI texture support
689
const hiDpiTexture = Texture.from('image@2x.png', {
690
  resolution: 2 // 2x resolution
691
});
692

693
// Texture rotation (for sprite atlases)
694
const rotatedTexture = new Texture({
695
  source: spriteSheetTexture.source,
696
  frame: new Rectangle(0, 64, 64, 64),
697
  rotate: 6 // 90 degrees clockwise
698
});
699

700
// Compressed texture (requires extension)
701
const compressedTexture = await Assets.load('texture.ktx');
702

703
// Custom texture from typed array
704
const width = 256;
705
const height = 256;
706
const buffer = new Uint8Array(width * height * 4);
707

708
// Fill with gradient
709
for (let y = 0; y < height; y++) {
710
  for (let x = 0; x < width; x++) {
711
    const i = (y * width + x) * 4;
712
    buffer[i] = x;     // Red
713
    buffer[i + 1] = y; // Green
714
    buffer[i + 2] = 0; // Blue
715
    buffer[i + 3] = 255; // Alpha
716
  }
717
}
718

719
const bufferTexture = Texture.fromBuffer(buffer, width, height, {
720
  format: FORMATS.RGBA,
721
  type: TYPES.UNSIGNED_BYTE
722
});
723

724
// Texture memory management
725
texture.destroy(); // Clean up texture
726
renderTexture.destroy(true); // Destroy including base texture
727

728
// Texture update detection
729
const originalUpdateId = texture.updateId;
730
texture.source.update(); // Trigger update
731
if (texture.updateId !== originalUpdateId) {
732
  console.log('Texture updated');
733
}
734

735
// Creating seamless patterns
736
const patternTexture = Texture.from('pattern.png', {
737
  wrapMode: WRAP_MODES.REPEAT
738
});
739

740
const tilingSprite = new TilingSprite(patternTexture, 800, 600);
741
```