WebGPU API
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
createTexture(descriptor)
Parameters
descriptor- : An object containing the following properties:
-
dimension-
: 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.
dimensiondefaults 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.
[!NOTE]
- The
depth32float-stencil8feature needs to be enabled to createdepth32float-stencil8-format GPUTextures. - The
texture-compression-bcfeature 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-srgbformats. - The
texture-compression-bcandtexture-compression-bc-sliced-3dfeatures need to be enabled to create three-dimensional BC compressedGPUTextures (the sameformatvalues specified in the previous bullet, but withdimensionset to3d). - The
texture-compression-astcfeature 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-srgbformats. - The
texture-compression-astcandtexture-compression-astc-sliced-3dfeatures need to be enabled to create three-dimensional BC compressedGPUTextures (the sameformatvalues specified in the previous bullet, but withdimensionset to3d). - The
texture-compression-etc2feature 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-rg11snormformats. - See the Tier 1 and Tier 2 texture formats section for more information about those texture format sets and the requirements to create them.
- The
-
-
label- : A string providing a label that can be used to identify the object, for example in GPUError messages or console warnings.
-
mipLevelCount- : A number specifying the number of mip levels the texture will contain. If omitted, this defaults to 1.
-
sampleCount- : 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-
: The Bitwise_flags representing the allowed usages for the
GPUTexture. The possible values are in theGPUTexture.usagevalue table.Note that multiple possible usages can be specified by separating values with bitwise OR, for example:
GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.[!NOTE]
-
-
viewFormats- : 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
formatvalue.
- : 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
-
- : An object containing the following properties:
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
usageis specified. - The values specified in
size(width, height, or depth/array layer count) are greater than 0. mipLevelCountis greater than 0.sampleCountis equal to 1 or 4.- If
dimensionis set to"1d":- The
sizewidth value is less than or equal to the GPUDevice'smaxTextureDimension1DGPUSupportedLimits. - The
sizeheight and depth/array layer count values are equal to 1. - The
sampleCountis equal to 1. - The
formatis not equal to a compressed format or depth-or-stencil format.
- The
- If
dimensionis set to"2d":- The
sizewidth and height values are less than or equal to the GPUDevice'smaxTextureDimension2DGPUSupportedLimits. - The
sizedepth/array layer count value is less than or equal to the GPUDevice'smaxTextureArrayLayersGPUSupportedLimits.
- The
- If
dimensionis set to"3d":- The
sizewidth, and height, and depth/array layer count values are less than or equal to the GPUDevice'smaxTextureDimension3DGPUSupportedLimits. - The
sampleCountvalue is equal to 1. - The
formatis not equal to a compressed format or depth-or-stencil format.
- The
- The
sizewidth value is a multiple of the texel block width. - The
sizeheight value is a multiple of the texel block height. - If
sampleCountis greater than 1:mipLevelCountis equal to 1.- The
sizedepth/array layer count value is equal to 1. usageincludes theGPUTextureUsage.RENDER_ATTACHMENTflag.usagedoes not include theGPUTextureUsage.STORAGE_BINDINGflag.- The specified format supports multi-sampling.
- The
mipLevelCountvalue is less than or equal to the maximum miplevel count. - The formats specified in
formatandviewFormatsare compatible with one another. - If
usageincludes theGPUTextureUsage.RENDER_ATTACHMENTflag:formatis a renderable format (meaning a color renderable format, or a depth-or-stencil format).dimensionis set to"2d".
- If
usageincludes theGPUTextureUsage.STORAGE_BINDINGflag:- The specified
formatincludes theSTORAGE_BINDINGcapability (see the Plain color formats table for reference).
- The specified
- If
usageincludes theGPUTextureUsage.TRANSIENT_ATTACHMENTflag:usageis equal toTRANSIENT_ATTACHMENT | RENDER_ATTACHMENT.dimensionis equal to"2d".mipLevelCountis equal to1.size.depthOrArrayLayersis equal to1.
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 the texture-formats-tier1 feature (see GPUSupportedFeatures).
Enabling this feature allows:
- Using the following
formatswithusagesofRENDER_ATTACHMENT(including blendable and multisampling capabilities) andSTORAGE_BINDING(withread-onlyandwrite-onlyaccess):r16unormr16snormrg16unormrg16snormrgba16unormrgba16snorm
- Using the following
formatswith theRENDER_ATTACHMENTusage(including blendable and multisampling capabilities):r8snormrg8snormrgba8snorm
- Using the following
formatswith theSTORAGE_BINDINGusage(withread-onlyandwrite-onlyaccess):r8unormr8snormr8uintr8sintrg8unormrg8snormrg8uintrg8sintr16uintr16sintr16floatrg16uintrg16sintrg16floatrgb10a2uintrgb10a2unormrg11b10ufloat
- Using the following
GPUTextureformats in the destinationtextureof GPUQueue.copyExternalImageToTexture() calls:r16unormrg16unormrgba16unorm
[!NOTE] Enabling the
texture-formats-tier1feature automatically enables therg11b10ufloat-renderablefeature, which allows therg11b10ufloattexture to be used with theRENDER_ATTACHMENTusage, including blending and multisampling.
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 the texture-formats-tier2 feature (see GPUSupportedFeatures).
Enabling this feature allows using the following formats with the STORAGE_BINDING usage (with read-write access):
r8unormr8uintr8sintrgba8unormrgba8uintrgba8sintr16uintr16sintr16floatrgba16uintrgba16sintrgba16floatrgba32uintrgba32sintrgba32float
[!NOTE] Enabling the
texture-formats-tier2feature automatically enables therg11b10ufloat-renderableandtexture-formats-tier1features.
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 using Window.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],
);
}
// …
Specifications
Browser compatibility
See also
- The WebGPU API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
