GPUDevice: createBindGroup() 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 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 in layout. 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 corresponding GPUBindGroupLayout entry. In addition, it matches the n 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:

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 the entries 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 at offset and ending at the end of the buffer. If both offset and size 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 in entries.
  • For each entry in the layout GPUBindGroupLayout, the corresponding entry object in entries binds the correct resource type. For example, a buffer resource layout object has a GPUBufferBinding 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 and size) contained inside it completely, with a non-zero size.
      • Has a size bigger than the buffer resource layout's minBindingSize.
    • If the resource layout object type is "uniform":
      • The bound GPUBuffer has a usage that includes GPUBufferUsage.UNIFORM.
      • The effective size of the bound buffer segment is less than or equal to the GPUDevice's maxUniformBufferBindingSize limit.
      • The specified GPUBufferBinding offset is a multiple of the GPUDevice's minUniformBufferOffsetAlignment limit.
    • If the resource layout object type is "storage" or "read-only-storage":
      • The bound GPUBuffer has a usage that includes GPUBufferUsage.STORAGE.
      • The effective size of the bound buffer segment is less than or equal to the GPUDevice's maxStorageBufferBindingSize limit.
      • The effective size of the bound buffer segment is a multiple of 4.
      • The specified GPUBufferBinding offset is a multiple of the GPUDevice's minStorageBufferOffsetAlignment limit.
  • If the resource layout object is a storageTexture, the corresponding bound GPUTextureView:
    • Has a dimension equal to the resource layout object's viewDimension (see GPUTexture.createView() for more details of a texture view's settings).
    • Has a format equal to the resource layout object's sampleType.
    • Has a mipLevelCount equal to 1.
    • Is a view of a GPUTexture with a usage that includes GPUTextureUsage.STORAGE_BINDING.
  • If the resource layout object is a texture, the corresponding bound GPUTextureView:
    • Has a dimension equal to the resource layout object's viewDimension (see GPUTexture.createView() for more details of a texture view's settings).
    • Has a format compatible with the resource layout object's sampleType.
    • Is a view of a GPUTexture with a usage that includes GPUTextureUsage.TEXTURE_BINDING.
    • is a view of a GPUTexture with a sampleCount greater than 1 if the resource layout object's multisampled property is true, or equal to 1 if it is false.

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

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
createBindGroup
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

See also