WebGPU API
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
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 in
layout. Each entry object has the following properties:binding- : A number representing a unique identifier for this resource binding, which matches the
bindingvalue of a corresponding GPUBindGroupLayout entry. In addition, it matches thenindex value of the corresponding@binding(n)attribute in the shader (GPUShaderModule) used in the related pipeline.
- : A number representing a unique identifier for this resource binding, which matches the
resource- : The resource to bind. This can be one of the following:
GPUBufferBinding: Wraps a GPUBuffer; see GPUBufferBinding objects for a definition.- GPUBuffer: Can be used directly rather than being wrapped in a
GPUBufferBinding, provided the defaultoffsetandsizevalues are being used. - GPUExternalTexture
- GPUTextureView: Can be used in place of a
GPUExternalTextureprovided it is compatible (a 2D format with a single subresource, that is,dimension: "2d"). - GPUTexture: Can be used in place of a
GPUTextureView, provided a default view is desired. When used in this context,GPUTextureis equivalent to aGPUTextureViewobject created using a GPUTexture.createView() call with no argument specified. - GPUSampler
- : The resource to bind. This can be one of the following:
- : 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 in
label- : 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 the
entriesof this bind group will conform to.
- : The GPUBindGroupLayout that the
- : An object containing the following properties:
GPUBufferBinding objects
A GPUBufferBinding object can contain the following properties:
buffer- : The GPUBuffer object you want to bind.
offset- : The offset, in bytes, from the beginning of the
bufferto the beginning of the range exposed to the shader by the buffer binding. If omitted,offsetdefaults to 0.
- : The offset, in bytes, from the beginning of the
size- : The size, in bytes, of the buffer binding. If omitted,
sizewill be the range starting atoffsetand ending at the end of thebuffer. If bothoffsetandsizeare omitted, the entire buffer is exposed to the shader.
- : The size, in bytes, of the buffer binding. If omitted,
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
layoutGPUBindGroupLayout equals the number of entry objects inentries. - For each entry in the
layoutGPUBindGroupLayout, the corresponding entry object inentriesbinds the correct resource type. For example, abufferresource layout object has aGPUBufferBindingobject specified in the corresponding binding. - If the resource layout object is a
buffer:- The corresponding bound GPUBuffer:
- Has its bound part (as specified by
offsetandsize) contained inside it completely, with a non-zero size. - Has a size bigger than the
bufferresource layout'sminBindingSize.
- Has its bound part (as specified by
- If the resource layout object
typeis"uniform":- The bound GPUBuffer has a
usagethat includesGPUBufferUsage.UNIFORM. - The effective size of the bound buffer segment is less than or equal to the GPUDevice's
maxUniformBufferBindingSizeGPUSupportedLimits. - The specified
GPUBufferBindingoffsetis a multiple of the GPUDevice'sminUniformBufferOffsetAlignmentGPUSupportedLimits.
- The bound GPUBuffer has a
- If the resource layout object
typeis"storage"or"read-only-storage":- The bound GPUBuffer has a
usagethat includesGPUBufferUsage.STORAGE. - The effective size of the bound buffer segment is less than or equal to the GPUDevice's
maxStorageBufferBindingSizeGPUSupportedLimits. - The effective size of the bound buffer segment is a multiple of 4.
- The specified
GPUBufferBindingoffsetis a multiple of the GPUDevice'sminStorageBufferOffsetAlignmentGPUSupportedLimits.
- The bound GPUBuffer has a
- The corresponding bound GPUBuffer:
- If the resource layout object is a
storageTexture, the corresponding bound GPUTextureView:- Has a
dimensionequal to the resource layout object'sviewDimension(see GPUTexture.createView() for more details of a texture view's settings). - Has a
formatequal to the resource layout object'ssampleType. - Has a
mipLevelCountequal to 1. - Is a view of a GPUTexture with a
usagethat includesGPUTextureUsage.STORAGE_BINDING.
- Has a
- If the resource layout object is a
texture, the corresponding bound GPUTextureView:- Has a
dimensionequal to the resource layout object'sviewDimension(see GPUTexture.createView() for more details of a texture view's settings). - Has a
formatcompatible with the resource layout object'ssampleType. - Is a view of a GPUTexture with a
usagethat includesGPUTextureUsage.TEXTURE_BINDING. - is a view of a GPUTexture with a
sampleCountgreater than 1 if the resource layout object'smultisampledproperty 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.
// …
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
Browser compatibility
See also
- The WebGPU API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
