GPUTexture: createView() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The createView()
method of the
GPUTexture
interface creates a GPUTextureView
representing a specific view of the GPUTexture
.
Syntax
createView()
createView(descriptor)
Parameters
descriptor
Optional-
An object containing the following properties:
arrayLayerCount
Optional-
A number defining how many array layers are accessible to the view, starting with the
baseArrayLayer
value.If
arrayLayerCount
is omitted, it is given a value as follows:- If
dimension
is"1d"
,"2d"
, or"3d"
,arrayLayerCount
is 1. - If
dimension
is"cube"
,arrayLayerCount
is 6. - If
dimension
is"2d-array"
, or"cube-array"
,arrayLayerCount
isGPUTexture.depthOrArrayLayers
-baseArrayLayer
.
- If
aspect
Optional-
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,
aspect
takes a value of"all"
. baseArrayLayer
Optional-
A number defining the index of the first array layer accessible to the view. If omitted,
baseArrayLayer
takes a value of 0. baseMipLevel
Optional-
A number representing the first (most detailed) mipmap level accessible to the view. If omitted,
baseMipLevel
takes a value of 0. dimension
Optional-
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
dimension
is omitted, it is given a value as follows:- If
GPUTexture.dimension
is"1d"
,dimension
is"1d"
. - If
GPUTexture.dimension
is"2d"
andGPUTexture.depthOrArrayLayers
is 1,dimension
is"2d"
. - If
GPUTexture.dimension
is"2d"
andGPUTexture.depthOrArrayLayers
is more than 1,dimension
is"2d-array"
. - If
GPUTexture.dimension
is"3d"
,dimension
is"3d"
.
format
Optional-
An enumerated value specifying the format of the texture view. See the Texture formats section of the specification for all the possible values.
If
format
is omitted, it will be given a value as follows:- If
aspect
is"depth-only"
or"stencil-only"
, andGPUTexture.format
is a depth-or-stencil format,format
will be set equal to the appropriate aspect-specific format. - Otherwise it will be set equal to
GPUTexture.format
.
- If
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 defining how many mipmap levels are accessible to the view, starting with the
baseMipLevel
value.If
mipLevelCount
is omitted, it will be given a value ofGPUTexture.mipLevelCount
-baseMipLevel
.
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
aspect
is"all"
,format
is equal toGPUTexture.format
, or one of theviewFormats
specified in the originatingGPUDevice.createTexture()
call's descriptor object. - If
aspect
is"depth-only"
or"stencil-only"
,format
is equal to the appropriate aspect-specific format of the depth-or-stencil format. mipLevelCount
is greater than 0.mipLevelCount
+baseMipLevel
is less than or equal toGPUTexture.mipLevelCount
.arrayLayerCount
is greater than 0.arrayLayerCount
+baseArrayLayer
is less than or equal toGPUTexture.depthOrArrayLayers
ifGPUTexture.dimension
is"2d"
, or less than or equal to 1 ifGPUTexture.dimension
is"1d"
or"3d"
.- If
sampleCount
is greater than 1,dimension
is"2d"
. - If
dimension
is:"1d"
GPUTexture.dimension
is"1d"
arrayLayerCount
is 1
"2d"
GPUTexture.dimension
is"2d"
arrayLayerCount
is 1
"2d-array"
GPUTexture.dimension
is"2d"
"cube"
GPUTexture.dimension
is"2d"
arrayLayerCount
is 6GPUTexture.width
is equal toGPUTexture.height
"cube-array"
GPUTexture.dimension
is"2d"
arrayLayerCount
is a multiple of 6GPUTexture.width
is equal toGPUTexture.height
"3d"
GPUTexture.dimension
is"3d"
arrayLayerCount
is 1
Examples
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: GPURenderPassDescriptor = {
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);
// ...
Specifications
Specification |
---|
WebGPU # dom-gputexture-createview |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API