GPUDevice: createBindGroup() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The createBindGroup()
method of the
GPUDevice
interface creates a GPUBindGroup
based on a GPUBindGroupLayout
that defines a set of resources to be bound together in a group and how those resources are used in shader stages.
Syntax
js
createBindGroup(descriptor)
Parameters
descriptor
-
An object containing the following properties:
entries
-
An array of entry objects describing the resources to expose to the shader. There will be one for each corresponding entry described by the
GPUBindGroupLayout
referenced inlayout
. Each entry object has the following properties:binding
-
A number representing a unique identifier for this resource binding, which matches the
binding
value of a correspondingGPUBindGroupLayout
entry. In addition, it matches then
index value of the corresponding@binding(n)
attribute in the shader (GPUShaderModule
) used in the related pipeline. resource
-
The resource to bind. This can be one of the following:
GPUBufferBinding
(which wraps aGPUBuffer
; see GPUBufferBinding objects for a definition)GPUExternalTexture
GPUSampler
GPUTextureView
label
Optional-
A string providing a label that can be used to identify the object, for example in
GPUError
messages or console warnings. layout
-
The
GPUBindGroupLayout
that theentries
of this bind group will conform to.
GPUBufferBinding objects
A GPUBufferBinding
object can contain the following properties:
buffer
-
The
GPUBuffer
object you want to bind. offset
Optional-
The offset, in bytes, from the beginning of the
buffer
to the beginning of the range exposed to the shader by the buffer binding. If omitted,offset
defaults to 0. size
Optional-
The size, in bytes, of the buffer binding. If omitted,
size
will be the range starting atoffset
and ending at the end of thebuffer
. If bothoffset
andsize
are omitted, the entire buffer is exposed to the shader.
Return value
A GPUBindGroup
object instance.
Validation
The following criteria must be met when calling createBindGroup()
, otherwise a GPUValidationError
is generated and an invalid GPUBindGroup
object is returned:
- The number of entries in the
layout
GPUBindGroupLayout
equals the number of entry objects inentries
. - For each entry in the
layout
GPUBindGroupLayout
, the corresponding entry object inentries
binds the correct resource type. For example, abuffer
resource layout object has aGPUBufferBinding
object specified in the corresponding binding. - If the resource layout object is a
buffer
:- The corresponding bound
GPUBuffer
:- Has its bound part (as specified by
offset
andsize
) contained inside it completely, with a non-zero size. - Has a size bigger than the
buffer
resource layout'sminBindingSize
.
- Has its bound part (as specified by
- If the resource layout object
type
is"uniform"
:- The bound
GPUBuffer
has ausage
that includesGPUBufferUsage.UNIFORM
. - The effective size of the bound buffer segment is less than or equal to the
GPUDevice
'smaxUniformBufferBindingSize
limit. - The specified
GPUBufferBinding
offset
is a multiple of theGPUDevice
'sminUniformBufferOffsetAlignment
limit.
- The bound
- If the resource layout object
type
is"storage"
or"read-only-storage"
:- The bound
GPUBuffer
has ausage
that includesGPUBufferUsage.STORAGE
. - The effective size of the bound buffer segment is less than or equal to the
GPUDevice
'smaxStorageBufferBindingSize
limit. - The effective size of the bound buffer segment is a multiple of 4.
- The specified
GPUBufferBinding
offset
is a multiple of theGPUDevice
'sminStorageBufferOffsetAlignment
limit.
- The bound
- The corresponding bound
- If the resource layout object is a
storageTexture
, the corresponding boundGPUTextureView
:- Has a
dimension
equal to the resource layout object'sviewDimension
(seeGPUTexture.createView()
for more details of a texture view's settings). - Has a
format
equal to the resource layout object'ssampleType
. - Has a
mipLevelCount
equal to 1. - Is a view of a
GPUTexture
with ausage
that includesGPUTextureUsage.STORAGE_BINDING
.
- Has a
- If the resource layout object is a
texture
, the corresponding boundGPUTextureView
:- Has a
dimension
equal to the resource layout object'sviewDimension
(seeGPUTexture.createView()
for more details of a texture view's settings). - Has a
format
compatible with the resource layout object'ssampleType
. - Is a view of a
GPUTexture
with ausage
that includesGPUTextureUsage.TEXTURE_BINDING
. - is a view of a
GPUTexture
with asampleCount
greater than 1 if the resource layout object'smultisampled
property istrue
, or equal to 1 if it isfalse
.
- Has a
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.
js
// ...
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-createbindgroup |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API