ThecreateView() method of theGPUTexture interface creates aGPUTextureView representing a specific view of theGPUTexture.

Syntax

createView()createView(descriptor)

Parameters

descriptorOptional

An object containing the following properties:

arrayLayerCountOptional

A number defining how many array layers are accessible to the view, starting with thebaseArrayLayer value.

IfarrayLayerCount is omitted, it is given a value as follows:

• Ifdimension is"1d","2d", or"3d",arrayLayerCount is 1.
• Ifdimension is"cube",arrayLayerCount is 6.
• Ifdimension is"2d-array", or"cube-array",arrayLayerCount isGPUTexture.depthOrArrayLayers -baseArrayLayer.

aspectOptional

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 adepth-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".

baseArrayLayerOptional

A number defining the index of the first array layer accessible to the view. If omitted,baseArrayLayer takes a value of 0.

baseMipLevelOptional

A number representing the first (most detailed) mipmap level accessible to the view. If omitted,baseMipLevel takes a value of 0.

dimensionOptional

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.

Ifdimension is omitted, it is given a value as follows:

• IfGPUTexture.dimension is"1d",dimension is"1d".
• IfGPUTexture.dimension is"2d" andGPUTexture.depthOrArrayLayers is 1,dimension is"2d".
• IfGPUTexture.dimension is"2d" andGPUTexture.depthOrArrayLayers is more than 1,dimension is"2d-array".
• IfGPUTexture.dimension is"3d",dimension is"3d".

formatOptional

An enumerated value specifying the format of the texture view. See theTexture formats section of the specification for all the possible values.

Ifformat is omitted, it will be given a value as follows:

• Ifaspect is"depth-only" or"stencil-only", andGPUTexture.format is adepth-or-stencil format,format will be set equal to the appropriateaspect-specific format.
• Otherwise it will be set equal toGPUTexture.format.

labelOptional

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

mipLevelCountOptional

A number defining how many mipmap levels are accessible to the view, starting with thebaseMipLevel value.

IfmipLevelCount is omitted, it will be given a value ofGPUTexture.mipLevelCount -baseMipLevel.

swizzleOptional

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 of0.

1

Enforces a value of1.

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 theswizzle property, you must enable thetexture-component-swizzlefeature in yourGPUDevice by specifying it in therequiredFeatures array of theGPUAdapter.requestDevice() descriptor. If this feature is not enabled, theswizzle property will have no effect.

usageOptional

A set ofbitwise flags representing a subset of the source texture's usage flags (available in theGPUTexture.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 theGPUTexture.usage value table.

The default value is0, which represents the source texture's full set of usage flags. If the view'sformat doesn't support all of the texture's usages, the default will fail, and the view's usage must be specified explicitly.

Return value

AGPUTextureView object instance.

Validation

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

• Ifaspect is"all",format is equal toGPUTexture.format, or one of theviewFormats specified in the originatingGPUDevice.createTexture() call's descriptor object.
• Ifaspect is"depth-only" or"stencil-only",format is equal to the appropriateaspect-specific format of thedepth-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".
• IfsampleCount is greater than 1,dimension is"2d".
• Ifdimension 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 6
    • GPUTexture.width is equal toGPUTexture.height
  • "cube-array"
    • GPUTexture.dimension is"2d"
    • arrayLayerCount is a multiple of 6
    • GPUTexture.width is equal toGPUTexture.height
  • "3d"
    • GPUTexture.dimension is"3d"
    • arrayLayerCount is 1
• The view'sformat supports all of the usages specified in theusage property.

Examples

TypicalcreateView() usage

In the WebGPU SamplesCubemap demo, you will see multiple examples of howcreateView() is used, both as to create a viewresource for aGPUDevice.createBindGroup() call, and to provide aview in thedepthStencilAttachment object of aGPUCommandEncoder.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);// …

createView() with usage restriction

In this snippet, we create a texture and then create a view that has its usage restricted via theusage 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

• TheWebGPU API