GPUDevice: createBindGroup() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("WebGPU API")}}{{SecureContext_Header}}{{AvailableInWorkers}}
The **createBindGroup()** method of the {{domxref("GPUDevice")}} interface creates a {{domxref("GPUBindGroup")}} based on a {{domxref("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 {{domxref("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 {{domxref("GPUBindGroupLayout")}} entry. In addition, it matches thenindex value of the corresponding [@binding(n)](https://gpuweb.github.io/gpuweb/wgsl/#attribute-binding) attribute in the shader ({{domxref("GPUShaderModule")}}) used in the related pipeline. resource- : The resource to bind. This can be one of the following:
GPUBufferBinding: Wraps a {{domxref("GPUBuffer")}}; see GPUBufferBinding objects for a definition.- {{domxref("GPUBuffer")}}: Can be used directly rather than being wrapped in a
GPUBufferBinding, provided the default [offset](#offset) and [size](#size) values are being used. - {{domxref("GPUExternalTexture")}}
- {{domxref("GPUTextureView")}}: Can be used in place of a
GPUExternalTextureprovided it is compatible (a 2D format with a single subresource, that is, [dimension: "2d"](/en-US/docs/Web/API/GPUTexture/createView#dimension)). - {{domxref("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 {{domxref("GPUTexture.createView()")}} call with no argument specified. - {{domxref("GPUSampler")}}
label{{optional_inline}}- : A string providing a label that can be used to identify the object, for example in {{domxref("GPUError")}} messages or console warnings.
layout- : The {{domxref("GPUBindGroupLayout")}} that the
entriesof this bind group will conform to.
GPUBufferBinding objects
A GPUBufferBinding object can contain the following properties:
buffer- : The {{domxref("GPUBuffer")}} object you want to bind.
offset{{optional_inline}}- : 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. size{{optional_inline}}- : 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.
Return value
A {{domxref("GPUBindGroup")}} object instance.
Validation
The following criteria must be met when calling **createBindGroup()**, otherwise a {{domxref("GPUValidationError")}} is generated and an invalid {{domxref("GPUBindGroup")}} object is returned:
- The number of entries in the
layout{{domxref("GPUBindGroupLayout")}} equals the number of entry objects inentries. - For each entry in the
layout{{domxref("GPUBindGroupLayout")}}, 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 {{domxref("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. - If the resource layout object
typeis"uniform": - The bound {{domxref("GPUBuffer")}} has a
usagethat includesGPUBufferUsage.UNIFORM. - The effective size of the bound buffer segment is less than or equal to the {{domxref("GPUDevice")}}'s
maxUniformBufferBindingSize{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - The specified
GPUBufferBindingoffsetis a multiple of the {{domxref("GPUDevice")}}'sminUniformBufferOffsetAlignment{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - If the resource layout object
typeis"storage"or"read-only-storage": - The bound {{domxref("GPUBuffer")}} has a
usagethat includesGPUBufferUsage.STORAGE. - The effective size of the bound buffer segment is less than or equal to the {{domxref("GPUDevice")}}'s
maxStorageBufferBindingSize{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - The effective size of the bound buffer segment is a multiple of 4.
- The specified
GPUBufferBindingoffsetis a multiple of the {{domxref("GPUDevice")}}'sminStorageBufferOffsetAlignment{{domxref("GPUSupportedLimits", "limit", "", "nocode")}}. - If the resource layout object is a
storageTexture, the corresponding bound {{domxref("GPUTextureView")}}: - Has a
dimensionequal to the resource layout object'sviewDimension(see {{domxref("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 {{domxref("GPUTexture")}} with a
usagethat includesGPUTextureUsage.STORAGE_BINDING. - If the resource layout object is a
texture, the corresponding bound {{domxref("GPUTextureView")}}: - Has a
dimensionequal to the resource layout object'sviewDimension(see {{domxref("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 {{domxref("GPUTexture")}} with a
usagethat includesGPUTextureUsage.TEXTURE_BINDING. - is a view of a {{domxref("GPUTexture")}} with a
sampleCountgreater than 1 if the resource layout object'smultisampledproperty istrue, or equal to 1 if it isfalse.
Examples
توجه: 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
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- The WebGPU API