GPURenderPassEncoder: setBindGroup() 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 setBindGroup()
method of the
GPURenderPassEncoder
interface sets the GPUBindGroup
to use for subsequent render commands, for a given index.
Syntax
setBindGroup(index, bindGroup)
setBindGroup(index, bindGroup, dynamicOffsets)
setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart,
dynamicOffsetsLength)
Parameters
index
-
The index to set the bind group at. This matches the
n
index value of the corresponding@group(n)
attribute in the shader code (GPUShaderModule
) used in the related pipeline. bindGroup
-
The
GPUBindGroup
to use for subsequent render commands, ornull
, in which case any previously-set bind group in the given slot is unset. dynamicOffsets
Optional-
A value specifying the offset, in bytes, for each entry in
bindGroup
withhasDynamicOffset: true
set (i.e. in the descriptor of theGPUDevice.createBindGroupLayout()
call that created theGPUBindGroupLayout
object that thebindGroup
is based on). This value can be:- An array of numbers specifying the different offsets.
- A
Uint32Array
containing numbers specifying the offsets.
If a Uint32Array
value is specified for dynamicOffsets
, both of the following parameters are also required:
dynamicOffsetsStart
-
A number specifying the offset, in array elements, into
dynamicOffsetsData
, where the dynamic offset data begins. dynamicOffsetsLength
-
A number specifying the number of dynamic offset values to be read from in
dynamicOffsetsData
.
Return value
None (Undefined
).
Exceptions
For setBindGroup()
calls that use a Uint32Array
value for dynamicOffsets
, the call will throw with a RangeError
DOMException
if:
dynamicOffsetsStart
is less than 0.dynamicOffsetsStart
+dynamicOffsetsLength
is greater thandynamicOffsets.length
.
Validation
The following criteria must be met when calling setBindGroup()
, otherwise a GPUValidationError
is generated and the GPURenderPassEncoder
becomes invalid:
index
is less than or equal to theGPUDevice
'smaxBindGroups
limit.dynamicOffsets.length
is the same as the number of entries inbindGroup
withhasDynamicOffset: true
set.- For
bindGroup
entries where the boundbuffer
'stype
is"uniform"
(seeGPUDevice.createBindGroupLayout()
), each number indynamicOffsets
is a multiple of theGPUDevice
'sminUniformBufferOffsetAlignment
limit. - For
bindGroup
entries where the boundbuffer
'stype
is"storage"
or"read-only-storage"
(seeGPUDevice.createBindGroupLayout()
), each number indynamicOffsets
is a multiple of theGPUDevice
'sminStorageBufferOffsetAlignment
limit. - For each
bindGroup
entry, the boundbuffer
'soffset
, plus the corresponding layout entry'sminBindingSize
, plus the corresponding dynamic offset specified indynamicOffsets
, is less than or equal to the boundbuffer
'ssize
.
Examples
Set bind group
In the WebGPU Samples Textured Cube example, setBindGroup()
is used to bind the uniformBindGroup
to index position 0. Check out the example for the full context.
// ...
const commandEncoder = device.createCommandEncoder();
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);
passEncoder.setPipeline(pipeline);
passEncoder.setBindGroup(0, uniformBindGroup);
passEncoder.setVertexBuffer(0, verticesBuffer);
passEncoder.draw(cubeVertexCount, 1, 0, 0);
passEncoder.end();
device.queue.submit([commandEncoder.finish()]);
// ...
Note:
Study the other WebGPU Samples for more examples of setBindGroup()
usage.
Unset bind group
// Set bind group in slot 0
passEncoder.setBindGroup(0, uniformBindGroup);
// Later, unset bind group in slot 0
passEncoder.setBindGroup(0, null);
Specifications
Specification |
---|
WebGPU # programmable-passes-bind-groups |
Browser compatibility
BCD tables only load in the browser
See also
- The WebGPU API