Engine API Reference - v2.20.0-beta.0
    Preparing search index...

    Class Texture

    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 Materials and sampled in Shaders (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. PIXELFORMAT_RGBA32F), half-float (i.e. PIXELFORMAT_RGBA16F) and small-float (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 GraphicsDevice#textureFloatFilterable is true.
      • PIXELFORMAT_RGB9E5 is a compact HDR format with shared exponent, supported for sampling on both WebGL2 and WebGPU, but cannot be used as a render target.

    2. As renderable textures that can be used as color buffers in a RenderTarget:

    Index

    Constructors

    constructor

    Properties

    _invalid _lockedLevel _lockedMode _numLevels _numLevelsRequested _storage id name

    Accessors

    addressU addressV addressW anisotropy array arrayLength compareFunc compareOnRead cubemap depth flipY format height magFilter minFilter mipmaps numLevels pot srgb storage volume width

    Methods

    destroy getSource getView lock read setSource unlock upload

    Constructors

    • Create a new Texture instance.

      Parameters

      Returns Texture

      // 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();

    Properties

    Protected_invalid

    _invalid: boolean = false

    Protected_lockedLevel

    _lockedLevel: number = -1

    Protected_lockedMode

    _lockedMode: number = TEXTURELOCK_NONE

    Protected_numLevels

    _numLevels: number = 0

    Protected_numLevelsRequested

    _numLevelsRequested: number | undefined

    Protected_storage

    _storage: boolean = false
    id: number = ...
    name: string

    The name of the texture.

    Accessors

    • get addressU(): number

      Gets the addressing mode to be applied to the texture horizontally.

      Returns number

    • set addressU(v: number): void

      Sets the addressing mode to be applied to the texture horizontally. Can be:

      Parameters

      • v: number

      Returns void

    • get addressV(): number

      Gets the addressing mode to be applied to the texture vertically.

      Returns number

    • set addressV(v: number): void

      Sets the addressing mode to be applied to the texture vertically. Can be:

      Parameters

      • v: number

      Returns void

    • get addressW(): number

      Gets the addressing mode to be applied to the 3D texture depth.

      Returns number

    • set addressW(addressW: number): void

      Sets the addressing mode to be applied to the 3D texture depth. Can be:

      Parameters

      • addressW: number

      Returns void

    • get anisotropy(): number

      Gets the integer value specifying the level of anisotropy to apply to the texture.

      Returns number

    • set anisotropy(v: number): void

      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 GraphicsDevice#maxAnisotropy).

      Parameters

      • v: number

      Returns void

    • get array(): boolean

      Returns true if this texture is a 2D texture array and false otherwise.

      Returns boolean

    • get arrayLength(): number

      Returns the number of textures inside this texture if this is a 2D array texture or 0 otherwise.

      Returns number

    • get compareOnRead(): boolean

      Gets whether you can get filtered results of comparison using texture() in your shader.

      Returns boolean

    • set compareOnRead(v: boolean): void

      When enabled, and if texture format is PIXELFORMAT_DEPTH or PIXELFORMAT_DEPTHSTENCIL, hardware PCF is enabled for this texture, and you can get filtered results of comparison using texture() in your shader.

      Parameters

      • v: boolean

      Returns void

    • get cubemap(): boolean

      Returns true if this texture is a cube map and false otherwise.

      Returns boolean

    • get depth(): number

      The number of depth slices in a 3D texture.

      Returns number

    • get flipY(): boolean

      Gets whether the texture should be flipped in the Y-direction.

      Returns boolean

    • set flipY(flipY: boolean): void

      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.

      Parameters

      • flipY: boolean

      Returns void

    • get height(): number

      The height of the texture in pixels.

      Returns number

    • get magFilter(): number

      Gets the magnification filter to be applied to the texture.

      Returns number

    • set magFilter(v: number): void

      Sets the magnification filter to be applied to the texture. Can be:

      Parameters

      • v: number

      Returns void

    • get mipmaps(): boolean

      Gets whether the texture should generate/upload mipmaps.

      Returns boolean

    • set mipmaps(v: boolean): void

      Sets whether the texture should generate/upload mipmaps.

      Parameters

      • v: boolean

      Returns void

    • get numLevels(): number

      Gets the number of mip levels.

      Returns number

    • get pot(): boolean

      Returns true if all dimensions of the texture are power of two, and false otherwise.

      Returns boolean

    • get srgb(): 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.

      Returns boolean

    • get storage(): boolean

      Defines if texture can be used as a storage texture by a compute shader.

      Returns boolean

    • get volume(): boolean

      Returns true if this texture is a 3D volume and false otherwise.

      Returns boolean

    • get width(): number

      The width of the texture in pixels.

      Returns number

    Methods

    • Frees resources associated with this texture.

      Returns 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.

      Parameters

      • OptionalmipLevel: number = 0

        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.

    • Creates a TextureView for this texture, specifying a subset of mip levels and array layers. TextureViews can be used with compute shaders to access specific portions of a texture.

      Note: TextureView is only supported on WebGPU. On WebGL, the full texture is always bound.

      Parameters

      • OptionalbaseMipLevel: number = 0

        The first mip level accessible to the view. Defaults to 0.

      • OptionalmipLevelCount: number = 1

        The number of mip levels accessible to the view. Defaults to 1.

      • OptionalbaseArrayLayer: number = 0

        The first array layer accessible to the view. Defaults to 0.

      • OptionalarrayLayerCount: number = 1

        The number of array layers accessible to the view. Defaults to 1.

      Returns TextureView

      A new TextureView for this texture.

      // Create a view for mip level 1
      const mip1View = texture.getView(1);

      // Use with compute shader
      compute.setParameter('outputTexture', mip1View);

    • Locks a miplevel of the texture, returning a typed array to be filled with pixel data.

      Parameters

      • Optionaloptions: { face?: number; level?: number; mode?: number } = {}

        Optional options object. Valid properties are as follows:

        • Optionalface?: number

          If the texture is a cubemap, this is the index of the face to lock.

        • Optionallevel?: number

          The mip level to lock with 0 being the top level. Defaults to 0.

        • Optionalmode?: number

          The lock mode. Can be:

      Returns
          | Uint8Array<ArrayBufferLike>
          | Uint16Array<ArrayBufferLike>
          | Uint32Array<ArrayBufferLike>
          | Float32Array<ArrayBufferLike>

      A typed array containing the pixel data of the locked mip level.

    • Download the textures data from the graphics memory to the local memory.

      Parameters

      • x: number

        The left edge of the rectangle.

      • y: number

        The top edge of the rectangle.

      • width: number

        The width of the rectangle.

      • height: number

        The height of the rectangle.

      • Optionaloptions: {
            data?:
                | Uint8Array<ArrayBufferLike>
                | Uint16Array<ArrayBufferLike>
                | Uint32Array<ArrayBufferLike>
                | Float32Array<ArrayBufferLike>;
            face?: number;
            immediate?: boolean;
            mipLevel?: number;
            renderTarget?: RenderTarget;
        } = {}

        Object for passing optional arguments.

        • Optionaldata?:
              | Uint8Array<ArrayBufferLike>
              | Uint16Array<ArrayBufferLike>
              | Uint32Array<ArrayBufferLike>
              | Float32Array<ArrayBufferLike>

          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.

        • Optionalface?: number

          The face to download. Defaults to 0.

        • Optionalimmediate?: boolean

          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.

        • OptionalmipLevel?: number

          The mip level to download. Defaults to 0.

        • OptionalrenderTarget?: 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.

      Returns Promise<
          | Uint8Array<ArrayBufferLike>
          | Uint16Array<ArrayBufferLike>
          | Uint32Array<ArrayBufferLike>
          | Float32Array<ArrayBufferLike>,
      >

      A promise that resolves with the pixel data of the texture.

    • Unlocks the currently locked mip level and uploads it to VRAM.

      Returns void

    • Forces a reupload of the texture's pixel data to graphics memory. Ordinarily, this function is called internally by setSource and 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.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods