GPUDevice: createTexture() method

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 the GPUTexture.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 its format value.

A GPUTexture object instance.

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 the GPUDevice's maxTextureDimension1D 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.
• If dimension is set to "2d":
  • The size width and height values are less than or equal to the GPUDevice's maxTextureDimension2D limit.
  • The size depth/array layer count value is less than or equal to the GPUDevice's maxTextureArrayLayers limit.
• If dimension is set to "3d":
  • The size width, and height, and depth/array layer count values are less than or equal to the GPUDevice's maxTextureDimension3D limit.
  • The sampleCount value is equal to 1.
  • The format is not equal to a compressed format or depth-or-stencil format.
• 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 the GPUTextureUsage.RENDER_ATTACHMENT flag.
  • usage does not include the GPUTextureUsage.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 and viewFormats are compatible with one another.
• If usage includes the GPUTextureUsage.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 the GPUTextureUsage.STORAGE_BINDING flag:
  • The specified format includes the STORAGE_BINDING capability (see the Plain color formats table for reference).

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 using createImageBitmap().
• Creating a new texture using createTexture().
• Copying the image bitmap into the texture using GPUQueue.copyExternalImageToTexture().

//...

let cubeTexture;

{
  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],
  );
}

//...

• The WebGPU API