GPUDevice: createTexture() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The createTexture()
method of the
GPUDevice
interface creates a GPUTexture
in which to store 1D, 2D, or 3D arrays of data, such as images, to use in GPU rendering operations.
Syntax
js
createTexture(descriptor)
Parameters
descriptor
-
An object containing the following properties:
dimension
Optional-
An enumerated value indicating the dimension level of the texture. Possible values are:
"1d"
: The texture is one-dimensional."2d"
: The texture is two-dimensional or an array of two-dimensional layers."3d"
: The texture is three-dimensional.
dimension
defaults to"2d"
if the value is omitted. format
-
An enumerated value specifying the format of the texture. See the Texture formats section of the specification for all the possible values.
label
Optional-
A string providing a label that can be used to identify the object, for example in
GPUError
messages or console warnings. mipLevelCount
Optional-
A number specifying the number of mip levels the texture will contain. If omitted, this defaults to 1.
sampleCount
Optional-
A number specifying the texture's sample count. To be valid, the value must be 1 or 4. If omitted, this defaults to 1. A value higher than 1 indicates a multi-sampled texture.
size
-
An object or array specifying the width, height, and depth/array layer count of the texture. The width value must always be specified, while the height and depth/array layer count values are optional and will default to 1 if omitted.
What follows is a sample
size
array:js
size: [16, 16, 2];
The object equivalent would look like this:
js
size: { width: 16, height: 16, depthOrArrayLayers: 2 }
usage
-
The bitwise flags representing the allowed usages for the
GPUTexture
. The possible values are in theGPUTexture.usage
value table.Note that multiple possible usages can be specified by separating values with pipe symbols, for example:
js
usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT;
viewFormats
Optional-
An array of enumerated values specifying other texture formats permitted when calling
GPUTexture.createView()
on this texture, in addition to the texture format specified in itsformat
value.
Return value
A GPUTexture
object instance.
Validation
The following criteria must be met when calling createTexture()
, otherwise a GPUValidationError
is generated and an invalid GPUTexture
object is returned:
- A valid
usage
is specified. - The values specified in
size
(width, height, or depth/array layer count) are greater than 0. mipLevelCount
is greater than 0.sampleCount
is equal to 1 or 4.- If
dimension
is set to"1d"
:- The
size
width value is less than or equal to theGPUDevice
'smaxTextureDimension1D
limit. - The
size
height and depth/array layer count values are equal to 1. - The
sampleCount
is equal to 1. - The
format
is not equal to a compressed format or depth-or-stencil format.
- The
- If
dimension
is set to"2d"
: - If
dimension
is set to"3d"
:- The
size
width, and height, and depth/array layer count values are less than or equal to theGPUDevice
'smaxTextureDimension3D
limit. - The
sampleCount
value is equal to 1. - The
format
is not equal to a compressed format or depth-or-stencil format.
- The
- The
size
width value is a multiple of the texel block width. - The
size
height value is a multiple of the texel block height. - If
sampleCount
is greater than 1:mipLevelCount
is equal to 1.- The
size
depth/array layer count value is equal to 1. usage
includes theGPUTextureUsage.RENDER_ATTACHMENT
flag.usage
does not include theGPUTextureUsage.STORAGE_BINDING
flag.- The specified format supports multi-sampling.
- The
mipLevelCount
value is less than or equal to the maximum miplevel count. - The formats specified in
format
andviewFormats
are compatible with one another. - If
usage
includes theGPUTextureUsage.RENDER_ATTACHMENT
flag:format
is a renderable format (meaning a color renderable format, or a depth-or-stencil format).dimension
is set to"2d"
.
- If
usage
includes theGPUTextureUsage.STORAGE_BINDING
flag:- The specified
format
includes theSTORAGE_BINDING
capability (see the Plain color formats table for reference).
- The specified
Examples
In the WebGPU samples Textured Cube sample, a texture to use on the faces of a cube is created by:
- Loading the image into an
HTMLImageElement
and creating an image bitmap usingcreateImageBitmap()
. - Creating a new texture using
createTexture()
. - Copying the image bitmap into the texture using
GPUQueue.copyExternalImageToTexture()
.
js
//...
let cubeTexture: GPUTexture; // Sample is written in TypeScript
{
const img = document.createElement("img");
img.src = new URL(
"../../../assets/img/Di-3d.png",
import.meta.url
).toString();
await img.decode();
const imageBitmap = await createImageBitmap(img);
cubeTexture = device.createTexture({
size: [imageBitmap.width, imageBitmap.height, 1],
format: "rgba8unorm",
usage:
GPUTextureUsage.TEXTURE_BINDING |
GPUTextureUsage.COPY_DST |
GPUTextureUsage.RENDER_ATTACHMENT,
});
device.queue.copyExternalImageToTexture(
{ source: imageBitmap },
{ texture: cubeTexture },
[imageBitmap.width, imageBitmap.height]
);
}
//...
Specifications
Specification |
---|
WebGPU # dom-gpudevice-createtexture |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API