GPUDevice: createBindGroupLayout() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
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.
Note: This feature is available in Web Workers.
The createBindGroupLayout()
method of the
GPUDevice
interface creates a GPUBindGroupLayout
that defines the structure and purpose of related GPU resources such as buffers that will be used in a pipeline, and is used as a template when creating GPUBindGroup
s.
Syntax
createBindGroupLayout(descriptor)
Parameters
descriptor
-
An object containing the following properties:
entries
-
An array of entry objects, each one of which describes a single shader resource binding to be included in the
GPUBindGroupLayout
. Each entry will correspond to an entry defined in aGPUBindGroup
(created via aGPUDevice.createBindGroup()
call) that uses thisGPUBindGroupLayout
object as a template. label
Optional-
A string providing a label that can be used to identify the object, for example in
GPUError
messages or console warnings.
Entry objects
An entry object includes the following properties:
binding
-
A number representing a unique identifier for this particular entry, which matches the
binding
value of a correspondingGPUBindGroup
entry. In addition, it matches then
index value of the corresponding@binding(n)
attribute in the shader (GPUShaderModule
) used in the related pipeline. visibility
-
One or more bitwise flags defining the shader stages that a
GPUBindGroup
entry corresponding to this entry will be visible to. Possible values are:GPUShaderStage.COMPUTE
: The bind group entry will be accessible to compute shaders.GPUShaderStage.FRAGMENT
: The bind group entry will be accessible to fragment shaders.GPUShaderStage.VERTEX
: The bind group entry will be accessible to vertex shaders.
Note that multiple stages can be specified by separating values with pipe symbols, for example:
jsvisibility: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX;
- "Resource layout object"
-
An object that defines the required binding resource type and structure of the
GPUBindGroup
entry corresponding to this entry. This property can be one ofbuffer
,externalTexture
,sampler
,storageTexture
, ortexture
, the object structures of which are described in the next section.
Resource layout objects
The resource layout object can be one of the following (see also GPUDevice.createBindGroup()
for details of how the required resources for each entry are structured):
-
buffer
: Indicates that the correspondingGPUBindGroup
entry will be aGPUBufferBinding
object, which contains aGPUBuffer
plusoffset
andsize
values. Abuffer
resource layout object can contain the following properties:hasDynamicOffset
Optional-
A boolean. If set to
true
, it indicates that this binding requires a dynamic offset, for example as set during aGPURenderPassEncoder.setBindGroup()
call. If omitted,hasDynamicOffset
defaults tofalse
. minBindingSize
Optional-
A number indicating the minimum allowed size, in bytes, of bound buffers. If omitted,
minBindingSize
defaults to 0. If the value is 0, minimum buffer size is ignored during pipeline creation and is instead validated by issued draw/dispatch commands. type
Optional-
An enumerated value specifying the required type for
GPUBuffer
s bound to this binding (seeGPUDevice.createBuffer()
for more information on buffer types). Possible values are:"read-only-storage"
: A read-only buffer created with ausage
ofGPUBufferUsage.STORAGE
."storage"
: A writable buffer created with ausage
ofGPUBufferUsage.STORAGE
."uniform"
: A buffer created with ausage
ofGPUBufferUsage.UNIFORM
.
If omitted,
type
defaults to"uniform"
.
-
externalTexture
: Indicates that the correspondingGPUBindGroup
entry will be aGPUExternalTexture
object. AnexternalTexture
resource layout object is empty —{}
. -
sampler
: Indicates that the correspondingGPUBindGroup
entry will be aGPUSampler
object. Asampler
resource layout object can contain the following properties:type
Optional-
An enumerated value specifying the required type for
GPUSampler
s bound to this binding (seeGPUDevice.createSampler()
for more information on sampler types). Possible values are:"comparison"
: A comparison sampler."filtering"
: A filtering sampler."non-filtering"
: A non-filtering sampler.
If omitted,
type
defaults to"filtering"
.
-
storageTexture
: Indicates that the correspondingGPUBindGroup
entry will be aGPUTextureView
object. AstorageTexture
resource layout object can contain the following properties:access
Optional-
An enumerated value specifying whether texture views bound to this binding will be bound for read and/or write access. Possible values are currently
"write-only"
andundefined
, with the intention to add more access modes in the future. If omitted, the default value is"write-only"
. format
-
An enumerated value specifying the required format of texture views bound to this binding. See the specification's Texture Formats section for all the available
format
values. viewDimension
Optional-
An enumerated value specifying the required dimension for texture views bound to this binding. 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 ofn
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 omitted,
viewDimension
defaults to"2d"
.
-
texture
: Indicates that the correspondingGPUBindGroup
entry will be aGPUTextureView
object. Atexture
resource layout object can contain the following properties:multisampled
Optional-
A boolean. A value of
true
indicates that texture views bound to this binding must be multi-sampled. If omitted,multisampled
defaults tofalse
. sampleType
Optional-
An enumerated value specifying the sample type required for texture views bound to this binding (see
GPUDevice.createTexture()
for more information on texture view types). Possible values are:"depth"
"float"
"sint"
"uint"
"unfilterable-float"
If omitted,
sampleType
defaults to"float"
. viewDimension
Optional-
An enumerated value specifying the required dimension for texture views bound to this binding. Possible and default values are the same as for
storageTexture
resource layout objects — see above.
Return value
A GPUBindGroupLayout
object instance.
Validation
The following criteria must be met when calling createBindGroupLayout()
, otherwise a GPUValidationError
is generated and an invalid GPUBindGroupLayout
object is returned:
- Each entry's
binding
value is unique. - Each entry's
binding
value is less than theGPUDevice
'smaxBindingsPerBindGroup
limit. - The number of entries does not exceed the binding slot limits.
- Only 1 resource layout object is defined per entry.
- If an entry's
visibility
includesGPUShaderStage.VERTEX
:- If its resource layout object is a
buffer
, itstype
is not"storage"
. - Its resource layout object is not a
storageTexture
.
- If its resource layout object is a
- If an entry's resource layout object is a
texture
, and itsmultisampled
value istrue
:- Its
viewDimension
is"2d"
. - Its
sampleType
is not"float"
.
- Its
- If an entry's resource layout object is a
storageTexture
:- Its
viewDimension
is not"cube"
or"cube-array"
. - Its
format
is a format that supports storage usage.
- Its
Examples
Note: The WebGPU samples feature many more examples.
Basic example
Our basic compute demo shows an example of creating a bind group layout and then using that as a template when creating a bind group.
// ...
const bindGroupLayout = device.createBindGroupLayout({
entries: [
{
binding: 0,
visibility: GPUShaderStage.COMPUTE,
buffer: {
type: "storage",
},
},
],
});
const bindGroup = device.createBindGroup({
layout: bindGroupLayout,
entries: [
{
binding: 0,
resource: {
buffer: output,
},
},
],
});
// ...
Specifications
Specification |
---|
WebGPU # dom-gpudevice-createbindgrouplayout |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API