HomeEngine API Reference - v2.21.3
    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
    constructor
    _invalid _lockedLevel _lockedMode _numLevels _numLevelsRequested _storage id name
    addressU addressV addressW anisotropy array arrayLength compareFunc compareOnRead cubemap depth flipY format height magFilter minFilter mipmaps numLevels pot srgb storage volume width
    copy destroy getSource getView lock read setSource unlock upload

    • Create a new Texture instance.

      Parameters

      Returns Texture

      // Create a 8x8x24-bit texture
      const texture = new Texture(graphicsDevice, {
          width: 8,
          height: 8,
          format: 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();

    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.

    • 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 arrayLength(): number

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

      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 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. Note that changing this property on an array texture, or on any texture on WebGPU, re-creates the texture on the GPU, which is an expensive operation, so it is preferable to create the texture with the correct mipmaps setting from the start.

      Parameters

      • v: boolean

      Returns void

    • 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

    • Copies a region of a source texture into this texture. Both textures must have the same pixel format. The copied region sizes must match (no scaling), and must lie within the chosen mip levels of both textures.

      Parameters

      • source: Texture

        The source texture to copy from.

      • Optionaloptions: {
            destMipLevel?: number;
            destX?: number;
            destY?: number;
            face?: number;
            height?: number;
            sourceMipLevel?: number;
            sourceRenderTarget?: RenderTarget;
            sourceX?: number;
            sourceY?: number;
            width?: number;
        } = {}

        Optional arguments.

        • OptionaldestMipLevel?: number

          The destination mip level to copy to. Defaults to 0.

        • OptionaldestX?: number

          The left edge of the destination region. Defaults to 0.

        • OptionaldestY?: number

          The top edge of the destination region. Defaults to 0.

        • Optionalface?: number

          The cubemap face or array layer to copy (applies to both source and destination). Defaults to 0.

        • Optionalheight?: number

          The height of the copied region. Defaults to the full height of the source mip level (minus sourceY).

        • OptionalsourceMipLevel?: number

          The source mip level to copy from. Defaults to 0.

        • OptionalsourceRenderTarget?: RenderTarget

          A render target wrapping the source texture as its color buffer, at the matching face / mip level. Provide as an optimization to avoid allocating a temporary one when copying with high frequency (per frame). Note that this is only utilized on the WebGL platform, and ignored on WebGPU.

        • OptionalsourceX?: number

          The left edge of the source region. Defaults to 0.

        • OptionalsourceY?: number

          The top edge of the source region. Defaults to 0.

        • Optionalwidth?: number

          The width of the copied region. Defaults to the full width of the source mip level (minus sourceX).

      Returns boolean

      True if the copy was successful, false otherwise.

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

    • 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