# compute

GPGPU compute pipeline on top of Three.js: run arbitrary GLSL shaders over large arrays by rendering points into a floating-point render target.

---

## `ComputeMaterial`

A `RawShaderMaterial` configured for compute passes. The vertex shader runs once per output element, writing its result to `fragOutput`; the fragment shader forwards that value to the render target.

```typescript
new ComputeMaterial({ computeShader?, uniforms? })
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `computeShader` | `string` | GLSL body defining a `vec4 compute()` function; defaults to `return vec4(0)` |
| `uniforms` | `{ [key: string]: IUniform }` | Additional uniforms passed through to the shader |

### Notes

- The built-in uniforms `_compute_rt_output_width` and `_compute_rt_output_height` are injected automatically at compile time by `ComputeProgram`.

---

## `ComputeRenderTarget`

A `WebGLRenderTarget` sized to hold `outputCount` floats, using power-of-two width from `computeTextureDimensions`.

```typescript
new ComputeRenderTarget(outputCount: number, itemsPerPixel: 1 | 2 | 4)
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `outputCount` | `number` | Number of output elements |
| `itemsPerPixel` | `1 \| 2 \| 4` | Floats per pixel (maps to `Red` / `RG` / `RGBA` format) |

### Methods

#### `readData(renderer, start?, end?) → Float32Array`

Read computed results from the GPU.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `renderer` | `WebGLRenderer` | — | Active renderer |
| `start` | `number` | `0` | Start element index |
| `end` | `number` | `Infinity` | End element index (exclusive); defaults to `outputCount` |

### Returns

`Float32Array` — slice of `itemsPerPixel` floats per element.

---

## `ComputeProgram`

Orchestrates a full compute pass: creates an internal `WebGLRenderer`, renders the `ComputeMaterial` into a `ComputeRenderTarget`, and returns the results.

```typescript
new ComputeProgram(geometry: BufferGeometry, material: ComputeMaterial)
```

### Methods

#### `compute(renderTarget, start?, end?) → Promise<Float32Array>`

Run the compute shader asynchronously via `requestAnimationFrame` and return the result.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `renderTarget` | `ComputeRenderTarget` | — | Output target |
| `start` | `number` | `0` | Draw range start |
| `end` | `number` | `Infinity` | Draw range end |

#### `dispose() → void`

Release geometry and material GPU resources.

### Notes

- `ComputeProgram` owns its renderer; do not share it with the main scene renderer.

---

## `computeTextureDimensions(outputSize) → { width, height }`

Compute the smallest power-of-two width and minimum height such that `width * height >= outputSize`.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `outputSize` | `number` | Number of elements to store |

### Returns

`{ width: number, height: number }` — texture dimensions.

### Example

```typescript
import { computeTextureDimensions } from '@yaoc1996/js-tools/three-utils'

computeTextureDimensions(5)   // → { width: 4, height: 2 }
computeTextureDimensions(16)  // → { width: 4, height: 4 }
```
