ThecreateBindGroup() method of theGPUDevice interface creates aGPUBindGroup based on aGPUBindGroupLayout 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 theGPUBindGroupLayout referenced inlayout. Each entry object has the following properties:

binding

A number representing a unique identifier for this resource binding, which matches thebinding 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: Wraps aGPUBuffer; seeGPUBufferBinding objects for a definition.
• GPUBuffer: Can be used directly rather than being wrapped in aGPUBufferBinding, provided the defaultoffset andsize values are being used.
• GPUExternalTexture
• GPUTextureView: Can be used in place of aGPUExternalTexture provided it is compatible (a 2D format with a single subresource, that is,dimension: "2d").
• GPUTexture: Can be used in place of aGPUTextureView, provided a default view is desired. When used in this context,GPUTexture is equivalent to aGPUTextureView object created using aGPUTexture.createView() call with no argument specified.
• GPUSampler

labelOptional

A string providing a label that can be used to identify the object, for example inGPUError messages or console warnings.

layout

TheGPUBindGroupLayout that theentries of this bind group will conform to.

GPUBufferBinding objects

AGPUBufferBinding object can contain the following properties:

buffer

TheGPUBuffer object you want to bind.

offsetOptional

The offset, in bytes, from the beginning of thebuffer to the beginning of the range exposed to the shader by the buffer binding. If omitted,offset defaults to 0.

sizeOptional

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

AGPUBindGroup object instance.

Validation

The following criteria must be met when callingcreateBindGroup(), otherwise aGPUValidationError is generated and an invalidGPUBindGroup object is returned:

• The number of entries in thelayoutGPUBindGroupLayout equals the number of entry objects inentries.
• For each entry in thelayoutGPUBindGroupLayout, 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 abuffer:
  • The corresponding boundGPUBuffer:
    • Has its bound part (as specified byoffset andsize) contained inside it completely, with a non-zero size.
    • Has a size bigger than thebuffer resource layout'sminBindingSize.
  • If the resource layout objecttype is"uniform":
    • The boundGPUBuffer has ausage that includesGPUBufferUsage.UNIFORM.
    • The effective size of the bound buffer segment is less than or equal to theGPUDevice'smaxUniformBufferBindingSizelimit.
    • The specifiedGPUBufferBindingoffset is a multiple of theGPUDevice'sminUniformBufferOffsetAlignmentlimit.
  • If the resource layout objecttype is"storage" or"read-only-storage":
    • The boundGPUBuffer has ausage that includesGPUBufferUsage.STORAGE.
    • The effective size of the bound buffer segment is less than or equal to theGPUDevice'smaxStorageBufferBindingSizelimit.
    • The effective size of the bound buffer segment is a multiple of 4.
    • The specifiedGPUBufferBindingoffset is a multiple of theGPUDevice'sminStorageBufferOffsetAlignmentlimit.
• If the resource layout object is astorageTexture, the corresponding boundGPUTextureView:
  • Has adimension equal to the resource layout object'sviewDimension (seeGPUTexture.createView() for more details of a texture view's settings).
  • Has aformat equal to the resource layout object'ssampleType.
  • Has amipLevelCount equal to 1.
  • Is a view of aGPUTexture with ausage that includesGPUTextureUsage.STORAGE_BINDING.
• If the resource layout object is atexture, the corresponding boundGPUTextureView:
  • Has adimension equal to the resource layout object'sviewDimension (seeGPUTexture.createView() for more details of a texture view's settings).
  • Has aformat compatible with the resource layout object'ssampleType.
  • Is a view of aGPUTexture with ausage that includesGPUTextureUsage.TEXTURE_BINDING.
  • is a view of aGPUTexture with asampleCount greater than 1 if the resource layout object'smultisampled property istrue, or equal to 1 if it isfalse.

Examples

Basic example

Ourbasic 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

• TheWebGPU API