import { BaseTexture } from './BaseTexture'; import { ImageResource } from './resources/ImageResource'; import type { CanvasResource } from './resources/CanvasResource'; import { TextureUvs } from './TextureUvs'; import { settings } from '@pixi/settings'; import { Rectangle, Point } from '@pixi/math'; import { uid, TextureCache, getResolutionOfUrl, EventEmitter } from '@pixi/utils'; import type { Resource } from './resources/Resource'; import type { BufferResource } from './resources/BufferResource'; import type { IPointData, ISize } from '@pixi/math'; import type { IBaseTextureOptions, ImageSource } from './BaseTexture'; import type { TextureMatrix } from './TextureMatrix'; const DEFAULT_UVS = new TextureUvs(); export type TextureSource = string | BaseTexture | ImageSource; export interface Texture extends GlobalMixins.Texture, EventEmitter {} /** * Used to remove listeners from WHITE and EMPTY Textures * @ignore */ function removeAllHandlers(tex: any): void { tex.destroy = function _emptyDestroy(): void { /* empty */ }; tex.on = function _emptyOn(): void { /* empty */ }; tex.once = function _emptyOnce(): void { /* empty */ }; tex.emit = function _emptyEmit(): void { /* empty */ }; } /** * A texture stores the information that represents an image or part of an image. * * It cannot be added to the display list directly; instead use it as the texture for a Sprite. * If no frame is provided for a texture, then the whole image is used. * * You can directly create a texture from an image and then reuse it multiple times like this : * * ```js * let texture = PIXI.Texture.from('assets/image.png'); * let sprite1 = new PIXI.Sprite(texture); * let sprite2 = new PIXI.Sprite(texture); * ``` * * If you didnt pass the texture frame to constructor, it enables `noFrame` mode: * it subscribes on baseTexture events, it automatically resizes at the same time as baseTexture. * * Textures made from SVGs, loaded or not, cannot be used before the file finishes processing. * You can check for this by checking the sprite's _textureID property. * ```js * var texture = PIXI.Texture.from('assets/image.svg'); * var sprite1 = new PIXI.Sprite(texture); * //sprite1._textureID should not be undefined if the texture has finished processing the SVG file * ``` * You can use a ticker or rAF to ensure your sprites load the finished textures after processing. See issue #3068. * @memberof PIXI * @typeParam R - The BaseTexture's Resource type. */ export class Texture extends EventEmitter { /** The base texture that this texture uses. */ public baseTexture: BaseTexture; /** This is the area of original texture, before it was put in atlas. */ public orig: Rectangle; /** * This is the trimmed area of original texture, before it was put in atlas * Please call `updateUvs()` after you change coordinates of `trim` manually. */ public trim: Rectangle; /** This will let the renderer know if the texture is valid. If it's not then it cannot be rendered. */ public valid: boolean; /** * Does this Texture have any frame data assigned to it? * * This mode is enabled automatically if no frame was passed inside constructor. * * In this mode texture is subscribed to baseTexture events, and fires `update` on any change. * * Beware, after loading or resize of baseTexture event can fired two times! * If you want more control, subscribe on baseTexture itself. * * ```js * texture.on('update', () => {}); * ``` * * Any assignment of `frame` switches off `noFrame` mode. */ public noFrame: boolean; /** * Anchor point that is used as default if sprite is created with this texture. * Changing the `defaultAnchor` at a later point of time will not update Sprite's anchor point. * @default {0,0} */ public defaultAnchor: Point; /** Default TextureMatrix instance for this texture. By default, that object is not created because its heavy. */ public uvMatrix: TextureMatrix; protected _rotate: number; /** * Update ID is observed by sprites and TextureMatrix instances. * Call updateUvs() to increment it. * @protected */ _updateID: number; /** * This is the area of the BaseTexture image to actually copy to the Canvas / WebGL when rendering, * irrespective of the actual frame size or placement (which can be influenced by trimmed texture atlases) */ _frame: Rectangle; /** * The WebGL UV data cache. Can be used as quad UV. * @protected */ _uvs: TextureUvs; /** * The ids under which this Texture has been added to the texture cache. This is * automatically set as long as Texture.addToCache is used, but may not be set if a * Texture is added directly to the TextureCache array. */ textureCacheIds: Array; /** * @param baseTexture - The base texture source to create the texture from * @param frame - The rectangle frame of the texture to show * @param orig - The area of original texture * @param trim - Trimmed rectangle of original texture * @param rotate - indicates how the texture was rotated by texture packer. See {@link PIXI.groupD8} * @param anchor - Default anchor point used for sprite placement / rotation */ constructor(baseTexture: BaseTexture, frame?: Rectangle, orig?: Rectangle, trim?: Rectangle, rotate?: number, anchor?: IPointData) { super(); this.noFrame = false; if (!frame) { this.noFrame = true; frame = new Rectangle(0, 0, 1, 1); } if (baseTexture instanceof Texture) { baseTexture = baseTexture.baseTexture; } this.baseTexture = baseTexture; this._frame = frame; this.trim = trim; this.valid = false; this._uvs = DEFAULT_UVS; this.uvMatrix = null; this.orig = orig || frame;// new Rectangle(0, 0, 1, 1); this._rotate = Number(rotate || 0); if (rotate as any === true) { // this is old texturepacker legacy, some games/libraries are passing "true" for rotated textures this._rotate = 2; } else if (this._rotate % 2 !== 0) { throw new Error('attempt to use diamond-shaped UVs. If you are sure, set rotation manually'); } this.defaultAnchor = anchor ? new Point(anchor.x, anchor.y) : new Point(0, 0); this._updateID = 0; this.textureCacheIds = []; if (!baseTexture.valid) { baseTexture.once('loaded', this.onBaseTextureUpdated, this); } else if (this.noFrame) { // if there is no frame we should monitor for any base texture changes.. if (baseTexture.valid) { this.onBaseTextureUpdated(baseTexture); } } else { this.frame = frame; } if (this.noFrame) { baseTexture.on('update', this.onBaseTextureUpdated, this); } } /** * Updates this texture on the gpu. * * Calls the TextureResource update. * * If you adjusted `frame` manually, please call `updateUvs()` instead. */ update(): void { if (this.baseTexture.resource) { this.baseTexture.resource.update(); } } /** * Called when the base texture is updated * @protected * @param baseTexture - The base texture. */ onBaseTextureUpdated(baseTexture: BaseTexture): void { if (this.noFrame) { if (!this.baseTexture.valid) { return; } this._frame.width = baseTexture.width; this._frame.height = baseTexture.height; this.valid = true; this.updateUvs(); } else { // TODO this code looks confusing.. boo to abusing getters and setters! // if user gave us frame that has bigger size than resized texture it can be a problem this.frame = this._frame; } this.emit('update', this); } /** * Destroys this texture * @param [destroyBase=false] - Whether to destroy the base texture as well */ destroy(destroyBase?: boolean): void { if (this.baseTexture) { if (destroyBase) { const { resource } = this.baseTexture as unknown as BaseTexture; // delete the texture if it exists in the texture cache.. // this only needs to be removed if the base texture is actually destroyed too.. if (resource?.url && TextureCache[resource.url]) { Texture.removeFromCache(resource.url); } this.baseTexture.destroy(); } this.baseTexture.off('loaded', this.onBaseTextureUpdated, this); this.baseTexture.off('update', this.onBaseTextureUpdated, this); this.baseTexture = null; } this._frame = null; this._uvs = null; this.trim = null; this.orig = null; this.valid = false; Texture.removeFromCache(this); this.textureCacheIds = null; } /** * Creates a new texture object that acts the same as this one. * @returns - The new texture */ clone(): Texture { const clonedFrame = this._frame.clone(); const clonedOrig = this._frame === this.orig ? clonedFrame : this.orig.clone(); const clonedTexture = new Texture(this.baseTexture, !this.noFrame && clonedFrame, clonedOrig, this.trim?.clone(), this.rotate, this.defaultAnchor ); if (this.noFrame) { clonedTexture._frame = clonedFrame; } return clonedTexture; } /** * Updates the internal WebGL UV cache. Use it after you change `frame` or `trim` of the texture. * Call it after changing the frame */ updateUvs(): void { if (this._uvs === DEFAULT_UVS) { this._uvs = new TextureUvs(); } this._uvs.set(this._frame, this.baseTexture, this.rotate); this._updateID++; } /** * Helper function that creates a new Texture based on the source you provide. * The source can be - frame id, image url, video url, canvas element, video element, base texture * @param {string|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement|PIXI.BaseTexture} source - * Source or array of sources to create texture from * @param options - See {@link PIXI.BaseTexture}'s constructor for options. * @param {string} [options.pixiIdPrefix=pixiid] - If a source has no id, this is the prefix of the generated id * @param {boolean} [strict] - Enforce strict-mode, see {@link PIXI.settings.STRICT_TEXTURE_CACHE}. * @returns {PIXI.Texture} The newly created texture */ static from(source: TextureSource | TextureSource[], options: IBaseTextureOptions = {}, strict = settings.STRICT_TEXTURE_CACHE): Texture { const isFrame = typeof source === 'string'; let cacheId = null; if (isFrame) { cacheId = source; } else if (source instanceof BaseTexture) { if (!source.cacheId) { const prefix = options?.pixiIdPrefix || 'pixiid'; source.cacheId = `${prefix}-${uid()}`; BaseTexture.addToCache(source, source.cacheId); } cacheId = source.cacheId; } else { if (!(source as any)._pixiId) { const prefix = options?.pixiIdPrefix || 'pixiid'; (source as any)._pixiId = `${prefix}_${uid()}`; } cacheId = (source as any)._pixiId; } let texture = TextureCache[cacheId] as Texture; // Strict-mode rejects invalid cacheIds if (isFrame && strict && !texture) { throw new Error(`The cacheId "${cacheId}" does not exist in TextureCache.`); } if (!texture && !(source instanceof BaseTexture)) { if (!options.resolution) { options.resolution = getResolutionOfUrl(source as string); } texture = new Texture(new BaseTexture(source, options)); texture.baseTexture.cacheId = cacheId; BaseTexture.addToCache(texture.baseTexture, cacheId); Texture.addToCache(texture, cacheId); } else if (!texture && (source instanceof BaseTexture)) { texture = new Texture(source as BaseTexture); Texture.addToCache(texture, cacheId); } // lets assume its a base texture! return texture; } /** * Useful for loading textures via URLs. Use instead of `Texture.from` because * it does a better job of handling failed URLs more effectively. This also ignores * `PIXI.settings.STRICT_TEXTURE_CACHE`. Works for Videos, SVGs, Images. * @param url - The remote URL or array of URLs to load. * @param options - Optional options to include * @returns - A Promise that resolves to a Texture. */ static fromURL( url: string | string[], options?: IBaseTextureOptions): Promise> { const resourceOptions = Object.assign({ autoLoad: false }, options?.resourceOptions); const texture = Texture.from(url, Object.assign({ resourceOptions }, options), false); const resource = texture.baseTexture.resource; // The texture was already loaded if (texture.baseTexture.valid) { return Promise.resolve(texture); } // Manually load the texture, this should allow users to handle load errors return resource.load().then(() => Promise.resolve(texture)); } /** * Create a new Texture with a BufferResource from a Float32Array. * RGBA values are floats from 0 to 1. * @param {Float32Array|Uint8Array} buffer - The optional array to use, if no data * is provided, a new Float32Array is created. * @param width - Width of the resource * @param height - Height of the resource * @param options - See {@link PIXI.BaseTexture}'s constructor for options. * @returns - The resulting new BaseTexture */ static fromBuffer(buffer: Float32Array | Uint8Array, width: number, height: number, options?: IBaseTextureOptions): Texture { return new Texture(BaseTexture.fromBuffer(buffer, width, height, options)); } /** * Create a texture from a source and add to the cache. * @param {HTMLImageElement|HTMLCanvasElement|string} source - The input source. * @param imageUrl - File name of texture, for cache and resolving resolution. * @param name - Human readable name for the texture cache. If no name is * specified, only `imageUrl` will be used as the cache ID. * @param options * @returns - Output texture */ static fromLoader(source: HTMLImageElement | HTMLCanvasElement | string, imageUrl: string, name?: string, options?: IBaseTextureOptions): Promise> { const baseTexture = new BaseTexture(source, Object.assign({ scaleMode: settings.SCALE_MODE, resolution: getResolutionOfUrl(imageUrl), }, options)); const { resource } = baseTexture; if (resource instanceof ImageResource) { resource.url = imageUrl; } const texture = new Texture(baseTexture); // No name, use imageUrl instead if (!name) { name = imageUrl; } // lets also add the frame to pixi's global cache for 'fromLoader' function BaseTexture.addToCache(texture.baseTexture, name); Texture.addToCache(texture, name); // also add references by url if they are different. if (name !== imageUrl) { BaseTexture.addToCache(texture.baseTexture, imageUrl); Texture.addToCache(texture, imageUrl); } // Generally images are valid right away if (texture.baseTexture.valid) { return Promise.resolve(texture); } // SVG assets need to be parsed async, let's wait return new Promise((resolve) => { texture.baseTexture.once('loaded', () => resolve(texture)); }); } /** * Adds a Texture to the global TextureCache. This cache is shared across the whole PIXI object. * @param texture - The Texture to add to the cache. * @param id - The id that the Texture will be stored against. */ static addToCache(texture: Texture, id: string): void { if (id) { if (!texture.textureCacheIds.includes(id)) { texture.textureCacheIds.push(id); } if (TextureCache[id]) { // eslint-disable-next-line no-console console.warn(`Texture added to the cache with an id [${id}] that already had an entry`); } TextureCache[id] = texture; } } /** * Remove a Texture from the global TextureCache. * @param texture - id of a Texture to be removed, or a Texture instance itself * @returns - The Texture that was removed */ static removeFromCache(texture: string | Texture): Texture | null { if (typeof texture === 'string') { const textureFromCache = TextureCache[texture]; if (textureFromCache) { const index = textureFromCache.textureCacheIds.indexOf(texture); if (index > -1) { textureFromCache.textureCacheIds.splice(index, 1); } delete TextureCache[texture]; return textureFromCache; } } else if (texture?.textureCacheIds) { for (let i = 0; i < texture.textureCacheIds.length; ++i) { // Check that texture matches the one being passed in before deleting it from the cache. if (TextureCache[texture.textureCacheIds[i]] === texture) { delete TextureCache[texture.textureCacheIds[i]]; } } texture.textureCacheIds.length = 0; return texture; } return null; } /** * Returns resolution of baseTexture * @readonly */ get resolution(): number { return this.baseTexture.resolution; } /** * The frame specifies the region of the base texture that this texture uses. * Please call `updateUvs()` after you change coordinates of `frame` manually. */ get frame(): Rectangle { return this._frame; } set frame(frame: Rectangle) { this._frame = frame; this.noFrame = false; const { x, y, width, height } = frame; const xNotFit = x + width > this.baseTexture.width; const yNotFit = y + height > this.baseTexture.height; if (xNotFit || yNotFit) { const relationship = xNotFit && yNotFit ? 'and' : 'or'; const errorX = `X: ${x} + ${width} = ${x + width} > ${this.baseTexture.width}`; const errorY = `Y: ${y} + ${height} = ${y + height} > ${this.baseTexture.height}`; throw new Error('Texture Error: frame does not fit inside the base Texture dimensions: ' + `${errorX} ${relationship} ${errorY}`); } this.valid = width && height && this.baseTexture.valid; if (!this.trim && !this.rotate) { this.orig = frame; } if (this.valid) { this.updateUvs(); } } /** * Indicates whether the texture is rotated inside the atlas * set to 2 to compensate for texture packer rotation * set to 6 to compensate for spine packer rotation * can be used to rotate or mirror sprites * See {@link PIXI.groupD8} for explanation */ get rotate(): number { return this._rotate; } set rotate(rotate: number) { this._rotate = rotate; if (this.valid) { this.updateUvs(); } } /** The width of the Texture in pixels. */ get width(): number { return this.orig.width; } /** The height of the Texture in pixels. */ get height(): number { return this.orig.height; } /** Utility function for BaseTexture|Texture cast. */ castToBaseTexture(): BaseTexture { return this.baseTexture; } private static _EMPTY: Texture; private static _WHITE: Texture; /** An empty texture, used often to not have to create multiple empty textures. Can not be destroyed. */ public static get EMPTY(): Texture { if (!Texture._EMPTY) { Texture._EMPTY = new Texture(new BaseTexture()); removeAllHandlers(Texture._EMPTY); removeAllHandlers(Texture._EMPTY.baseTexture); } return Texture._EMPTY; } /** A white texture of 16x16 size, used for graphics and other things Can not be destroyed. */ public static get WHITE(): Texture { if (!Texture._WHITE) { const canvas = settings.ADAPTER.createCanvas(16, 16); const context = canvas.getContext('2d'); canvas.width = 16; canvas.height = 16; context.fillStyle = 'white'; context.fillRect(0, 0, 16, 16); Texture._WHITE = new Texture(BaseTexture.from(canvas)); removeAllHandlers(Texture._WHITE); removeAllHandlers(Texture._WHITE.baseTexture); } return Texture._WHITE; } }