Merge 3d6c289 into 2bcfd6c

docs/api-reference/engine/computation.md

@@ -0,0 +1,111 @@
+# Computation
+
+The `Computation` class is a high-level class in the luma.gl API. It brings together all GPU functionality needed to run GPU compute shaders, in a single, easy-to-use interface.
+
+`Computation` manages the following responsibilities:
+- **bindings** these can reference textures and uniform buffers
+- **shader module injection**
+- **shader transpilation****
+- **debugging** - Detailed debug logging of draw calls
+
+The `Computation` class integrates with 
+- The `@luma.gl/shadertools` shader module system: [see `Shader Assembly`]( /docs/api-reference/shadertools/shader-assembler).
+
+## Usage
+
+```typescript
+import {Computation} from `@luma.gl/engine`;
+```
+
+One of the simplest way to provide attribute data is by using a Geometry object.
+
+Create model object by passing shaders, uniforms, geometry and render it by passing updated uniforms.
+
+```typescript
+import {Computation} from `@luma.gl/engine`;
+// construct the model.
+const model = new Computation(device, {
+  source: COMPUTE_SHADER,
+  bindings: {
+    uSampler: texture
+  },
+})
+```
+
+### Provide attribute data using Buffer
+
+When using `Buffer` objects, data remains on GPU and same `Buffer` object can be shared between multiple models.
+
+```typescript
+// construct the model.
+const model = new Computation(device, {
+  source: COMPUTE_SHADER,
+  attributes: {
+    attributeName1: bufferObject,
+    attributeName2: device.createBuffer(new Float32Array(...))
+  },
+  uniforms: {uSampler: texture},
+})
+```
+
+On each frame, call the `model.draw()` function after updating any uniforms (typically matrices).
+
+```ts
+model.setUniforms({
+  uPMatrix: currentProjectionMatrix,
+  uMVMatrix: current ComputationViewMatrix
+});
+model.draw();
+```
+
+Debug shader source (even when shader successful)
+```ts
+// construct the model.
+const model = new Computation(device, {
+  source: COMPUTE_SHADER,
+  debugShaders: true
+});
+```
+
+## Types
+
+### `ComputationProps`
+
+| Property           | Type                                           | Description                                                                       |
+| ------------------ | ---------------------------------------------- | --------------------------------------------------------------------------------- |
+| `source`               | `Shader` \| _string_                           | A vertex shader object, or source as a string.                                    |
+| `modules`          |                                                | shader modules to be applied (shadertools).                                       |
+| `pipelineFactory?` |                                                | `PipelineFactory` to use for program creation and caching.                        |
+| `debugShaders?`    | `'error' \| 'never' \| 'warnings' \| 'always'` | Specify in what triggers the display shader compilation log (default: `'error'`). |
+
+`ComputationProps` also include `ComputePipelineProps`, which are passed through to the `ComputePipeline` constructor, e.g:
+
+| Property          | Type                       | Description                                                                             |
+| ----------------- | -------------------------- | --------------------------------------------------------------------------------------- |
+| `layout`          | `ShaderLayout`             | Describes how shader attributes and bindings are laid out.                              |
+| `bindings?`       | `Record<string, any>`      |                                                                                         |
+
+
+## Fields
+
+### `pipeline: ComputePipeline`
+
+The model's `ComputePipeline` instance
+
+## Methods
+
+### `constructor(device: Device, props: ComputationProps)`
+
+The constructor for the Computation class. Use this to create a new Computation.
+
+### `destroy(): void`
+
+Free GPU resources associated with this model immediately, instead of waiting for garbage collection.
+
+### `dispatch(pass: ComputePass, x, y, z)`
+
+Renders the model with provided uniforms, attributes and samplers
+
+```typescript
+computation.dispatch(computePass, 1);
+```

docs/sidebar.json

@@ -111,6 +111,7 @@
           "api-reference/engine/model",
           "api-reference/engine/pipeline-factory",
           "api-reference/engine/shader-factory",
+          "api-reference/engine/computation",
           "api-reference/engine/transform",
           "api-reference/engine/transform/buffer-transform",
           "api-reference/engine/transform/texture-transform",

docs/whats-new.md

@@ -58,10 +58,11 @@ To accelerate WebGPU development, luma.gl v9 drops support for legacy functional
 
 **`@luma.gl/engine`**
 
-- NEW: Scenegraph classes: `ModelNode`, `GroupNode`, `ScenegraphNode`. (Moved from `@luma.gl/experimental`).
+- NEW: Scenegraph classes: `ModelNode`, `GroupNode`, `ScenegraphNode`, moved from `@luma.gl/experimental`.
 - NEW: `ShaderInputs` - Class that manages uniform buffers for a `Model`
 - NEW: `ShaderFactory` - Creates and caches reusable `Shader` resources
-- NEW: `AnimationLoopTemplate` - Small helper class that can help write cleaner demos and applications in TypeScript.
+- NEW: `AnimationLoopTemplate` - Helper class for writing cleaner demos and applications in TypeScript.
+- New `Computation` - Class that manages a `ComputePipeline` similar to `Model` and `Transform`.
 
 **`@luma.gl/gltf`**
 

modules/core/src/adapter/resources/compute-pipeline.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {Resource, ResourceProps} from './resource';
-import type {ComputeShaderLayout} from '../types/shader-layout';
+import type {ComputeShaderLayout, Binding} from '../types/shader-layout';
 import type {Device} from '../device';
 import type {Shader} from './shader';
 
@@ -43,4 +43,10 @@ export abstract class ComputePipeline extends Resource<ComputePipelineProps> {
   constructor(device: Device, props: ComputePipelineProps) {
     super(device, props, ComputePipeline.defaultProps);
   }
+
+  /**
+   * @todo Use renderpass.setBindings() ?
+   * @todo Do we want to expose BindGroups in the API and remove this?
+   */
+  abstract setBindings(bindings: Record<string, Binding>): void;
 }