mirror of
https://github.com/visgl/luma.gl.git
synced 2026-01-18 14:03:42 +00:00
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# DynamicTexture
|
|
|
|
<p class="badges">
|
|
<img src="https://img.shields.io/badge/From-v9.2-blue.svg?style=flat-square" alt="From-v9.2" />
|
|
<img src="https://img.shields.io/badge/@luma.gl-engine.svg?style=flat-square" alt="@luma.gl/engine" />
|
|
</p>
|
|
|
|
> `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.
|
|
|
|
| `DynamicTexture` | `Texture` | Capability | Description |
|
|
| ---------------- | --------- | ---------- | ------------------------------------------------------------ |
|
|
| ✅ | ❌ | Resize | e.g updating textures to match changes in screen size |
|
|
| ✅ | ❌ | Async Init | avoids callbacks and conditional logic to defer texture init |
|
|
| 🚧 | ❌ | Mipmaps | Handles mipmap generation on WebGPU |
|
|
| ✅ | - | `Model` | `Model` 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
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
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.
|
|
|
|
```ts
|
|
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.
|
|
|
|
```ts
|
|
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).
|
|
|
|
```ts
|
|
texture: Texture;
|
|
```
|
|
|
|
### `sampler`
|
|
|
|
Shortcut to `DynamicTexture.texture.sampler`.
|
|
|
|
It is an error to access this member if `DynamicTexture.isReady` is not true).
|
|
|
|
```ts
|
|
sampler: Sampler;
|
|
```
|
|
|
|
### `view`
|
|
|
|
Shortcut to `DynamicTexture.texture.view`.
|
|
|
|
It is an error to access this member if `DynamicTexture.isReady` is not true).
|
|
|
|
```ts
|
|
view: TextureView;
|
|
```
|
|
|
|
## Methods
|
|
|
|
### constructor
|
|
|
|
Creates a new `DynamicTexture`.
|
|
|
|
```ts
|
|
new DynamicTexture(device: Device, props: DynamicTextureProps);
|
|
```
|