mirror of
https://github.com/visgl/luma.gl.git
synced 2025-12-08 17:36:19 +00:00
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# BufferLayout
|
|
|
|
The bufferLayout type provides information about how the application is planning to
|
|
map the attributes in its pipelines to the memory in GPU buffers.
|
|
|
|
`BufferLayout` affects buffers bound with `RenderPipeline.setAttributes({[bufferName]: Buffer})` or
|
|
`Model.setAttributes({[bufferName]: Buffer})`. The names of buffer bind points are determined by the `bufferLayout` mapping supplied to `createRenderPipeline()` or `new Model()`.
|
|
This buffer name then becomes valid in `RenderPipeline.setAttributes()` and `Model.setAttributes()`.
|
|
|
|
## Usage
|
|
|
|
The simplest use case is to provide a non-default vertex type:
|
|
|
|
```typescript
|
|
bufferLayout: [
|
|
{name: 'instancePositions', format: 'float32x3'}
|
|
...
|
|
// RGBA colors can be efficiently encoded in 4 8bit bytes, instead of 4 32bit floats
|
|
{name: 'instanceColors', format: 'uint8normx4'},
|
|
],
|
|
```
|
|
|
|
|
|
This is short hand for specifying an attribute with the same name as the buffer
|
|
|
|
```typescript
|
|
bufferLayout: [
|
|
{name: 'instancePositions', attributes: [{attribute: 'instancePositions', format: 'float32x3'}]},
|
|
{name: 'instanceColors', attributes: [{attribute: 'instanceColors', format: 'uint8normx4'}]},
|
|
]
|
|
```
|
|
|
|
A more advanced use case is interleaving: two attributes access the same buffer sin an interleaved way.
|
|
Note that this introduces a buffer name that is different from attribute names. This buffer name can be specified in `setAttributes({[bufferName]: Buffer})` method on the `RenderPipeline` and `Model` classes.
|
|
|
|
```typescript
|
|
bufferLayout: [
|
|
{
|
|
name: 'particles', stepMode: 'instance', byteStride: 24, attributes: [
|
|
// Note that strides are automatically calculated assuming a packed buffer.
|
|
{attribute: 'instancePositions', format: 'float32x3', byteOffset: 0},
|
|
{attribute: 'instanceVelocities', format: 'float32x3', byteOffset: 12}
|
|
]
|
|
}
|
|
],
|
|
```
|
|
|
|
In the above case case a new buffer name `particles` is defined and `setAttributes({particles: Buffer})`
|
|
calls will recognize that name and bind the provided buffer to all the interleaved attributes.
|
|
|
|
## `BufferLayout` Fields
|
|
|
|
Each `BufferLayout` describes how the memory content of one buffer is mapped to one or more shader attributes, via the following fields:
|
|
|
|
- `name: string` defines the name of this buffer for use in `setAttributes()` methods. THe application is free to select this name.
|
|
- `stepMode: 'vertex' | 'instance'` Whether attributes in this buffer will be treated as instanced.
|
|
- `byteStride?: number` the stride between elements in the buffer (default assumes a packed buffer)
|
|
- `attributes?: BufferAttributeLayout[]` - A list of attributes that will be bound to this buffer.
|
|
- `format?: VertexFormat` - Shorthand that allows specification of a single attribute with the same name as the buffer.
|
|
|
|
Remarks:
|
|
Attributes whose name includes the string `instance` will default to `stepMode: 'instance'` and all other attributes will default to `stepMode: 'vertex'`.
|
|
|
|
:::caution
|
|
One of `attributes` and `format` must be supplied, but not both.
|
|
The `format` field is equivalent to specifying `{name: _bufferName_, attributes: [{attribute: _layout_.name, format: _layout_.format, byteOffset: 0}]`
|
|
:::
|
|
|
|
|
|
## `BufferAttributeLayout` Fields
|
|
|
|
The attributes field must contain an array of `BufferAttributeLayout` objects.
|
|
|
|
- `attribute: string` the name of the attribute.
|
|
- `format: VertexFormat` the format of (the subset of) the buffer's memory being mapped to this attribute.
|
|
- `byteOffset?: number` the offset into the buffer (defaults to `0`). This should be a sum of any global offset into the buffer plus any small offset into the `byteStride` for interleaved attributes.
|
|
|
|
:::info
|
|
Unfortunately, interleaving attributes into the same buffer does not help avoid the
|
|
limit on the number of attributes that can be used in a shader (16 on many systems).
|
|
:::
|