0
# Textures
1

2
Comprehensive texture management system supporting multiple resource types, texture atlases, GPU texture optimization, and various image formats. The texture system handles all aspects of GPU texture management including uploading, caching, and resource management.
3

4
## Capabilities
5

6
### Texture
7

8
Main texture class that represents a region of a BaseTexture, providing UV coordinates, frames, and transformation data for rendering.
9

10
```typescript { .api }
11
/**
12
 * Texture represents a region of a BaseTexture for rendering
13
 * Handles UV coordinates, frames, and texture transformations
14
 */
15
class Texture<R = Resource> extends EventEmitter {
16
  /** Empty texture instance for fallback rendering */
17
  static EMPTY: Texture;
18
  /** White 1x1 texture for solid color rendering */
19
  static WHITE: Texture;
20

21
  /** The base texture containing the image data */
22
  baseTexture: BaseTexture<R>;
23
  /** Original texture rectangle before any transformations */
24
  orig: Rectangle;
25
  /** Trimmed rectangle if texture was trimmed */
26
  trim: Rectangle;
27
  /** Current frame rectangle defining the texture region */
28
  frame: Rectangle;
29
  /** Whether texture is valid and ready for rendering */
30
  valid: boolean;
31
  /** Whether this texture has no frame (uses full BaseTexture) */
32
  noFrame: boolean;
33
  /** Default anchor point for sprites using this texture */
34
  defaultAnchor: Point;
35
  /** UV transformation matrix */
36
  uvMatrix: TextureMatrix;
37
  /** Rotation of texture in increments of π/2 */
38
  rotate: number;
39

40
  /**
41
   * Create a new Texture
42
   * @param baseTexture - Base texture containing image data
43
   * @param frame - Rectangle frame within the base texture
44
   * @param orig - Original rectangle before trimming
45
   * @param trim - Trimmed rectangle
46
   * @param rotate - Rotation in increments of π/2
47
   * @param anchor - Default anchor point
48
   */
49
  constructor(
50
    baseTexture: BaseTexture,
51
    frame?: Rectangle,
52
    orig?: Rectangle,
53
    trim?: Rectangle,
54
    rotate?: number,
55
    anchor?: IPointData
56
  );
57

58
  /** Update UV coordinates based on current frame */
59
  updateUvs(): void;
60

61
  /** Create a copy of this texture */
62
  clone(): Texture;
63

64
  /** Update texture when BaseTexture changes */
65
  update(): void;
66

67
  /**
68
   * Destroy texture and optionally its BaseTexture
69
   * @param destroyBase - Also destroy the BaseTexture
70
   */
71
  destroy(destroyBase?: boolean): void;
72

73
  /**
74
   * Create texture from various sources
75
   * @param source - Image source (URL, ImageElement, Canvas, etc.)
76
   * @param options - BaseTexture creation options
77
   * @param strict - Strict mode for error handling
78
   */
79
  static from(source: TextureSource, options?: IBaseTextureOptions, strict?: boolean): Texture;
80

81
  /**
82
   * Create texture from URL with promise-based loading
83
   * @param url - Image URL to load
84
   * @param options - BaseTexture options
85
   */
86
  static fromURL(url: string, options?: IBaseTextureOptions): Promise<Texture>;
87

88
  /**
89
   * Create texture from typed array buffer
90
   * @param buffer - Pixel data buffer
91
   * @param width - Texture width
92
   * @param height - Texture height
93
   * @param options - BaseTexture options
94
   */
95
  static fromBuffer(
96
    buffer: Float32Array | Uint8Array,
97
    width: number,
98
    height: number,
99
    options?: IBaseTextureOptions
100
  ): Texture;
101

102
  /**
103
   * Create texture from loaded image element
104
   * @param source - HTML image or canvas element
105
   * @param imageUrl - Original image URL for caching
106
   * @param name - Cache name
107
   * @param options - BaseTexture options
108
   */
109
  static fromLoader(
110
    source: HTMLImageElement | HTMLCanvasElement,
111
    imageUrl: string,
112
    name?: string,
113
    options?: IBaseTextureOptions
114
  ): Promise<Texture>;
115

116
  /**
117
   * Add texture to global cache
118
   * @param texture - Texture to cache
119
   * @param id - Cache identifier
120
   */
121
  static addToCache(texture: Texture, id: string): void;
122

123
  /**
124
   * Remove texture from global cache
125
   * @param texture - Texture or cache ID to remove
126
   */
127
  static removeFromCache(texture: string | Texture): Texture | null;
128
}
129

130
type TextureSource = string | BaseTexture | ImageSource;
131
type ImageSource = HTMLImageElement | HTMLVideoElement | ImageBitmap | HTMLCanvasElement;
132
```
133

134
### BaseTexture
135

136
Base texture class that manages the actual GPU texture resource, handles uploading pixel data to the GPU and manages texture parameters.
137

138
```typescript { .api }
139
/**
140
 * BaseTexture manages the GPU texture resource and pixel data
141
 * Handles texture uploading, caching, and GPU resource management
142
 */
143
class BaseTexture<R = Resource> extends EventEmitter {
144
  /** Texture width in pixels */
145
  width: number;
146
  /** Texture height in pixels */
147
  height: number;
148
  /** Texture resolution/density */
149
  resolution: number;
150
  /** Alpha handling mode */
151
  alphaMode?: ALPHA_MODES;
152
  /** Anisotropic filtering level (1-16) */
153
  anisotropicLevel?: number;
154
  /** Pixel format (RGBA, RGB, etc.) */
155
  format?: FORMATS;
156
  /** Data type (UNSIGNED_BYTE, FLOAT, etc.) */
157
  type?: TYPES;
158
  /** WebGL texture target (TEXTURE_2D, TEXTURE_CUBE_MAP, etc.) */
159
  target?: TARGETS;
160
  /** Texture wrapping mode for UV coordinates */
161
  wrapMode: WRAP_MODES;
162
  /** Scaling mode for minification/magnification */
163
  scaleMode: SCALE_MODES;
164
  /** Mipmap generation mode */
165
  mipmap: MIPMAP_MODES;
166
  /** The underlying resource containing image data */
167
  resource: R;
168
  /** Whether texture is valid and uploaded to GPU */
169
  valid: boolean;
170
  /** Whether texture has been destroyed */
171
  destroyed: boolean;
172
  /** Texture cache ID */
173
  cacheId: string;
174
  /** Whether texture was loaded from cache */
175
  isPowerOfTwo: boolean;
176
  /** Internal WebGL texture cache */
177
  _glTextures: {[key: number]: GLTexture};
178

179
  /**
180
   * Create a new BaseTexture
181
   * @param resource - Image resource or source
182
   * @param options - Texture creation options
183
   */
184
  constructor(resource?: R | ImageSource | string, options?: IBaseTextureOptions<RO>);
185

186
  /** Update texture when resource changes */
187
  update(): void;
188

189
  /**
190
   * Set texture scaling and mipmap modes
191
   * @param scaleMode - Scaling mode for filtering
192
   * @param mipmap - Mipmap generation mode
193
   */
194
  setStyle(scaleMode?: SCALE_MODES, mipmap?: MIPMAP_MODES): this;
195

196
  /**
197
   * Set desired texture size and resolution
198
   * @param desiredWidth - Target width
199
   * @param desiredHeight - Target height  
200
   * @param resolution - Texture resolution
201
   */
202
  setSize(desiredWidth: number, desiredHeight: number, resolution?: number): this;
203

204
  /**
205
   * Set real pixel size of texture
206
   * @param realWidth - Actual pixel width
207
   * @param realHeight - Actual pixel height
208
   * @param resolution - Texture resolution
209
   */
210
  setRealSize(realWidth: number, realHeight: number, resolution?: number): this;
211

212
  /**
213
   * Set the resource for this BaseTexture
214
   * @param resource - New image resource
215
   */
216
  setResource(resource: R): this;
217

218
  /** Destroy texture and cleanup GPU resources */
219
  destroy(): void;
220

221
  /**
222
   * Create BaseTexture from image source
223
   * @param source - Image source
224
   * @param options - Creation options
225
   * @param strict - Strict error handling
226
   */
227
  static from<R = Resource, RO = any>(
228
    source: ImageSource | string,
229
    options?: IBaseTextureOptions<RO>,
230
    strict?: boolean
231
  ): BaseTexture<R>;
232

233
  /**
234
   * Create BaseTexture from canvas element
235
   * @param canvas - HTML canvas element
236
   * @param options - Creation options
237
   */
238
  static fromCanvas(canvas: HTMLCanvasElement, options?: IBaseTextureOptions): BaseTexture<CanvasResource>;
239

240
  /**
241
   * Add BaseTexture to cache
242
   * @param baseTexture - Texture to cache
243
   * @param id - Cache identifier
244
   */
245
  static addToCache(baseTexture: BaseTexture, id: string): void;
246

247
  /**
248
   * Remove BaseTexture from cache
249
   * @param baseTexture - Texture or ID to remove
250
   */
251
  static removeFromCache(baseTexture: string | BaseTexture): BaseTexture | null;
252
}
253

254
interface IBaseTextureOptions<RO = any> {
255
  /** Alpha handling mode */
256
  alphaMode?: ALPHA_MODES;
257
  /** Mipmap generation mode */  
258
  mipmap?: MIPMAP_MODES;
259
  /** Anisotropic filtering level */
260
  anisotropicLevel?: number;
261
  /** Scaling mode for filtering */
262
  scaleMode?: SCALE_MODES;
263
  /** Texture wrapping mode */
264
  wrapMode?: WRAP_MODES;
265
  /** Pixel format */
266
  format?: FORMATS;
267
  /** Data type */
268
  type?: TYPES;
269
  /** WebGL texture target */
270
  target?: TARGETS;
271
  /** Texture resolution */
272
  resolution?: number;
273
  /** Resource-specific options */
274
  resourceOptions?: RO;
275
  /** Texture width override */
276
  width?: number;
277
  /** Texture height override */
278
  height?: number;
279
}
280
```
281

282
### TextureMatrix
283

284
UV transformation matrix for handling texture coordinate transformations, rotations, and mappings.
285

286
```typescript { .api }
287
/**
288
 * TextureMatrix handles UV coordinate transformations
289
 * Manages texture coordinate mapping and transformations
290
 */
291
class TextureMatrix {
292
  /** UV transformation matrix */
293
  mapCoord: Matrix;
294
  /** UV clamping matrix */
295
  uClampFrame: Matrix;
296
  /** UV wrapping offset matrix */
297
  uClampOffset: Matrix;
298
  /** Associated texture */
299
  _texture: Texture;
300
  /** Whether matrix needs updating */
301
  _updateID: number;
302

303
  /**
304
   * Create a new TextureMatrix
305
   * @param texture - Texture to create matrix for
306
   * @param clampMargin - Clamping margin for UV coordinates
307
   */
308
  constructor(texture: Texture, clampMargin?: number);
309

310
  /**
311
   * Update the matrix when texture changes
312
   * @param forceUpdate - Force matrix recalculation
313
   */
314
  update(forceUpdate?: boolean): boolean;
315

316
  /**
317
   * Multiply UV coordinates by this matrix
318
   * @param uvs - UV coordinate array to transform
319
   * @param out - Output array for transformed coordinates
320
   */
321
  multiplyUvs(uvs: Float32Array, out?: Float32Array): Float32Array;
322
}
323
```
324

325
### Texture Resources
326

327
Various resource types for different image sources and data formats.
328

329
```typescript { .api }
330
/**
331
 * Base resource class for texture data sources
332
 */
333
abstract class Resource extends EventEmitter {
334
  /** Resource width */
335
  width: number;
336
  /** Resource height */
337
  height: number;
338
  /** Whether resource is valid */
339
  valid: boolean;
340
  /** Whether resource has been destroyed */
341
  destroyed: boolean;
342
  /** Internal format */
343
  internal: boolean;
344

345
  /**
346
   * Create new resource
347
   * @param width - Resource width
348
   * @param height - Resource height
349
   */
350
  constructor(width?: number, height?: number);
351

352
  /** Upload resource to GPU texture */
353
  upload(renderer: Renderer, baseTexture: BaseTexture, glTexture: GLTexture): boolean;
354

355
  /** Update resource */
356
  update(): void;
357

358
  /** Dispose of resource */
359
  dispose(): void;
360

361
  /** Destroy resource */
362
  destroy(): void;
363
}
364

365
/**
366
 * Resource for HTML image elements
367
 */
368
class ImageResource extends Resource {
369
  /** Source image element */
370
  source: HTMLImageElement;
371
  /** Image URL */
372
  url: string;
373
  
374
  constructor(source: HTMLImageElement | string, options?: IImageResourceOptions);
375
  
376
  /** Load image from URL */
377
  load(): Promise<ImageResource>;
378
}
379

380
/**
381
 * Resource for HTML canvas elements
382
 */
383
class CanvasResource extends Resource {
384
  /** Source canvas element */
385
  source: HTMLCanvasElement;
386
  
387
  constructor(source: HTMLCanvasElement);
388
}
389

390
/**
391
 * Resource for HTML video elements
392
 */
393
class VideoResource extends Resource {
394
  /** Source video element */
395
  source: HTMLVideoElement;
396
  /** Auto-play flag */
397
  autoPlay: boolean;
398
  /** Video update FPS */
399
  updateFPS: number;
400
  
401
  constructor(source: HTMLVideoElement | string, options?: IVideoResourceOptions);
402
}
403

404
/**
405
 * Resource for ImageBitmap objects
406
 */
407
class ImageBitmapResource extends Resource {
408
  /** Source ImageBitmap */
409
  source: ImageBitmap;
410
  
411
  constructor(source: ImageBitmap);
412
}
413

414
/**
415
 * Resource for typed array buffers
416
 */
417
class BufferResource extends Resource {
418
  /** Source data buffer */
419
  data: Float32Array | Uint8Array | Uint32Array;
420
  
421
  constructor(source: Float32Array | Uint8Array | Uint32Array, options: IBufferResourceOptions);
422
}
423
```
424

425
**Usage Examples:**
426

427
```typescript
428
import { Texture, BaseTexture, TextureMatrix } from "@pixi/core";
429

430
// Create texture from image URL
431
const texture = Texture.from('/path/to/image.png');
432

433
// Create texture from canvas
434
const canvas = document.createElement('canvas');
435
const ctx = canvas.getContext('2d');
436
ctx.fillStyle = 'red';
437
ctx.fillRect(0, 0, 100, 100);
438
const canvasTexture = Texture.from(canvas);
439

440
// Create texture from buffer data
441
const buffer = new Uint8Array(64 * 64 * 4); // RGBA data
442
buffer.fill(255); // White texture
443
const bufferTexture = Texture.fromBuffer(buffer, 64, 64);
444

445
// Create texture with options
446
const texture = Texture.from('/path/to/image.png', {
447
  scaleMode: SCALE_MODES.NEAREST,
448
  wrapMode: WRAP_MODES.REPEAT,
449
  mipmap: MIPMAP_MODES.ON
450
});
451

452
// Use texture frames for sprite sheets
453
const baseTexture = BaseTexture.from('/path/to/spritesheet.png');
454
const frameTexture = new Texture(
455
  baseTexture,
456
  new Rectangle(0, 0, 32, 32) // 32x32 frame at top-left
457
);
458

459
// Handle texture loading
460
Texture.fromURL('/path/to/image.png').then((texture) => {
461
  console.log('Texture loaded:', texture.width, texture.height);
462
});
463

464
// Texture caching
465
Texture.addToCache(texture, 'my-texture');
466
const cachedTexture = Texture.from('my-texture');
467

468
// UV transformations
469
const uvMatrix = new TextureMatrix(texture);
470
const uvs = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]);
471
const transformedUvs = uvMatrix.multiplyUvs(uvs);
472
```
473

474
## Types
475

476
```typescript { .api }
477
interface IImageResourceOptions {
478
  /** Cross-origin mode */
479
  crossorigin?: boolean | string;
480
  /** Auto-load flag */
481
  autoLoad?: boolean;
482
  /** Create ImageBitmap flag */
483
  createBitmap?: boolean;
484
}
485

486
interface IVideoResourceOptions {
487
  /** Auto-update flag */
488
  autoUpdate?: boolean;
489
  /** Auto-play flag */  
490
  autoPlay?: boolean;
491
  /** Update FPS rate */
492
  updateFPS?: number;
493
  /** Cross-origin mode */
494
  crossorigin?: boolean | string;
495
}
496

497
interface IBufferResourceOptions {
498
  /** Texture width */
499
  width: number;
500
  /** Texture height */
501
  height: number;
502
  /** Pixel format */
503
  format?: FORMATS;
504
  /** Data type */
505
  type?: TYPES;
506
}
507

508
enum ALPHA_MODES {
509
  NPM = 0,
510
  UNPACK = 1,
511
  PMA = 2,
512
  NO_PREMULTIPLIED_ALPHA = 0,
513
  PREMULTIPLY_ON_UPLOAD = 1,
514
  PREMULTIPLIED_ALPHA = 2
515
}
516

517
enum SCALE_MODES {
518
  NEAREST = 0,
519
  LINEAR = 1
520
}
521

522
enum WRAP_MODES {
523
  CLAMP = 0,
524
  REPEAT = 1,
525
  MIRRORED_REPEAT = 2
526
}
527

528
enum MIPMAP_MODES {
529
  OFF = 0,
530
  POW2 = 1,
531
  ON = 2,
532
  ON_MANUAL = 3
533
}
534

535
enum FORMATS {
536
  RGBA = 6408,
537
  RGB = 6407,
538
  ALPHA = 6406,
539
  LUMINANCE = 6409,
540
  LUMINANCE_ALPHA = 6410,
541
  DEPTH_COMPONENT = 6402,
542
  DEPTH_STENCIL = 34041
543
}
544

545
enum TYPES {
546
  UNSIGNED_BYTE = 5121,
547
  UNSIGNED_SHORT = 5123,
548
  UNSIGNED_SHORT_5_6_5 = 33635,
549
  UNSIGNED_SHORT_4_4_4_4 = 32819,
550
  UNSIGNED_SHORT_5_5_5_1 = 32820,
551
  FLOAT = 5126,
552
  HALF_FLOAT = 36193
553
}
554
```