mirror of
https://github.com/visgl/luma.gl.git
synced 2025-12-08 17:36:19 +00:00
102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# ShaderLayout
|
|
|
|
:::caution
|
|
The luma.gl v9 API is currently in [public review](/docs/public-review) and may be subject to change.
|
|
:::
|
|
|
|
luma.gl defines the `ShaderLayout` type to collect a description of a (pair of) shaders.
|
|
A `ShaderLayout` is used when creating a `RenderPipeline` or `ComputePipeline`.
|
|
|
|
The binding of data is performed in JavaScript on the CPU. For this to work,
|
|
a certain amount of metadata is needed in JavaScript that describes the layout of a
|
|
render or compute pipeline's specific shaders.
|
|
|
|
Shader code contains declarations of attributes, uniform blocks, samplers etc in WGSL or GLSL code. After compilation and linking of fragment and vertex shaders into a pipeline, the resolved declarations collectively define the layout of the data that needs to be bound before the shader can execute on the GPU.
|
|
|
|
`ShaderLayout`s can be created manually by a programmer (by reading the shader code
|
|
and copying the relevant declarations).
|
|
|
|
:::info
|
|
A default `ShaderLayout` is be extracted programmatically by the `RenderPipeline` in WebGL, but this is not yet possible in WebGPU. Therefore it is necessary to provide an explicit `layout` property to any `RenderPipeline` that is expected to run in WebGPU. This restriction may be lifted in the future.
|
|
:::
|
|
|
|
```typescript
|
|
type ShaderLayout = {
|
|
attributes: [
|
|
instancePositions: {location: 0, format: 'float32x2', stepMode: 'instance'},
|
|
instanceVelocities: {location: 1, format: 'float32x2', stepMode: 'instance'},
|
|
vertexPositions: {location: 2, format: 'float32x2', stepMode: 'vertex'}
|
|
],
|
|
|
|
bindings: {[bindingName: string]: BindingLayout};
|
|
projectionUniforms: {location: 0, type: 'uniforms'},
|
|
textureSampler: {location: 1, type: 'sampler'},
|
|
texture: {location: 2, type: 'texture'}
|
|
}
|
|
}
|
|
|
|
type AttributeLayout =
|
|
{name: , location: number, format: VertexFormat, stepMode: 'vertex' | 'instance'}
|
|
|
|
type BindingLayout =
|
|
{type: 'uniform', location: number} |
|
|
{type: 'sampler', location: number} |
|
|
{type: 'texture', location: number}
|
|
```
|
|
|
|
## Usage
|
|
|
|
```typescript
|
|
const shaderLayout: ShaderLayout = {
|
|
attributes:
|
|
'instancePositions': {location: 0, format: 'float32x2', stepMode: 'instance'},
|
|
'instanceVelocities': {location: 1, format: 'float32x2', stepMode: 'instance'},
|
|
'vertexPositions': {location: 2, format: 'float32x2', stepMode: 'vertex'}
|
|
},
|
|
|
|
bindings: {
|
|
'uniforms': {location: 0, type: 'uniforms'},
|
|
'sampler': {location: 1, type: 'sampler'},
|
|
'texture': {location: 2, type: 'texture'}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Fields
|
|
|
|
### attributes
|
|
|
|
The attributes field declares structural information about the shader pipeline.
|
|
It contains fixed information about each attribute such as its location (the index in the attribute bank, typically between 0-15) and whether the attribute is instanced.
|
|
|
|
```typescript
|
|
attributes:
|
|
instancePositions: {location: 0, format: 'float32x2', stepMode: 'instance'},
|
|
instanceVelocities: {location: 1, format: 'float32x2', stepMode: 'instance'},
|
|
vertexPositions: {location: 2, format: 'float32x2', stepMode: 'vertex'}
|
|
}
|
|
```
|
|
|
|
### bindings
|
|
|
|
Bindings cover textures, samplers and uniform buffers. location (index on the GPU)
|
|
and type are the key pieces of information that need to be provided.
|
|
|
|
```typescript
|
|
bindings?: {
|
|
projectionUniforms: {location: 0, type: 'uniforms'},
|
|
textureSampler: {location: 1, type: 'sampler'},
|
|
texture: {location: 2, type: 'texture'}
|
|
}
|
|
```
|
|
|
|
|
|
### uniforms
|
|
|
|
And "free" uniforms (not part of a uniform buffer) are declared in this field.
|
|
|
|
:::caution
|
|
Uniforms are a WebGL-only concept, and it is strongly recommended to use uniform
|
|
buffers instead.
|
|
:::
|