UNPKG

playcanvas

Version:

PlayCanvas WebGL game engine

677 lines (676 loc) 26.3 kB
/** * Represents a texture, which is typically an image composed of pixels (texels). Textures are * fundamental resources for rendering graphical objects. They are commonly used by * {@link Material}s and sampled in {@link Shader}s (usually fragment shaders) to define the visual * appearance of a 3D model's surface. Beyond storing color images, textures can hold various data * types like normal maps, environment maps (cubemaps), or custom data for shader computations. Key * properties control how the texture data is sampled, including filtering modes and coordinate * wrapping. * * Note on **HDR texture format** support: * 1. **As textures**: * - float (i.e. {@link PIXELFORMAT_RGBA32F}), half-float (i.e. {@link PIXELFORMAT_RGBA16F}) and * small-float ({@link PIXELFORMAT_111110F}) formats are always supported on both WebGL2 and WebGPU * with point sampling. * - half-float and small-float formats are always supported on WebGL2 and WebGPU with linear * sampling. * - float formats are supported on WebGL2 and WebGPU with linear sampling only if * {@link GraphicsDevice#textureFloatFilterable} is true. * * 2. **As renderable textures** that can be used as color buffers in a {@link RenderTarget}: * - on WebGPU, rendering to float and half-float formats is always supported. * - on WebGPU, rendering to small-float format is supported only if * {@link GraphicsDevice#textureRG11B10Renderable} is true. * - on WebGL2, rendering to these 3 formats formats is supported only if * {@link GraphicsDevice#textureFloatRenderable} is true. * - on WebGL2, if {@link GraphicsDevice#textureFloatRenderable} is false, but * {@link GraphicsDevice#textureHalfFloatRenderable} is true, rendering to half-float formats only * is supported. This is the case of many mobile iOS devices. * - you can determine available renderable HDR format using * {@link GraphicsDevice#getRenderableHdrFormat}. * @category Graphics */ export class Texture { /** * Create a new Texture instance. * * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this texture. * @param {object} [options] - Object for passing optional arguments. * @param {string} [options.name] - The name of the texture. Defaults to null. * @param {number} [options.width] - The width of the texture in pixels. Defaults to 4. * @param {number} [options.height] - The height of the texture in pixels. Defaults to 4. * @param {number} [options.depth] - The number of depth slices in a 3D texture. * @param {number} [options.format] - The pixel format of the texture. Can be: * * - {@link PIXELFORMAT_R8} * - {@link PIXELFORMAT_RG8} * - {@link PIXELFORMAT_RGB565} * - {@link PIXELFORMAT_RGBA5551} * - {@link PIXELFORMAT_RGBA4} * - {@link PIXELFORMAT_RGB8} * - {@link PIXELFORMAT_RGBA8} * - {@link PIXELFORMAT_DXT1} * - {@link PIXELFORMAT_DXT3} * - {@link PIXELFORMAT_DXT5} * - {@link PIXELFORMAT_RGB16F} * - {@link PIXELFORMAT_RGBA16F} * - {@link PIXELFORMAT_RGB32F} * - {@link PIXELFORMAT_RGBA32F} * - {@link PIXELFORMAT_ETC1} * - {@link PIXELFORMAT_PVRTC_2BPP_RGB_1} * - {@link PIXELFORMAT_PVRTC_2BPP_RGBA_1} * - {@link PIXELFORMAT_PVRTC_4BPP_RGB_1} * - {@link PIXELFORMAT_PVRTC_4BPP_RGBA_1} * - {@link PIXELFORMAT_111110F} * - {@link PIXELFORMAT_ASTC_4x4} * - {@link PIXELFORMAT_ATC_RGB} * - {@link PIXELFORMAT_ATC_RGBA} * * Defaults to {@link PIXELFORMAT_RGBA8}. * @param {string} [options.projection] - The projection type of the texture, used when the * texture represents an environment. Can be: * * - {@link TEXTUREPROJECTION_NONE} * - {@link TEXTUREPROJECTION_CUBE} * - {@link TEXTUREPROJECTION_EQUIRECT} * - {@link TEXTUREPROJECTION_OCTAHEDRAL} * * Defaults to {@link TEXTUREPROJECTION_CUBE} if options.cubemap is true, otherwise * {@link TEXTUREPROJECTION_NONE}. * @param {number} [options.minFilter] - The minification filter type to use. Defaults to * {@link FILTER_LINEAR_MIPMAP_LINEAR}. * @param {number} [options.magFilter] - The magnification filter type to use. Defaults to * {@link FILTER_LINEAR}. * @param {number} [options.anisotropy] - The level of anisotropic filtering to use. Defaults * to 1. * @param {number} [options.addressU] - The repeat mode to use in the U direction. Defaults to * {@link ADDRESS_REPEAT}. * @param {number} [options.addressV] - The repeat mode to use in the V direction. Defaults to * {@link ADDRESS_REPEAT}. * @param {number} [options.addressW] - The repeat mode to use in the W direction. Defaults to * {@link ADDRESS_REPEAT}. * @param {boolean} [options.mipmaps] - When enabled try to generate or use mipmaps for this * texture. Default is true. * @param {number} [options.numLevels] - Specifies the number of mip levels to generate. If not * specified, the number is calculated based on the texture size. When this property is set, * the mipmaps property is ignored. * @param {boolean} [options.cubemap] - Specifies whether the texture is to be a cubemap. * Defaults to false. * @param {number} [options.arrayLength] - Specifies whether the texture is to be a 2D texture array. * When passed in as undefined or < 1, this is not an array texture. If >= 1, this is an array texture. * Defaults to undefined. * @param {boolean} [options.volume] - Specifies whether the texture is to be a 3D volume. * Defaults to false. * @param {string} [options.type] - Specifies the texture type. Can be: * * - {@link TEXTURETYPE_DEFAULT} * - {@link TEXTURETYPE_RGBM} * - {@link TEXTURETYPE_RGBE} * - {@link TEXTURETYPE_RGBP} * - {@link TEXTURETYPE_SWIZZLEGGGR} * * Defaults to {@link TEXTURETYPE_DEFAULT}. * @param {boolean} [options.flipY] - Specifies whether the texture should be flipped in the * Y-direction. Only affects textures with a source that is an image, canvas or video element. * Does not affect cubemaps, compressed textures or textures set from raw pixel data. Defaults * to false. * @param {boolean} [options.premultiplyAlpha] - If true, the alpha channel of the texture (if * present) is multiplied into the color channels. Defaults to false. * @param {boolean} [options.compareOnRead] - When enabled, and if texture format is * {@link PIXELFORMAT_DEPTH} or {@link PIXELFORMAT_DEPTHSTENCIL}, hardware PCF is enabled for * this texture, and you can get filtered results of comparison using texture() in your shader. * Defaults to false. * @param {number} [options.compareFunc] - Comparison function when compareOnRead is enabled. * Can be: * * - {@link FUNC_LESS} * - {@link FUNC_LESSEQUAL} * - {@link FUNC_GREATER} * - {@link FUNC_GREATEREQUAL} * - {@link FUNC_EQUAL} * - {@link FUNC_NOTEQUAL} * * Defaults to {@link FUNC_LESS}. * @param {Uint8Array[]|Uint16Array[]|Uint32Array[]|Float32Array[]|HTMLCanvasElement[]|HTMLImageElement[]|HTMLVideoElement[]|Uint8Array[][]} [options.levels] * - Array of Uint8Array or other supported browser interface; or a two-dimensional array * of Uint8Array if options.arrayLength is defined and greater than zero. * @param {boolean} [options.storage] - Defines if texture can be used as a storage texture by * a compute shader. Defaults to false. * @example * // Create a 8x8x24-bit texture * const texture = new pc.Texture(graphicsDevice, { * width: 8, * height: 8, * format: pc.PIXELFORMAT_RGB8 * }); * * // Fill the texture with a gradient * const pixels = texture.lock(); * const count = 0; * for (let i = 0; i < 8; i++) { * for (let j = 0; j < 8; j++) { * pixels[count++] = i * 32; * pixels[count++] = j * 32; * pixels[count++] = 255; * } * } * texture.unlock(); */ constructor(graphicsDevice: GraphicsDevice, options?: { name?: string; width?: number; height?: number; depth?: number; format?: number; projection?: string; minFilter?: number; magFilter?: number; anisotropy?: number; addressU?: number; addressV?: number; addressW?: number; mipmaps?: boolean; numLevels?: number; cubemap?: boolean; arrayLength?: number; volume?: boolean; type?: string; flipY?: boolean; premultiplyAlpha?: boolean; compareOnRead?: boolean; compareFunc?: number; levels?: Uint8Array[] | Uint16Array[] | Uint32Array[] | Float32Array[] | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | Uint8Array[][]; storage?: boolean; }); /** * The name of the texture. * * @type {string} */ name: string; /** @ignore */ _gpuSize: number; /** @protected */ protected id: number; /** @protected */ protected _invalid: boolean; /** @protected */ protected _lockedLevel: number; /** @protected */ protected _lockedMode: number; /** * A render version used to track the last time the texture properties requiring bind group * to be updated were changed. * * @type {number} * @ignore */ renderVersionDirty: number; /** @protected */ protected _storage: boolean; /** @protected */ protected _numLevels: number; /** @protected */ protected _numLevelsRequested: number; device: GraphicsDevice; _width: number; _height: number; _format: number; _compressed: boolean; _integerFormat: boolean; _volume: boolean; _depth: number; _arrayLength: number; _cubemap: boolean; _flipY: boolean; _premultiplyAlpha: boolean; _mipmaps: boolean; _minFilter: number; _magFilter: number; _anisotropy: number; _addressU: number; _addressV: number; _addressW: number; _compareOnRead: boolean; _compareFunc: number; _type: string; projection: string; profilerHint: any; _levels: Uint8Array<ArrayBufferLike>[] | Uint16Array<ArrayBufferLike>[] | Uint32Array<ArrayBufferLike>[] | Float32Array<ArrayBufferLike>[] | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[] | Uint8Array<ArrayBufferLike>[][]; /** * Frees resources associated with this texture. */ destroy(): void; recreateImpl(upload?: boolean): void; impl: any; _clearLevels(): void; /** * Resizes the texture. This operation is supported for render target textures, and it resizes * the allocated buffer used for rendering, not the existing content of the texture. * * It is also supported for textures with data provided via the {@link lock} method. After * resizing, the appropriately sized data must be assigned by calling {@link lock} again. * * @param {number} width - The new width of the texture. * @param {number} height - The new height of the texture. * @param {number} [depth] - The new depth of the texture. Defaults to 1. * @ignore */ resize(width: number, height: number, depth?: number): void; /** * Called when the rendering context was lost. It releases all context related resources. * * @ignore */ loseContext(): void; /** * Updates vram size tracking for the texture, size can be positive to add or negative to subtract * * @ignore */ adjustVramSizeTracking(vram: any, size: any): void; propertyChanged(flag: any): void; _updateNumLevel(): void; /** * Returns the current lock mode. One of: * * - {@link TEXTURELOCK_NONE} * - {@link TEXTURELOCK_READ} * - {@link TEXTURELOCK_WRITE} * * @ignore * @type {number} */ get lockedMode(): number; /** * Sets the minification filter to be applied to the texture. Can be: * * - {@link FILTER_NEAREST} * - {@link FILTER_LINEAR} * - {@link FILTER_NEAREST_MIPMAP_NEAREST} * - {@link FILTER_NEAREST_MIPMAP_LINEAR} * - {@link FILTER_LINEAR_MIPMAP_NEAREST} * - {@link FILTER_LINEAR_MIPMAP_LINEAR} * * @type {number} */ set minFilter(v: number); /** * Gets the minification filter to be applied to the texture. * * @type {number} */ get minFilter(): number; /** * Sets the magnification filter to be applied to the texture. Can be: * * - {@link FILTER_NEAREST} * - {@link FILTER_LINEAR} * * @type {number} */ set magFilter(v: number); /** * Gets the magnification filter to be applied to the texture. * * @type {number} */ get magFilter(): number; /** * Sets the addressing mode to be applied to the texture horizontally. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} * - {@link ADDRESS_MIRRORED_REPEAT} * * @type {number} */ set addressU(v: number); /** * Gets the addressing mode to be applied to the texture horizontally. * * @type {number} */ get addressU(): number; /** * Sets the addressing mode to be applied to the texture vertically. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} * - {@link ADDRESS_MIRRORED_REPEAT} * * @type {number} */ set addressV(v: number); /** * Gets the addressing mode to be applied to the texture vertically. * * @type {number} */ get addressV(): number; /** * Sets the addressing mode to be applied to the 3D texture depth. Can be: * * - {@link ADDRESS_REPEAT} * - {@link ADDRESS_CLAMP_TO_EDGE} * - {@link ADDRESS_MIRRORED_REPEAT} * * @type {number} */ set addressW(addressW: number); /** * Gets the addressing mode to be applied to the 3D texture depth. * * @type {number} */ get addressW(): number; /** * When enabled, and if texture format is {@link PIXELFORMAT_DEPTH} or * {@link PIXELFORMAT_DEPTHSTENCIL}, hardware PCF is enabled for this texture, and you can get * filtered results of comparison using texture() in your shader. * * @type {boolean} */ set compareOnRead(v: boolean); /** * Gets whether you can get filtered results of comparison using texture() in your shader. * * @type {boolean} */ get compareOnRead(): boolean; /** * Sets the comparison function when {@link compareOnRead} is enabled. Possible values: * * - {@link FUNC_LESS} * - {@link FUNC_LESSEQUAL} * - {@link FUNC_GREATER} * - {@link FUNC_GREATEREQUAL} * - {@link FUNC_EQUAL} * - {@link FUNC_NOTEQUAL} * * @type {number} */ set compareFunc(v: number); /** * Gets the comparison function when {@link compareOnRead} is enabled. * * @type {number} */ get compareFunc(): number; /** * Sets the integer value specifying the level of anisotropy to apply to the texture. The value * ranges from 1 (no anisotropic filtering) to the maximum anisotropy supported by the graphics * device (see {@link GraphicsDevice#maxAnisotropy}). * * @type {number} */ set anisotropy(v: number); /** * Gets the integer value specifying the level of anisotropy to apply to the texture. * * @type {number} */ get anisotropy(): number; /** * Sets whether the texture should generate/upload mipmaps. * * @type {boolean} */ set mipmaps(v: boolean); /** * Gets whether the texture should generate/upload mipmaps. * * @type {boolean} */ get mipmaps(): boolean; _needsMipmapsUpload: boolean; /** * Gets the number of mip levels. * * @type {number} */ get numLevels(): number; /** * Defines if texture can be used as a storage texture by a compute shader. * * @type {boolean} */ get storage(): boolean; /** * The width of the texture in pixels. * * @type {number} */ get width(): number; /** * The height of the texture in pixels. * * @type {number} */ get height(): number; /** * The number of depth slices in a 3D texture. * * @type {number} */ get depth(): number; /** * The pixel format of the texture. Can be: * * - {@link PIXELFORMAT_R8} * - {@link PIXELFORMAT_RG8} * - {@link PIXELFORMAT_RGB565} * - {@link PIXELFORMAT_RGBA5551} * - {@link PIXELFORMAT_RGBA4} * - {@link PIXELFORMAT_RGB8} * - {@link PIXELFORMAT_RGBA8} * - {@link PIXELFORMAT_DXT1} * - {@link PIXELFORMAT_DXT3} * - {@link PIXELFORMAT_DXT5} * - {@link PIXELFORMAT_RGB16F} * - {@link PIXELFORMAT_RGBA16F} * - {@link PIXELFORMAT_RGB32F} * - {@link PIXELFORMAT_RGBA32F} * - {@link PIXELFORMAT_ETC1} * - {@link PIXELFORMAT_PVRTC_2BPP_RGB_1} * - {@link PIXELFORMAT_PVRTC_2BPP_RGBA_1} * - {@link PIXELFORMAT_PVRTC_4BPP_RGB_1} * - {@link PIXELFORMAT_PVRTC_4BPP_RGBA_1} * - {@link PIXELFORMAT_111110F} * - {@link PIXELFORMAT_ASTC_4x4} * - {@link PIXELFORMAT_ATC_RGB} * - {@link PIXELFORMAT_ATC_RGBA} * * @type {number} */ get format(): number; /** * Returns true if this texture is a cube map and false otherwise. * * @type {boolean} */ get cubemap(): boolean; get gpuSize(): number; /** * Returns true if this texture is a 2D texture array and false otherwise. * * @type {boolean} */ get array(): boolean; /** * Returns the number of textures inside this texture if this is a 2D array texture or 0 otherwise. * * @type {number} */ get arrayLength(): number; /** * Returns true if this texture is a 3D volume and false otherwise. * * @type {boolean} */ get volume(): boolean; /** * Sets the texture type. * * @type {string} * @ignore */ set type(value: string); /** * Gets the texture type. * * @type {string} * @ignore */ get type(): string; /** * Sets the texture's internal format to an sRGB or linear equivalent of its current format. * When set to true, the texture is stored in sRGB format and automatically converted to linear * space when sampled. When set to false, the texture remains in a linear format. Changing this * property recreates the texture on the GPU, which is an expensive operation, so it is * preferable to create the texture with the correct format from the start. If the texture * format has no sRGB variant, this operation is ignored. * This is not a public API and is used by Editor only to update rendering when the sRGB * property is changed in the inspector. The higher cost is acceptable in this case. * * @type {boolean} * @ignore */ set srgb(value: boolean); /** * Returns true if the texture is stored in an sRGB format, meaning it will be converted to * linear space when sampled. Returns false if the texture is stored in a linear format. * * @type {boolean} */ get srgb(): boolean; /** * Sets whether the texture should be flipped in the Y-direction. Only affects textures * with a source that is an image, canvas or video element. Does not affect cubemaps, * compressed textures or textures set from raw pixel data. Defaults to true. * * @type {boolean} */ set flipY(flipY: boolean); /** * Gets whether the texture should be flipped in the Y-direction. * * @type {boolean} */ get flipY(): boolean; _needsUpload: boolean; set premultiplyAlpha(premultiplyAlpha: boolean); get premultiplyAlpha(): boolean; /** * Returns true if all dimensions of the texture are power of two, and false otherwise. * * @type {boolean} */ get pot(): boolean; get encoding(): "srgb" | "linear" | "rgbm" | "rgbe" | "rgbp"; dirtyAll(): void; _levelsUpdated: boolean[] | boolean[][]; _mipmapsUploaded: boolean; /** * Locks a miplevel of the texture, returning a typed array to be filled with pixel data. * * @param {object} [options] - Optional options object. Valid properties are as follows: * @param {number} [options.level] - The mip level to lock with 0 being the top level. Defaults * to 0. * @param {number} [options.face] - If the texture is a cubemap, this is the index of the face * to lock. * @param {number} [options.mode] - The lock mode. Can be: * - {@link TEXTURELOCK_READ} * - {@link TEXTURELOCK_WRITE} * Defaults to {@link TEXTURELOCK_WRITE}. * @returns {Uint8Array|Uint16Array|Uint32Array|Float32Array} A typed array containing the pixel data of * the locked mip level. */ lock(options?: { level?: number; face?: number; mode?: number; }): Uint8Array | Uint16Array | Uint32Array | Float32Array; /** * Set the pixel data of the texture from a canvas, image, video DOM element. If the texture is * a cubemap, the supplied source must be an array of 6 canvases, images or videos. * * @param {HTMLCanvasElement|HTMLImageElement|HTMLVideoElement|HTMLCanvasElement[]|HTMLImageElement[]|HTMLVideoElement[]} source - A * canvas, image or video element, or an array of 6 canvas, image or video elements. * @param {number} [mipLevel] - A non-negative integer specifying the image level of detail. * Defaults to 0, which represents the base image source. A level value of N, that is greater * than 0, represents the image source for the Nth mipmap reduction level. */ setSource(source: HTMLCanvasElement | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement[] | HTMLImageElement[] | HTMLVideoElement[], mipLevel?: number): void; /** * Get the pixel data of the texture. If this is a cubemap then an array of 6 images will be * returned otherwise a single image. * * @param {number} [mipLevel] - A non-negative integer specifying the image level of detail. * Defaults to 0, which represents the base image source. A level value of N, that is greater * than 0, represents the image source for the Nth mipmap reduction level. * @returns {HTMLImageElement} The source image of this texture. Can be null if source not * assigned for specific image level. */ getSource(mipLevel?: number): HTMLImageElement; /** * Unlocks the currently locked mip level and uploads it to VRAM. */ unlock(): void; /** * Forces a reupload of the textures pixel data to graphics memory. Ordinarily, this function * is called by internally by {@link setSource} and {@link unlock}. However, it still needs to * be called explicitly in the case where an HTMLVideoElement is set as the source of the * texture. Normally, this is done once every frame before video textured geometry is * rendered. */ upload(): void; /** * Download the textures data from the graphics memory to the local memory. * * Note a public API yet, as not all options are implemented on all platforms. * * @param {number} x - The left edge of the rectangle. * @param {number} y - The top edge of the rectangle. * @param {number} width - The width of the rectangle. * @param {number} height - The height of the rectangle. * @param {object} [options] - Object for passing optional arguments. * @param {RenderTarget} [options.renderTarget] - The render target using the texture as a color * buffer. Provide as an optimization to avoid creating a new render target. Important especially * when this function is called with high frequency (per frame). Note that this is only utilized * on the WebGL platform, and ignored on WebGPU. * @param {number} [options.mipLevel] - The mip level to download. Defaults to 0. * @param {number} [options.face] - The face to download. Defaults to 0. * @param {Uint8Array|Uint16Array|Uint32Array|Float32Array} [options.data] - The data buffer to * write the pixel data to. If not provided, a new buffer will be created. The type of the buffer * must match the texture's format. * @param {boolean} [options.immediate] - If true, the read operation will be executed as soon as * possible. This has a performance impact, so it should be used only when necessary. Defaults * to false. * @returns {Promise<Uint8Array|Uint16Array|Uint32Array|Float32Array>} A promise that resolves * with the pixel data of the texture. * @ignore */ read(x: number, y: number, width: number, height: number, options?: { renderTarget?: RenderTarget; mipLevel?: number; face?: number; data?: Uint8Array | Uint16Array | Uint32Array | Float32Array; immediate?: boolean; }): Promise<Uint8Array | Uint16Array | Uint32Array | Float32Array>; /** * Upload texture data asynchronously to the GPU. * * @param {number} x - The left edge of the rectangle. * @param {number} y - The top edge of the rectangle. * @param {number} width - The width of the rectangle. * @param {number} height - The height of the rectangle. * @param {Uint8Array|Uint16Array|Uint32Array|Float32Array} data - The pixel data to upload. This should be a typed array. * * @returns {Promise<void>} A promise that resolves when the upload is complete. * @ignore */ write(x: number, y: number, width: number, height: number, data: Uint8Array | Uint16Array | Uint32Array | Float32Array): Promise<void>; } import type { GraphicsDevice } from './graphics-device.js'; import type { RenderTarget } from './render-target.js';