Skip to main content

DynamicTexture

From-v9.2@luma.gl/engine

DynamicTexture was called AsyncTexture in v9.1

The DynamicTexture class module is designed to make it easier to work with textures in luma.gl. The underlying Texture class in @luma.gl/core module can be used, however it is not designed for convenience, as it intentionally offers only the minimal API necessary to expose GPU texture capabilities in a portable way.

DynamicTextureTextureCapabilityDescription
✅❌Resizee.g updating textures to match changes in screen size
✅❌Async Initavoids callbacks and conditional logic to defer texture init
🚧❌MipmapsHandles mipmap generation on WebGPU
✅-ModelModel class is DynamicTexture aware
  • DynamicTexture can be resized.
    • This is very useful when developing shader based techniques that need to respond to changes in screen size.
  • DynamicTexture can be created and "used" while data is still being loaded.
    • The DynamicTexture class accepts promises that resolve to texture data (images or byte arrays).
    • It postpones the creation of underlying Textures until the supplied promise(s) resolve and data is available.
  • The Model class accepts DynamicTextures as bindings wherever a Texture or TextureView would be accepted
    • Model avoids rendering (Model.draw() call execution) until the underlying texture has been created.

Usage​

import {DynamicTexture, loadImage} from '@luma.gl/engine';
const dynamicTexture = new DynamicTexture({data: loadImage(url)});
const model = new Model(device, {source, bindings: {texture: DynamicTexture}});
const renderPass = device.createRenderPass();
model.draw(renderPass); // Doesn't draw
...
await dynamicTexture.ready; // Not necessary, just for illustration
model.draw(renderPass); // Draws

Types​

export type DynamicTextureProps = Omit<TextureProps, 'data'> & DynamicTextureDataProps;

type DynamicTextureDataProps =
  | DynamicTexture1DProps
  | DynamicTexture2DProps
  | DynamicTexture3DProps
  | DynamicTextureArrayProps
  | DynamicTextureCubeProps
  | DynamicTextureCubeArrayProps;

type DynamicTexture1DProps = {dimension: '1d'; data: Promise<Texture1DData> | Texture1DData | null};
type DynamicTexture2DProps = {
  dimension?: '2d';
  data: Promise<Texture2DData> | Texture2DData | null;
};
type DynamicTexture3DProps = {dimension: '3d'; data: Promise<Texture3DData> | Texture3DData | null};
type DynamicTextureArrayProps = {
  dimension: '2d-array';
  data: Promise<TextureArrayData> | TextureArrayData | null;
};
type DynamicTextureCubeProps = {
  dimension: 'cube';
  data: Promise<TextureCubeData> | TextureCubeData | null;
};
type DynamicTextureCubeArrayProps = {
  dimension: 'cube-array';
  data: Promise<TextureCubeArrayData> | TextureCubeArrayData | null;
};

Members​

ready​

A promise that resolves when the data has completed loading / preparation and the underlying GPU texture has been created and initialized, or rejects with an Error instance describing the failure.

ready: Promise<void>;

isReady​

A flag that indicates whether data loading / preparation has completed loading and the underlying GPU texture has been created and initialized.

isReady: boolean;

Initial value is false. Once the DynamicTexture.ready promise resolve successfully, the DynamicTexture.isReady flag is guaranteed to be true.

texture​

It is an error to access this member if DynamicTexture.isReady is not true).

texture: Texture;

sampler​

Shortcut to DynamicTexture.texture.sampler.

It is an error to access this member if DynamicTexture.isReady is not true).

sampler: Sampler;

view​

Shortcut to DynamicTexture.texture.view.

It is an error to access this member if DynamicTexture.isReady is not true).

view: TextureView;

Methods​

constructor​

Creates a new DynamicTexture.

new DynamicTexture(device: Device, props: DynamicTextureProps);