API
API|
@babylonjs/core|
HtmlTexture

Class HtmlTexture

A texture whose content is rendered from a live HTML element using the WICG HTML-in-Canvas API (https://github.com/WICG/html-in-canvas).

The element is hosted as a child of the engine's rendering canvas (which is marked layoutsubtree) so the browser can lay it out and snapshot it; the WICG API requires the source element to be a direct child of the canvas whose context performs the upload. Content is uploaded through WebGLRenderingContext.texElementImage2D (WebGL) or GPUQueue.copyElementImageToTexture (WebGPU), available either natively (behind chrome://flags/#canvas-draw-element) or via the three-html-render polyfill (https://github.com/repalash/three-html-render). When neither is present, a built-in SVG <foreignObject> fallback is used instead (see useSvgFallback).

As with HtmlElementTexture, updates are not automatic unless autoUpdate is enabled; in that case the texture refreshes whenever the host canvas reports a paint change.

Hierarchy (View Summary)

Index
constructor
animations anisotropicFilteringLevel delayLoadState displayName element host invertZ isRenderTarget level metadata name onDisposeObservable onLoadObservable optimizeUVAllocation reservedDataStore sphericalPolynomial uniqueId wrapR DEFAULT_ANISOTROPIC_FILTERING_LEVEL
canRescale coordinatesIndex coordinatesMode errorObject gammaSpace getAlphaFromRGB hasAlpha irradianceTexture is2DArray is3D isBlocking isCube isRGBD linearSpecularLOD loadingError lodGenerationOffset lodGenerationScale noMipmap onDispose samplingMode textureFormat textureType uid wrapU wrapV
clone delayLoad dispose forceSphericalPolynomialsRecompute getBaseSize getClassName getInternalTexture getReflectionTextureMatrix getRefractionTextureMatrix getScene getSize getTextureMatrix isReady isReadyOrNotBlocking readPixels releaseInternalTexture requestUpdate scale serialize toString update updateSamplingMode WhenAllReady
animations: Animation[] = []

Define the list of animation attached to the texture.

anisotropicFilteringLevel: number = BaseTexture.DEFAULT_ANISOTROPIC_FILTERING_LEVEL

With compliant hardware and browser (supporting anisotropic filtering) this defines the level of anisotropic filtering in the texture. The higher the better but the slower. This defaults to 4 as it seems to be the best tradeoff.

delayLoadState: number = Constants.DELAYLOADSTATE_NONE

Define the current state of the loading sequence when in delayed load mode.

displayName: string

Define the display name of the texture, which is used as tree item name of the dedicated node in the inspector

element: HTMLElement

The HTML element rendered into the texture.

host: Nullable<HTMLElement>

The element that hosts element in the document. This is the engine's rendering canvas when one is available (required by the WICG API, which can only capture the element from that canvas), or a hidden helper <div> otherwise - in which case only the SVG fallback can render.

invertZ: boolean = false

Is Z inverted in the texture (useful in a cube texture).

isRenderTarget: boolean = false

Define if the texture is a render target.

level: number = 1

Intensity or strength of the texture. It is commonly used by materials to fine tune the intensity of the texture

metadata: any = null

Gets or sets an object used to store user defined information.

name: string

Define the name of the texture.

onDisposeObservable: Observable<BaseTexture> = ...

An event triggered when the texture is disposed.

onLoadObservable: Observable<HtmlTexture> = ...

Observable triggered once the texture has been rendered for the first time.

optimizeUVAllocation: boolean = true

Gets or sets a boolean indicating that the texture should try to reduce shader code if there is no UV manipulation. (ie. when texture.getTextureMatrix().isIdentityAs3x2() returns true)

reservedDataStore: any = null

For internal use only. Please do not use.

sphericalPolynomial: Nullable<SphericalPolynomial>

Get the polynomial representation of the texture data. This is mainly use as a fast way to recover IBL Diffuse irradiance data.

https://learnopengl.com/PBR/IBL/Diffuse-irradiance

uniqueId: number

Gets or sets the unique id of the texture

wrapR: number = Constants.TEXTURE_WRAP_ADDRESSMODE
ValueTypeDescription
0CLAMP_ADDRESSMODE
1WRAP_ADDRESSMODE
2MIRROR_ADDRESSMODE
DEFAULT_ANISOTROPIC_FILTERING_LEVEL: number = 4

Default anisotropic filtering level for the application. It is set to 4 as a good tradeoff between perf and quality.

  • get coordinatesMode(): number

    How a texture is mapped. Unused in thin texture mode.

    Returns number

  • set coordinatesMode(value: number): void

    How a texture is mapped.

    ValueTypeDescription
    0EXPLICIT_MODE
    1SPHERICAL_MODE
    2PLANAR_MODE
    3CUBIC_MODE
    4PROJECTION_MODE
    5SKYBOX_MODE
    6INVCUBIC_MODE
    7EQUIRECTANGULAR_MODE
    8FIXED_EQUIRECTANGULAR_MODE
    9FIXED_EQUIRECTANGULAR_MIRRORED_MODE

    Parameters

    • value: number

    Returns void

  • get errorObject(): { exception?: any; message?: string } | undefined

    If a loading error occurred this object will be populated with information about the error.

    Returns { exception?: any; message?: string } | undefined

  • set onDispose(callback: () => void): void

    Callback triggered when the texture has been disposed. Kept for back compatibility, you can use the onDisposeObservable instead.

    Parameters

    • callback: () => void

    Returns void

  • Reads the pixels stored in the webgl texture and returns them as an ArrayBuffer. This will returns an RGBA array buffer containing either in values (0-255) or float values (0-1) depending of the underlying buffer type. Note that you can use GetTextureDataAsync instead, which will also support reading from a compressed texture (by rendering it to an intermediate RGBA texture and retrieving the bytes from it).

    Parameters

    • faceIndex: number = 0

      defines the face of the texture to read (in case of cube texture)

    • level: number = 0

      defines the LOD level of the texture to read (in case of Mip Maps)

    • buffer: Nullable<ArrayBufferView<ArrayBufferLike>> = null

      defines a user defined buffer to fill with data (can be null)

    • flushRenderer: boolean = true

      true to flush the renderer from the pending commands before reading the pixels

    • noDataConversion: boolean = false

      false to convert the data to Uint8Array (if texture type is UNSIGNED_BYTE) or to Float32Array (if texture type is anything but UNSIGNED_BYTE). If true, the type of the generated buffer (if buffer==null) will depend on the type of the texture

    • x: number = 0

      defines the region x coordinates to start reading from (default to 0)

    • y: number = 0

      defines the region y coordinates to start reading from (default to 0)

    • width: number = Number.MAX_VALUE

      defines the region width to read from (default to the texture size at level)

    • height: number = Number.MAX_VALUE

      defines the region width to read from (default to the texture size at level)

    Returns Nullable<Promise<ArrayBufferView<ArrayBufferLike>>>

    The Array buffer promise containing the pixels data.

  • Requests the host canvas to emit a paint event on the next rendering update. When auto-update is enabled, this triggers a texture refresh in sync with the DOM. Falls back to an immediate update when the WICG API is not available.

    Returns void

  • Update the sampling mode of the texture. Default is Trilinear mode.

    ValueTypeDescription
    1NEAREST_SAMPLINGMODE or NEAREST_NEAREST_MIPLINEARNearest is: mag = nearest, min = nearest, mip = linear
    2BILINEAR_SAMPLINGMODE or LINEAR_LINEAR_MIPNEARESTBilinear is: mag = linear, min = linear, mip = nearest
    3TRILINEAR_SAMPLINGMODE or LINEAR_LINEAR_MIPLINEARTrilinear is: mag = linear, min = linear, mip = linear
    4NEAREST_NEAREST_MIPNEAREST
    5NEAREST_LINEAR_MIPNEAREST
    6NEAREST_LINEAR_MIPLINEAR
    7NEAREST_LINEAR
    8NEAREST_NEAREST
    9LINEAR_NEAREST_MIPNEAREST
    10LINEAR_NEAREST_MIPLINEAR
    11LINEAR_LINEAR
    12LINEAR_NEAREST

    mag: magnification filter (close to the viewer) min: minification filter (far from the viewer) mip: filter used between mip map levels

    Parameters

    • samplingMode: number

      Define the new sampling mode of the texture

    • generateMipMaps: boolean = false

      Define if the texture should generate mip maps or not. Default is false.

    Returns void