UWAL / Texture

Type Aliases

Usage

type Usage = Readonly<Record<"RENDER" | "STORAGE", GPUTextureUsageFlags>>;

GPUTextureUsageFlags utility bitmasks:

• Usage.RENDER is the default usage when creating a texture.
• Usage.STORAGE is the default usage when creating a storage texture.

Type Parameters

Type Parameter

Classes

Texture

Utility class to create and manage textures and samplers.
Upon instantiation, it returns a promise of itself.

Param

Renderer

Optional Renderer instance required in some methods.

Example

const Texture = new (await UWAL.Texture());

Methods

CreateTexture()

CreateTexture(descriptor): GPUTexture;

Create a new texture from the descriptor object.

Parameters

Parameter	Type	Description
descriptor	Pick<Partial<GPUTextureDescriptor>, "format" | "usage"> & Omit<GPUTextureDescriptor, "format" | "usage">	GPUTextureDescriptor object with optional format and usage properties which default to Device.PreferredCanvasFormat and Usage.RENDER, respectively.

Returns

GPUTexture

See

https://www.w3.org/TR/webgpu/#dom-gpudevice-createtexture

WriteTexture()

WriteTexture(data, options): void;

Write data into a GPUTexture using options.

Parameters

Parameter	Type	Description
data	GPUAllowSharedBufferSource	Buffer data to write.
options	GPUTexelCopyTextureInfo & Partial<GPUExtent3DDict> & Partial<Record<"size", Iterable<number, any, any>>> & GPUTexelCopyBufferLayout	A union of the destination, dataLayout and size arguments of the GPUQueue.writeTexture() method.

Returns

void

See

https://www.w3.org/TR/webgpu/#dom-gpuqueue-writetexture

CreateStorageTexture()

CreateStorageTexture(descriptor?): GPUTexture;

Create a new storage texture.

Parameters

Parameter	Type	Description
descriptor	Pick<Partial<GPUTextureDescriptor>, "format" | "usage" | "size"> & Omit<GPUTextureDescriptor, "format" | "usage" | "size">	GPUTextureDescriptor object with optional format, usage and size properties which default to Device.PreferredCanvasFormat, Usage.STORAGE, and Renderer.CanvasSize when Renderer is provided.

Returns

GPUTexture

Throws

ERROR.DESCRIPTOR_SIZE_NOT_FOUND if Renderer and size parameter are not provided.

CreateTextureFromSource()

CreateTextureFromSource(source, descriptor?): GPUTexture;

Create a new texture using a GPUTexture or any valid image source. Texture's size and mipLevelCount properties are authomatically calculated if not defined explicitly in the descriptor object.

Parameters

Parameter	Type	Description
source	GPUSourceTexture	GPUTexture or an image source.
descriptor?	boolean | TextureDescriptor	CreateTexture descriptor object.

Returns

GPUTexture

CreateSampler()

CreateSampler(descriptor?): GPUSampler;

Create a new sampler from the descriptor object.

Parameters

Parameter	Type	Description
descriptor?	GPUSamplerDescriptor & SamplerDescriptor	GPUSamplerDescriptor object extended with optional properties: addressModeUV for width and height; addressMode is for all 3 dimensions; minMagFilter for min and mag, and filter for min, mag and mipmapFilter. Defaults to {filter: "linear"}.

Returns

GPUSampler

See

https://www.w3.org/TR/webgpu/#dom-gpudevice-createsampler

ImportExternalTexture()

ImportExternalTexture(
   source, 
   colorSpace?, 
   label?
): GPUExternalTexture;

Create a new GPUExternalTexture from a video source.

Parameters

Parameter	Type	Description
source	HTMLVideoElement | VideoFrame	Video source frame or element.
colorSpace?	PredefinedColorSpace	Color space to convert into.
label?	string	Texture label.

Returns

GPUExternalTexture

See

• https://www.w3.org/TR/webgpu/#dom-gpudevice-importexternaltexture
• Video Color Grading for reference.

CreateImageBitmap()

CreateImageBitmap(
   source, 
   options?, 
   requestOptions?
): Promise<ImageBitmap>;

Create a bitmap image from a valid source path.

Parameters

Parameter	Type	Description
source	string	Image source path.
options?	ImageBitmapOptions	Bitmap options, defaults to {colorSpaceConversion: "none"}.
requestOptions?	RequestInit	fetch request options.

Returns

Promise<ImageBitmap>

See

https://developer.mozilla.org/en-US/docs/Web/API/Window/createImageBitmap

CreateMultisampleTexture()

CreateMultisampleTexture(
   force?, 
   sampleCount?, 
   label?
): void;

Create and assign a multisampled texture to the Renderer.MultisampleTexture.

Parameters

Parameter	Type	Default value	Description
force?	boolean	false	Force a new texture to be created.
sampleCount?	number	4	Must be either 1 or 4.
label?	string	undefined	Texture label.

Returns

void

Throws

ERROR.RENDERER_NOT_FOUND if Renderer is not provided.

CreateCubeTexture()

CreateCubeTexture(
   sources, 
   bitmapOptions?, 
   textureDescriptor?, 
   copyOptions?, 
   requestOptions?
): Promise<GPUTexture>;

Create a "cube" texture from 6 image sources. All images must have the same dimensions. This method creates a bitmap image for each source and one cube texture and uses that as the destination when copying bitmaps with flipY option set to false.

Parameters

Parameter	Type	Description
sources	string[]	Array of 6 image source paths.
bitmapOptions?	ImageBitmapOptions	Bitmap options for CreateImageBitmap method, defaults to {colorSpaceConversion: "none"}.
textureDescriptor?	TextureDescriptor	Texture descriptor for CreateTextureFromSource method, defaults to {mipmaps: true}.
copyOptions?	CopyImageOptions	Copy options for CopyImageToTexture method, method, defaults to {flipY: false}.
requestOptions?	RequestInit	fetch request options for CreateImageBitmap method.

Returns

Promise<GPUTexture>

See

• https://www.w3.org/TR/webgpu/#dom-gputextureviewdimension-cube
• Skybox / Materials, Environment maps and SkyBox for reference.

Throws

ERROR.RENDERER_NOT_FOUND if Renderer is not provided.

CopyImageToTexture()

CopyImageToTexture(source, options?): Promise<GPUTexture>;

Copy an image source into a texture and optionally generate mipmaps for it. If options.texture is not provided, a new GPUTexture is created by default.

Parameters

Parameter	Type	Description
source	GPUCopyExternalImageSource	Image source.
options?	Partial<GPUExtent3DDict> & Partial<Record<"size", Iterable<number, any, any>>> & CopyImageOptions	Defaults to {create: true, flipY: true}.

Returns

Promise<GPUTexture>

See

https://www.w3.org/TR/webgpu/#dom-gpuqueue-copyexternalimagetotexture

Throws

ERROR.TEXTURE_NOT_FOUND if called without options.texture when options.mipmaps is true or undefined and options.create is falsy.

CopyTextureToTexture()

CopyTextureToTexture(options): void;

Copy options.srcTexture into options.dstTexture. If options.dstTexture is omitted, a new texture is created from options.srcTexture using options.create descriptor.

Parameters

Parameter	Type	Description
options	Partial<GPUExtent3DDict> & Partial<Record<"size", Iterable<number, any, any>>> & CopyTextureOptions	A union of the source, destination, and copySize arguments of the GPUCommandEncoder.copyTextureToTexture() method.

Returns

void

See

https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-copytexturetotexture

Throws

ERROR.RENDERER_NOT_FOUND if Renderer is not provided.

CopyTextureToBuffer()

CopyTextureToBuffer(options): void;

Copy options.texture into options.buffer.

Parameters

Parameter	Type	Description
options	CopyBufferOptions & GPUTexelCopyTextureInfo & Partial<GPUExtent3DDict> & Partial<Record<"size", Iterable<number, any, any>>> & GPUTexelCopyBufferInfo	A union of the source, destination, and copySize arguments of the GPUCommandEncoder.copyTextureToBuffer() method.

Returns

void

See

https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-copytexturetobuffer

Throws

ERROR.RENDERER_NOT_FOUND if Renderer is not provided.

CopyBufferToTexture()

CopyBufferToTexture(options): void;

Copy options.buffer into options.texture.

Parameters

Parameter	Type	Description
options	GPUTexelCopyBufferInfo & CopyBufferOptions & GPUTexelCopyTextureInfo & Partial<GPUExtent3DDict> & Partial<Record<"size", Iterable<number, any, any>>>	A union of the source, destination, and copySize arguments of the GPUCommandEncoder.copyBufferToTexture() method.

Returns

void

See

https://www.w3.org/TR/webgpu/#dom-gpucommandencoder-copybuffertotexture

Throws

ERROR.RENDERER_NOT_FOUND if Renderer is not provided.

Accessors

PreferredStorageFormat

Get Signature

get PreferredStorageFormat(): GPUTextureFormat;

Get the optimal GPUTextureFormat for storage textures.

Returns

GPUTextureFormat

The only possible values are "rgba8unorm" and "bgra8unorm".

Renderer

Set Signature

set Renderer(renderer): void;

Parameters

Parameter	Type	Description
renderer	RenderStage	Renderer instance required in some methods.

Returns

void