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<R extends Resource = Resource> extends EventEmitter
{
/** The base texture that this texture uses. */
public baseTexture: BaseTexture<R>;
/** 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<string>;
/**
* @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 PIXI.groupD8
* @param anchor - Default anchor point used for sprite placement / rotation
*/
constructor(baseTexture: BaseTexture<R>, 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<ImageResource>;
// 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 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 PIXI.settings.STRICT_TEXTURE_CACHE.
* @returns {PIXI.Texture} The newly created texture
*/
static from<R extends Resource = Resource, RO = any>(source: TextureSource | TextureSource[],
options: IBaseTextureOptions<RO> = {},
strict = settings.STRICT_TEXTURE_CACHE): Texture<R>
{
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<R>;
// 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<R>(new BaseTexture<R>(source, options));
texture.baseTexture.cacheId = cacheId;
BaseTexture.addToCache(texture.baseTexture, cacheId);
Texture.addToCache(texture, cacheId);
}
else if (!texture && (source instanceof BaseTexture))
{
texture = new Texture<R>(source as BaseTexture<R>);
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<R extends Resource = Resource, RO = any>(
url: string | string[], options?: IBaseTextureOptions<RO>): Promise<Texture<R>>
{
const resourceOptions = Object.assign({ autoLoad: false }, options?.resourceOptions);
const texture = Texture.from<R>(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 PIXI.BaseTexture's constructor for options.
* @returns - The resulting new BaseTexture
*/
static fromBuffer(buffer: Float32Array | Uint8Array,
width: number, height: number, options?: IBaseTextureOptions<ISize>): Texture<BufferResource>
{
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<R extends Resource = Resource>(source: HTMLImageElement | HTMLCanvasElement | string,
imageUrl: string, name?: string, options?: IBaseTextureOptions): Promise<Texture<R>>
{
const baseTexture = new BaseTexture<R>(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<R>(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 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<Resource>;
private static _WHITE: Texture<CanvasResource>;
/** An empty texture, used often to not have to create multiple empty textures. Can not be destroyed. */
public static get EMPTY(): Texture<Resource>
{
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<CanvasResource>
{
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;
}
}