GPUDevice: createTexture() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("WebGPU API")}}{{SecureContext_Header}}{{AvailableInWorkers}}
The **createTexture()** method of the {{domxref("GPUDevice")}} interface creates a {{domxref("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{{optional_inline}}- : 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.
توجه: - The depth32float-stencil8 feature needs to be enabled to create depth32float-stencil8-format {{domxref("GPUTexture")}}s. - The texture-compression-bc feature needs to be enabled to create two-dimensional (dimension: "2d") BC compressed GPUTextures: 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, and bc7-rgba-unorm-srgb formats. - The texture-compression-bc and texture-compression-bc-sliced-3d features need to be enabled to create three-dimensional BC compressed GPUTextures (the same format values specified in the previous bullet, but with dimension set to 3d). - The texture-compression-astc feature needs to be enabled to create two-dimensional (dimension: "2d") ASTC compressed GPUTextures: 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, and astc-12x12-unorm-srgb formats. - The texture-compression-astc and texture-compression-astc-sliced-3d features need to be enabled to create three-dimensional BC compressed GPUTextures (the same format values specified in the previous bullet, but with dimension set to 3d). - The texture-compression-etc2 feature needs to be enabled to create two-dimensional ETC2 compressed GPUTextures: etc2-rgb8unorm, etc2-rgb8unorm-srgb, etc2-rgb8a1unorm, etc2-rgb8a1unorm-srgb, etc2-rgba8unorm, etc2-rgba8unorm-srgb, eac-r11unorm, eac-r11snorm, eac-rg11unorm, and eac-rg11snorm formats. - See the Tier 1 and Tier 2 texture formats section for more information about those texture format sets and the requirements to create them.
label{{optional_inline}}- : A string providing a label that can be used to identify the object, for example in {{domxref("GPUError")}} messages or console warnings.
mipLevelCount{{optional_inline}}- : A number specifying the number of mip levels the texture will contain. If omitted, this defaults to 1.
sampleCount{{optional_inline}}- : 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 {{glossary("Bitwise_flags", "bitwise flags")}} representing the allowed usages for the
GPUTexture. The possible values are in the [GPUTexture.usagevalue table](/en-US/docs/Web/API/GPUTexture/usage#value).
Note that multiple possible usages can be specified by separating values with bitwise OR, for example: GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT.
توجه: - The bgra8unorm-storage feature needs to be enabled to specify STORAGE_BINDING usage for a bgra8unorm-[format](#format) {{domxref("GPUTexture")}}. - The rg11b10ufloat-renderable feature needs to be enabled to specify RENDER_ATTACHMENT usage for a rg11b10ufloat-[format](#format) {{domxref("GPUTexture")}}, as well as its blending and multisampling.
viewFormats{{optional_inline}}- : An array of enumerated values specifying other texture formats permitted when calling {{domxref("GPUTexture.createView()")}} on this texture, in addition to the texture format specified in its
formatvalue.
Return value
A {{domxref("GPUTexture")}} object instance.
Validation
The following criteria must be met when calling **createTexture()**, otherwise a {{domxref("GPUValidationError")}} is generated and an invalid {{domxref("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 {{domxref("GPUDevice")}}'smaxTextureDimension1D{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - 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. - If
dimensionis set to"2d": - The
sizewidth and height values are less than or equal to the {{domxref("GPUDevice")}}'smaxTextureDimension2D{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - The
sizedepth/array layer count value is less than or equal to the {{domxref("GPUDevice")}}'smaxTextureArrayLayers{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - If
dimensionis set to"3d": - The
sizewidth, and height, and depth/array layer count values are less than or equal to the {{domxref("GPUDevice")}}'smaxTextureDimension3D{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - The
sampleCountvalue is equal to 1. - The
formatis not equal to a compressed format or depth-or-stencil format. - 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). - 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 {{domxref("GPUSupportedFeatures")}}).
Enabling this feature allows:
- Using the following [
formats](#format) with [usages](#usage) ofRENDER_ATTACHMENT(including blendable and multisampling capabilities) andSTORAGE_BINDING(withread-onlyandwrite-only[access](/en-US/docs/Web/API/GPUDevice/createBindGroupLayout#access)): r16unormr16snormrg16unormrg16snormrgba16unormrgba16snorm- Using the following [
formats](#format) with theRENDER_ATTACHMENT[usage](#usage) (including blendable and multisampling capabilities): r8snormrg8snormrgba8snorm- Using the following [
formats](#format) with theSTORAGE_BINDING[usage](#usage) (withread-onlyandwrite-only[access](/en-US/docs/Web/API/GPUDevice/createBindGroupLayout#access)): r8unormr8snormr8uintr8sintrg8unormrg8snormrg8uintrg8sintr16uintr16sintr16floatrg16uintrg16sintrg16floatrgb10a2uintrgb10a2unormrg11b10ufloat- Using the following
GPUTextureformats in the destination [texture](/en-US/docs/Web/API/GPUQueue/copyExternalImageToTexture#texture) of {{domxref("GPUQueue.copyExternalImageToTexture()")}} calls: r16unormrg16unormrgba16unorm
توجه: Enabling the texture-formats-tier1 feature automatically enables the rg11b10ufloat-renderable feature, which allows the rg11b10ufloat texture to be used with the RENDER_ATTACHMENT usage, 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 {{domxref("GPUSupportedFeatures")}}).
Enabling this feature allows using the following [formats](#format) with the STORAGE_BINDING [usage](#usage) (with read-write [access](/en-US/docs/Web/API/GPUDevice/createBindGroupLayout#access)):
r8unormr8uintr8sintrgba8unormrgba8uintrgba8sintr16uintr16sintr16floatrgba16uintrgba16sintrgba16floatrgba32uintrgba32sintrgba32float
توجه: Enabling the texture-formats-tier2 feature automatically enables the rg11b10ufloat-renderable and texture-formats-tier1 features.
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 {{domxref("HTMLImageElement")}} and creating an image bitmap using {{domxref("Window.createImageBitmap", "createImageBitmap()")}}.
- Creating a new texture using
createTexture(). - Copying the image bitmap into the texture using {{domxref("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
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- The WebGPU API