WebGPU API
The createView() method of the
GPUTexture interface creates a GPUTextureView representing a specific view of the GPUTexture.
Syntax
createView()
createView(descriptor)
Parameters
descriptor- : An object containing the following properties:
-
arrayLayerCount-
: A number defining how many array layers are accessible to the view, starting with the
baseArrayLayervalue.If
arrayLayerCountis omitted, it is given a value as follows:- If
dimensionis"1d","2d", or"3d",arrayLayerCountis 1. - If
dimensionis"cube",arrayLayerCountis 6. - If
dimensionis"2d-array", or"cube-array",arrayLayerCountis GPUTexture.depthOrArrayLayers -baseArrayLayer.
- If
-
-
aspect-
: An enumerated value specifying which aspect(s) of the texture are accessible to the texture view. Possible values are:
"all"- : All available aspects of the texture format will be accessible to the view, which can mean all or any of color, depth, and stencil, depending on what kind of format you are dealing with.
"depth-only"- : Only the depth aspect of a depth-or-stencil format will be accessible to the view.
"stencil-only"- : Only the stencil aspect of a depth-or-stencil format will be accessible to the view.
If omitted,
aspecttakes a value of"all".
-
-
baseArrayLayer- : A number defining the index of the first array layer accessible to the view. If omitted,
baseArrayLayertakes a value of 0.
- : A number defining the index of the first array layer accessible to the view. If omitted,
-
baseMipLevel- : A number representing the first (most detailed) mipmap level accessible to the view. If omitted,
baseMipLeveltakes a value of 0.
- : A number representing the first (most detailed) mipmap level accessible to the view. If omitted,
-
dimension-
: An enumerated value specifying the format to view the texture as. Possible values are:
"1d": The texture is viewed as a one-dimensional image."2d": The texture is viewed as a single two-dimensional image."2d-array": The texture is viewed as an array of two-dimensional images."cube": The texture is viewed as a cubemap. The view has 6 array layers, corresponding to the[+X, -X, +Y, -Y, +Z, -Z]faces of the cube. Sampling is done seamlessly across the faces of the cubemap."cube-array": The texture is viewed as a packed array of N cubemaps, each with 6 array layers corresponding to the[+X, -X, +Y, -Y, +Z, -Z]faces of the cube. Sampling is done seamlessly across the faces of the cubemaps."3d": The texture is viewed as a three-dimensional image.
If
dimensionis omitted, it is given a value as follows:- If GPUTexture.dimension is
"1d",dimensionis"1d". - If GPUTexture.dimension is
"2d"and GPUTexture.depthOrArrayLayers is 1,dimensionis"2d". - If GPUTexture.dimension is
"2d"and GPUTexture.depthOrArrayLayers is more than 1,dimensionis"2d-array". - If GPUTexture.dimension is
"3d",dimensionis"3d".
-
-
format-
: An enumerated value specifying the format of the texture view. See the Texture formats section of the specification for all the possible values.
If
formatis omitted, it will be given a value as follows:- If
aspectis"depth-only"or"stencil-only", and GPUTexture.format is a depth-or-stencil format,formatwill be set equal to the appropriate aspect-specific format. - Otherwise it will be set equal to GPUTexture.format.
- If
-
-
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 defining how many mipmap levels are accessible to the view, starting with the
baseMipLevelvalue.If
mipLevelCountis omitted, it will be given a value of GPUTexture.mipLevelCount -baseMipLevel.
-
-
swizzle-
: A string containing four characters. The position of each character maps to the texture view's red, green, blue, and alpha channel values, respectively. The value of each character specifies the value each of those channels will take when the view is accessed by a shader. Possible values are:
r- : The texture's red channel value.
g- : The texture's green channel value.
b- : The texture's blue channel value.
a- : The texture's alpha channel value.
0- : Enforces a value of
0.
- : Enforces a value of
1- : Enforces a value of
1.
- : Enforces a value of
For example,
swizzle: "grba"would result in the texture's red and green channel values being swapped when a shader accesses the view. Texture component swizzle allows developers to optimize performance, correct component ordering mismatches, and reuse shader code across various texture formats when sampling textures.[!NOTE] To use the
swizzleproperty, you must enable thetexture-component-swizzlefeature in your GPUDevice by specifying it in therequiredFeaturesarray of the GPUAdapter.requestDevice() descriptor. If this feature is not enabled, theswizzleproperty will have no effect.
-
-
usage-
: A set of bitwise flags representing a subset of the source texture's usage flags (available in the GPUTexture.usage property) that are compatible with the chosen view format. This can be used to restrict the allowed view usage in cases where the view format is incompatible with certain usages. The available usage flags are listed in the
GPUTexture.usagevalue table.The default value is
0, which represents the source texture's full set of usage flags. If the view'sformatdoesn't support all of the texture's usages, the default will fail, and the view's usage must be specified explicitly.
-
-
- : An object containing the following properties:
Return value
A GPUTextureView object instance.
Validation
The following criteria must be met when calling createView(), otherwise a GPUValidationError is generated and an invalid GPUTextureView object is returned:
- If
aspectis"all",formatis equal to GPUTexture.format, or one of theviewFormatsspecified in the originating GPUDevice.createTexture() call's descriptor object. - If
aspectis"depth-only"or"stencil-only",formatis equal to the appropriate aspect-specific format of the depth-or-stencil format. mipLevelCountis greater than 0.mipLevelCount+baseMipLevelis less than or equal to GPUTexture.mipLevelCount.arrayLayerCountis greater than 0.arrayLayerCount+baseArrayLayeris less than or equal to GPUTexture.depthOrArrayLayers if GPUTexture.dimension is"2d", or less than or equal to 1 if GPUTexture.dimension is"1d"or"3d".- If
sampleCountis greater than 1,dimensionis"2d". - If
dimensionis:"1d"- GPUTexture.dimension is
"1d" arrayLayerCountis 1
- GPUTexture.dimension is
"2d"- GPUTexture.dimension is
"2d" arrayLayerCountis 1
- GPUTexture.dimension is
"2d-array"- GPUTexture.dimension is
"2d"
- GPUTexture.dimension is
"cube"- GPUTexture.dimension is
"2d" arrayLayerCountis 6- GPUTexture.width is equal to GPUTexture.height
- GPUTexture.dimension is
"cube-array"- GPUTexture.dimension is
"2d" arrayLayerCountis a multiple of 6- GPUTexture.width is equal to GPUTexture.height
- GPUTexture.dimension is
"3d"- GPUTexture.dimension is
"3d" arrayLayerCountis 1
- GPUTexture.dimension is
- The view's
formatsupports all of the usages specified in theusageproperty.
Examples
Typical createView() usage
In the WebGPU Samples Cubemap demo, you will see multiple examples of how createView() is used, both as to create a view resource for a GPUDevice.createBindGroup() call, and to provide a view in the depthStencilAttachment object of a GPUCommandEncoder.beginRenderPass() descriptor.
const uniformBindGroup = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [
{
binding: 0,
resource: {
buffer: uniformBuffer,
offset: 0,
size: uniformBufferSize,
},
},
{
binding: 1,
resource: sampler,
},
{
binding: 2,
resource: cubemapTexture.createView({
dimension: "cube",
}),
},
],
});
const renderPassDescriptor = {
colorAttachments: [
{
view: undefined, // Assigned later
loadOp: "clear",
storeOp: "store",
},
],
depthStencilAttachment: {
view: depthTexture.createView(),
depthClearValue: 1.0,
depthLoadOp: "clear",
depthStoreOp: "store",
},
};
// …
const commandEncoder = device.createCommandEncoder();
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);
// …
createView() with usage restriction
In this snippet, we create a texture and then create a view that has its usage restricted via the usage property.
const texture = myDevice.createTexture({
size: [4, 4],
format: "rgba8unorm",
usage:
GPUTextureUsage.RENDER_ATTACHMENT |
GPUTextureUsage.TEXTURE_BINDING |
GPUTextureUsage.STORAGE_BINDING,
viewFormats: ["rgba8unorm-srgb"],
});
const view = texture.createView({
format: "rgba8unorm-srgb",
usage: GPUTextureUsage.RENDER_ATTACHMENT, // Restrict allowed usage
});
Specifications
Browser compatibility
See also
- The WebGPU API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
