ThecreateTexture() method of theGPUDevice interface creates aGPUTexture in which to store 1D, 2D, or 3D arrays of data, such as images, to use in GPU rendering operations.

Syntax

createTexture(descriptor)

Parameters

descriptor

An object containing the following properties:

dimensionOptional

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 theTexture formats section of the specification for all the possible values.

Note:

• Thedepth32float-stencil8feature needs to be enabled to createdepth32float-stencil8-formatGPUTextures.
• Thetexture-compression-bc feature needs to be enabled to create two-dimensional (dimension: "2d") BC compressedGPUTextures:bc1-rgba-unorm,bc1-rgba-unorm-srgb,bc2-rgba-unorm,bc2-rgba-unorm-srgb,bc3-rgba-unorm,bc3-rgba-unorm-srgb,bc4-r-unorm,bc4-r-snorm,bc5-rg-unorm,bc5-rg-snorm,bc6h-rgb-ufloat,bc6h-rgb-float,bc7-rgba-unorm, andbc7-rgba-unorm-srgb formats.
• Thetexture-compression-bc andtexture-compression-bc-sliced-3d features need to be enabled to create three-dimensional BC compressedGPUTextures (the sameformat values specified in the previous bullet, but withdimension set to3d).
• Thetexture-compression-astc feature needs to be enabled to create two-dimensional (dimension: "2d") ASTC compressedGPUTextures:astc-4x4-unorm,astc-4x4-unorm-srgb,astc-5x4-unorm,astc-5x4-unorm-srgb,astc-5x5-unorm,astc-5x5-unorm-srgb,astc-6x5-unorm,astc-6x5-unorm-srgb,astc-6x6-unorm,astc-6x6-unorm-srgb,astc-8x5-unorm,astc-8x5-unorm-srgb,astc-8x6-unorm,astc-8x6-unorm-srgb,astc-8x8-unorm,astc-8x8-unorm-srgb,astc-10x5-unorm,astc-10x5-unorm-srgb,astc-10x6-unorm,astc-10x6-unorm-srgb,astc-10x8-unorm,astc-10x8-unorm-srgb,astc-10x10-unorm,astc-10x10-unorm-srgb,astc-12x10-unorm,astc-12x10-unorm-srgb,astc-12x12-unorm, andastc-12x12-unorm-srgb formats.
• Thetexture-compression-astc andtexture-compression-astc-sliced-3d features need to be enabled to create three-dimensional BC compressedGPUTextures (the sameformat values specified in the previous bullet, but withdimension set to3d).
• Thetexture-compression-etc2 feature needs to be enabled to create two-dimensional ETC2 compressedGPUTextures:etc2-rgb8unorm,etc2-rgb8unorm-srgb,etc2-rgb8a1unorm,etc2-rgb8a1unorm-srgb,etc2-rgba8unorm,etc2-rgba8unorm-srgb,eac-r11unorm,eac-r11snorm,eac-rg11unorm, andeac-rg11snorm formats.
• See theTier 1 and Tier 2 texture formats section for more information about those texture format sets and the requirements to create them.

labelOptional

A string providing a label that can be used to identify the object, for example inGPUError messages or console warnings.

mipLevelCountOptional

A number specifying the number of mip levels the texture will contain. If omitted, this defaults to 1.

sampleCountOptional

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.

For example, you can pass an array like[16, 16, 2], or its equivalent object{ width: 16, height: 16, depthOrArrayLayers: 2 }.

usage

Thebitwise flags representing the allowed usages for theGPUTexture. The possible values are in theGPUTexture.usage value table.

Note that multiple possible usages can be specified by separating values withbitwise OR, for example:GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.

Note:

• Thebgra8unorm-storagefeature needs to be enabled to specifySTORAGE_BINDING usage for abgra8unorm-formatGPUTexture.
• Therg11b10ufloat-renderablefeature needs to be enabled to specifyRENDER_ATTACHMENT usage for arg11b10ufloat-formatGPUTexture, as well as its blending and multisampling.

viewFormatsOptional

An array of enumerated values specifying othertexture formats permitted when callingGPUTexture.createView() on this texture, in addition to the texture format specified in itsformat value.

Return value

AGPUTexture object instance.

Validation

The following criteria must be met when callingcreateTexture(), otherwise aGPUValidationError is generated and an invalidGPUTexture object is returned:

• A validusage is specified.
• The values specified insize (width, height, or depth/array layer count) are greater than 0.
• mipLevelCount is greater than 0.
• sampleCount is equal to 1 or 4.
• Ifdimension is set to"1d":
  • Thesize width value is less than or equal to theGPUDevice'smaxTextureDimension1Dlimit.
  • Thesize height and depth/array layer count values are equal to 1.
  • ThesampleCount is equal to 1.
  • Theformat is not equal to acompressed format ordepth-or-stencil format.
• Ifdimension is set to"2d":
  • Thesize width and height values are less than or equal to theGPUDevice'smaxTextureDimension2Dlimit.
  • Thesize depth/array layer count value is less than or equal to theGPUDevice'smaxTextureArrayLayerslimit.
• Ifdimension is set to"3d":
  • Thesize width, and height, and depth/array layer count values are less than or equal to theGPUDevice'smaxTextureDimension3Dlimit.
  • ThesampleCount value is equal to 1.
  • Theformat is not equal to acompressed format ordepth-or-stencil format.
• Thesize width value is a multiple of thetexel block width.
• Thesize height value is a multiple of thetexel block height.
• IfsampleCount is greater than 1:
  • mipLevelCount is equal to 1.
  • Thesize 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.
• ThemipLevelCount value is less than or equal to themaximum miplevel count.
• The formats specified informat andviewFormats arecompatible with one another.
• Ifusage includes theGPUTextureUsage.RENDER_ATTACHMENT flag:
  • format is a renderable format (meaning a color renderable format, or adepth-or-stencil format).
  • dimension is set to"2d".
• Ifusage includes theGPUTextureUsage.STORAGE_BINDING flag:
  • The specifiedformat includes theSTORAGE_BINDING capability (see thePlain color formats table for reference).

Tier 1 and Tier 2 texture formats

This section describes the WebGPU Tier1 and Tier2 texture formats.

Tier 1

The Tier 1 set of texture formats is designed to allow developers to port existing content to the web without needing to rewrite it to use WebGPU's lower-level capabilities. To use this set, enable thetexture-formats-tier1 feature (seeGPUSupportedFeatures).

Enabling this feature allows:

• Using the followingformats withusages ofRENDER_ATTACHMENT (including blendable and multisampling capabilities) andSTORAGE_BINDING (withread-only andwrite-onlyaccess):
  • r16unorm
  • r16snorm
  • rg16unorm
  • rg16snorm
  • rgba16unorm
  • rgba16snorm
• Using the followingformats with theRENDER_ATTACHMENTusage (including blendable and multisampling capabilities):
  • r8snorm
  • rg8snorm
  • rgba8snorm
• Using the followingformats with theSTORAGE_BINDINGusage (withread-only andwrite-onlyaccess):
  • r8unorm
  • r8snorm
  • r8uint
  • r8sint
  • rg8unorm
  • rg8snorm
  • rg8uint
  • rg8sint
  • r16uint
  • r16sint
  • r16float
  • rg16uint
  • rg16sint
  • rg16float
  • rgb10a2uint
  • rgb10a2unorm
  • rg11b10ufloat
• Using the followingGPUTexture formats in the destinationtexture ofGPUQueue.copyExternalImageToTexture() calls:
  • r16unorm
  • rg16unorm
  • rgba16unorm

Tier2

The Tier 2 set of texture formats supports storage texture formats that don't have support in "core" WebGPU, and are required for advanced usage. To use this set, enable thetexture-formats-tier2 feature (seeGPUSupportedFeatures).

Enabling this feature allows using the followingformats with theSTORAGE_BINDINGusage (withread-writeaccess):

• r8unorm
• r8uint
• r8sint
• rgba8unorm
• rgba8uint
• rgba8sint
• r16uint
• r16sint
• r16float
• rgba16uint
• rgba16sint
• rgba16float
• rgba32uint
• rgba32sint
• rgba32float

Examples

In the WebGPU samplesTextured Cube sample, a texture to use on the faces of a cube is created by:

• Loading the image into anHTMLImageElement and creating an image bitmap usingcreateImageBitmap().
• Creating a new texture usingcreateTexture().
• Copying the image bitmap into the texture usingGPUQueue.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],  );}// …

Specifications

Browser compatibility

See also

• TheWebGPU API