Class BufferBinding

Used to format uniforms or storages struct inputs and create a single typed array that will hold all those inputs values. The array needs to be correctly padded depending on every value type, so it can be safely used as a GPUBuffer input.

It will also create WGSL Structs and variables according to the BufferBinding inputs parameters.

The WGSL structs and variables declaration may vary based on the input types, especially if there's one or more arrays involved (i.e. array<f32>, array<vec3f> etc.).

It is possible to create complex WGSL structs with children structs by using the childrenBindings parameter.

There's a helper tool to help you understand and debug your BufferBinding WGSL declaration: BufferBinding WGSL generation helper

A BufferBinding can also have a parent BufferBinding, in which case it won't create a GPUBuffer but use its parent GPUBuffer at the right offset. Useful to create a unique BufferBinding with a single GPUBuffer to handle multiple BufferBinding and update them with a single writeBuffer call.

Example

// create a GPU buffer binding
const bufferBinding = new BufferBinding({
  name: 'params', // name of the WGSL object
  bindingType: 'uniform', // should be 'storage' for large arrays
  struct: {
    opacity: {
      type: 'f32',
      value: 1,
    },
    mousePosition: {
      type: 'vec2f',
      value: new Vec2(),
    },
  },
})

Hierarchy (View Summary)

Binding
- BufferBinding
  - WritableBufferBinding

Constructors

constructor

new BufferBinding(parameters: BufferBindingParams): BufferBinding
BufferBinding constructor
Parameters
- parameters: BufferBindingParams
  parameters used to create our BufferBindings
Returns BufferBinding
Overrides Binding.constructor
- Defined in src/core/bindings/BufferBinding.ts:182

Properties

label

label: string

The label of the Binding.

name

name: string

The name/key of the Binding.

visibility

visibility: number

The visibility of the Binding in the shaders.

shouldResetBindGroup

shouldResetBindGroup: boolean

Flag indicating whether we should recreate the parentMesh bind group, usually when a resource has changed.

shouldResetBindGroupLayout

shouldResetBindGroupLayout: boolean

Flag indicating whether we should recreate the parentMesh GPU bind group layout, usually when a resource layout has changed.

cacheKey

cacheKey: string

A cache key allowing to get / set bindings from the device manager map cache. Used for BufferBinding only at the moment.

bindingType

bindingType: BufferBindingType

The binding type of the BufferBinding

useStruct

useStruct: boolean

Flag to indicate whether this BufferBinding buffer elements should be packed in a single structured object or if each one of them should be a separate binding.

inputs

inputs: Record<string, BufferBindingInput>

All the BufferBinding data inputs

childrenBindings

childrenBindings: BufferBinding[]

Array of children BufferBinding used as struct children.

shouldUpdate

shouldUpdate: boolean

Flag to indicate whether one of the inputs value has changed and we need to update the GPUBuffer linked to the arrayBuffer array

bufferElements

bufferElements: AllowedBufferElement[]

An array describing how each corresponding inputs should be inserted into our arrayView array

arrayBufferSize

arrayBufferSize: number

Total size of our arrayBuffer array in bytes

arrayBuffer

arrayBuffer: ArrayBuffer

Array buffer that will be sent to the GPUBuffer

arrayView

arrayView: DataView

Data view of our array buffer

parentView

parentView: DataView

DataView inside the parent arrayBuffer if set.

parentViewSetBufferEls

parentViewSetBufferEls: {
bufferElement: AllowedBufferElement;
viewSetFunction: DataViewSetFunction;
}[]

Array of bufferElements and according view set functions to use if the parent is set.

Type declaration

bufferElement: AllowedBufferElement
Corresponding bufferElement.
viewSetFunction: DataViewSetFunction
Corresponding view set function.

buffer

buffer: Buffer

The Buffer holding the GPUBuffer

wgslStructFragment

wgslStructFragment: string

A string to append to our shaders code describing the WGSL structure representing this BufferBinding

wgslGroupFragment

wgslGroupFragment: string[]

An array of strings to append to our shaders code declaring all the WGSL variables representing this BufferBinding

options

options: BufferBindingParams

Options used to create this BufferBinding

Accessors

parent

get parent(): BufferBinding
Get the BufferBinding parent if any.

Returns BufferBinding
- The BufferBinding parent if any.
- Defined in src/core/bindings/BufferBinding.ts:275

offset

get offset(): number
Get this BufferBinding offset in bytes inside the parent arrayBuffer.

Returns number
- The offset in bytes inside the parent arrayBuffer
- Defined in src/core/bindings/BufferBinding.ts:352

resourceLayout

get resourceLayout(): {
    buffer: GPUBufferBindingLayout;
    offset?: number;
    size?: number;
}
Get ().descriptor.entries.resource | GPUBindGroupLayout entry resource.

Returns { buffer: GPUBufferBindingLayout; offset?: number; size?: number }
- buffer: GPUBufferBindingLayout
  bind group layout resource
- Optionaloffset?: number
  Offset in bytes in the parent buffer if set.
- Optionalsize?: number
  Size in bytes in the parent buffer if set.
- Defined in src/core/bindings/BufferBinding.ts:360

resourceLayoutCacheKey

get resourceLayoutCacheKey(): string
Get the resource cache key

Returns string
- Defined in src/core/bindings/BufferBinding.ts:380

resource

get resource(): { buffer: GPUBuffer; offset?: number; size?: number }
Get ().descriptor.entries.resource | GPUBindGroup entry resource.

Returns { buffer: GPUBuffer; offset?: number; size?: number }
- buffer: GPUBuffer
  bind group resource
- Optionaloffset?: number
  Offset in bytes in the parent buffer if set.
- Optionalsize?: number
  Size in bytes in the parent buffer if set.
- Defined in src/core/bindings/BufferBinding.ts:388

Methods

`Static`cloneStruct

cloneStruct(struct: Record<string, Input>): Record<string, Input>
Clone a struct object width new default values.
Parameters
- struct: Record<string, Input>
  New cloned struct object.
Returns Record<string, Input>
- Defined in src/core/bindings/BufferBinding.ts:246

getMinOffsetSize

getMinOffsetSize(value: number): number
Round the given size value to the nearest minimum GPUDevice buffer offset alignment.
Parameters
- value: number
  Size to round.
Returns number
- Defined in src/core/bindings/BufferBinding.ts:343

clone

clone(
params?: WritableBufferBindingParams | BufferBindingParams,
): WritableBufferBinding | BufferBinding
Clone this BufferBinding into a new one. Allows to skip buffer layout alignment computations.
Parameters
- params: WritableBufferBindingParams | BufferBindingParams = ...
  params to use for cloning
Returns WritableBufferBinding | BufferBinding
- Defined in src/core/bindings/BufferBinding.ts:406

setBindings

setBindings(bindings: Record<string, Input>): void
Format bindings struct and set our inputs
Parameters
- bindings: Record<string, Input>
  bindings inputs
Returns void
- Defined in src/core/bindings/BufferBinding.ts:517

setChildrenBindings

setChildrenBindings(childrenBindings: BufferBindingChildrenBinding[]): void
Set this BufferBinding optional childrenBindings.
Parameters
- childrenBindings: BufferBindingChildrenBinding[]
  Array of BufferBindingChildrenBinding to use as childrenBindings.
Returns void
- Defined in src/core/bindings/BufferBinding.ts:566

setInputsAlignment

setInputsAlignment(): void
Set the buffer alignments from inputs.

Returns void
- Defined in src/core/bindings/BufferBinding.ts:627

setBufferAttributes

setBufferAttributes(): void
Set our buffer attributes: Takes all the inputs and adds them to the bufferElements array with the correct start and end offsets (padded), then fill our arrayBuffer typed array accordingly.

Returns void
- Defined in src/core/bindings/BufferBinding.ts:771

setWGSLFragment

setWGSLFragment(): void
Set the WGSL code snippet to append to the shaders code. It consists of variable (and Struct structures if needed) declarations.

Returns void
- Defined in src/core/bindings/BufferBinding.ts:832

shouldUpdateBinding

shouldUpdateBinding(bindingName?: string): void
Set a binding shouldUpdate flag to true to update our arrayBuffer array during next render.
Parameters
- bindingName: string = ''
  the binding name/key to update
Returns void
- Defined in src/core/bindings/BufferBinding.ts:929

update

update(): void
Executed at the beginning of a Material render call. If any of the inputs has changed, run its onBeforeUpdate callback then updates our arrayBuffer array. Also sets the shouldUpdate property to true so the BindGroup knows it will need to update the GPUBuffer.

Returns void
- Defined in src/core/bindings/BufferBinding.ts:940

extractBufferElementDataFromBufferResult

extractBufferElementDataFromBufferResult(
parameters: { result: Float32Array; bufferElementName: string },
): Float32Array
Extract the data corresponding to a specific BufferElement from a Float32Array holding the GPU buffer data of this BufferBinding
Parameters
- parameters: { result: Float32Array; bufferElementName: string }
  parameters used to extract the data
  - result: Float32Array
    Float32Array holding GPUBuffer data
  - bufferElementName: string
    name of the BufferElement to use to extract the data
Returns Float32Array
- extracted data from the Float32Array
- Defined in src/core/bindings/BufferBinding.ts:998

Class BufferBinding

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns BufferBinding

Properties

label

name

visibility

shouldResetBindGroup

shouldResetBindGroupLayout

cacheKey

bindingType

useStruct

inputs

childrenBindings

shouldUpdate

bufferElements

arrayBufferSize

arrayBuffer

arrayView

parentView

parentViewSetBufferEls

Type declaration

bufferElement: AllowedBufferElement

viewSetFunction: DataViewSetFunction

buffer

wgslStructFragment

wgslGroupFragment

options

Accessors

parent

Returns BufferBinding

offset

Returns number

resourceLayout

Returns { buffer: GPUBufferBindingLayout; offset?: number; size?: number }

buffer: GPUBufferBindingLayout

Optionaloffset?: number

Optionalsize?: number

resourceLayoutCacheKey

Returns string

resource

Returns { buffer: GPUBuffer; offset?: number; size?: number }

buffer: GPUBuffer

Optionaloffset?: number

Optionalsize?: number

Methods

StaticcloneStruct

Parameters

Returns Record<string, Input>

getMinOffsetSize

Parameters

Returns number

clone

Parameters

Returns WritableBufferBinding | BufferBinding

setBindings

Parameters

Returns void

setChildrenBindings

Parameters

Returns void

setInputsAlignment

Returns void

setBufferAttributes

Returns void

setWGSLFragment

Returns void

shouldUpdateBinding

Parameters

Returns void

update

`Optional`offset?: number

`Optional`size?: number

`Optional`offset?: number

`Optional`size?: number

`Static`cloneStruct