<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=view]]

<div class="doc">

# The view: one WebGL2 ray-marcher, a template

<p class="plain"><a href="../view.md">this page as plaintext</a></p>

`view.js` is the twin's one voxel view: a per-pixel DDA over the cells as a 3-D integer texture, with the empty-space leaps by the worker's block distance. A look's features are resolved into the shader's source at build, never a uniform branch (HLSL evaluates both sides of a logical operator and a ternary: the toy's draw measured 204 ms against 135 with one feature merely switched off by a uniform, 2026-11-05).

## The look

| key | type | default | |
|---|---|---|---|
| `amb` | f32 | 0.38 | the light a face turned from the sun keeps |
| `sfloor` | f32 | 0.35 | what a shadowed face keeps of the sun |
| `edge` | cells | 0.0 | gas and liquid fade over this many cells toward the box's faces (0: none) |
| `grain` | f32 | 0.0 | a solid cell's albedo varies by this much (0: none) |
| `soft` | 0|1 | 0.0 | gas drawn as a soft volume (the scenes' bodies) |
| `shadow` | 0|1 | 1.0 | a shadow ray toward the sun |
| `ao` | 0|1 | 1.0 | the six neighbours' occlusion |
| `water` | 0|1 | 1.0 | the water's surface and depth tint |
| `heat` | 0|1 | 1.0 | heat on the frame, toward an ember colour above 0.72 |
| `flicker` | 0|1 | 1.0 | fire's flicker by the frame |
| `placed` | 0|1 | 0.0 | the camera is in the scene's space and place maps it to the grid (y flipped); off: grid space |
| `scene` | 0|1 | 1.0 | the sky, the checker floor and the fog, an opaque pixel; off: a ray that leaves the grid is discarded and the cover is the alpha (premultiplied) |

## The shims

Each caller's look, as its file sets it (a key absent keeps the default).

| shim | unroll | `amb` | `sfloor` | `edge` | `grain` | `soft` | `shadow` | `ao` | `water` | `heat` | `flicker` | `placed` | `scene` |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| the player | yes | 0.55 | · | · | · | · | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 1.0 |
| the toy | yes | 0.38 | 0.35 | · | · | · | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 | 1.0 |
| the home | no | · | 0.25 | · | · | · | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 |
| the comet | no | 0.16 | · | 6.0 | 0.2 | 1.0 | · | · | · | · | · | · | · |
| the system | no | 0.24 | · | 6.0 | 0.16 | 1.0 | · | · | · | · | · | · | · |

## The API

### `VS`

<pre class="sig">VS</pre>

The vertex shader every view shares: a screen-filling triangle strip from `gl_VertexID`, its NDC passed on as `v_ndc` for the fragment shader to ray-march from.

<p class="meta">starburn/crates/starlab-wasm/web/view.js:34</p>

### `LOOK`

<pre class="sig">LOOK</pre>

The look's keys and their defaults (api.json's `look` names each): the ambient and the shadow floor, the edge, grain and softness, the shadow, ambient occlusion, water, heat and flicker passes on or off, the placed-cell mark, the scene lighting. A view's `look:` bag overrides them key by key.

<p class="meta">starburn/crates/starlab-wasm/web/view.js:43</p>

### `fsSource`

<pre class="sig">fsSource(look, unroll)</pre>

The fragment shader's source for a look (the features in the source or not) and a loop form.

<p class="meta">starburn/crates/starlab-wasm/web/view.js:46</p>

### `MAT_OF`

<pre class="sig">MAT_OF</pre>

The material id of a packed cell word: its low four bits, plus sixteen when bit 6 (the high-material flag) is set, so the thirty-two slots of `MATS` are reached.

<p class="meta">starburn/crates/starlab-wasm/web/view.js:287</p>

### `voxelView`

<pre class="sig">voxelView(gl, opts)</pre>

The view on a context. `palette` 32 [r,g,b] (0-255) or null; `alphas` 32 floats; `look` and `unroll` as above.

| option | type | |
|---|---|---|
| `palette` | 32 x [r, g, b] 0-255 | a material's colour |
| `alphas` | 32 x f32 | a material's cover (1 = opaque) |
| `look` | look | the features, resolved into the shader's source at build |
| `unroll` | boolean | constant loop bounds (a faster draw, a longer link) or loops through u_one |

<p class="meta">starburn/crates/starlab-wasm/web/view.js:290</p>

### `placing`

<pre class="sig">placing(place, dims)</pre>

A scene point to the grid's cell coordinates and back, for the pick and the strikes (the same map as the shader's).

<p class="meta">starburn/crates/starlab-wasm/web/view.js:400</p>

### `pickCells`

<pre class="sig">pickCells(grid, dims, ro, rd, matOf)</pre>

The first cell a ray meets in the page's copy of the grid (a DDA, as the shader's), or null. ro/rd in grid space; `matOf` maps a word to its material (0 = air), so a mask is the caller's (gas as air, say).

<p class="meta">starburn/crates/starlab-wasm/web/view.js:413</p>

#### `draw(cam, place, light, canvas, frame, fade, skip)`

| option | type | |
|---|---|---|
| `cam` | {eye, fwd, right, up, fov} | fov in radians; grid space, or scene space when placed |
| `place` | {origin, scale, axes} | null | where the grid sits in the scene (placed looks) |
| `light` | vec3 | a direction toward the sun |
| `frame` | u32 | the twin's frame (flicker) |
| `fade` | f32 | a fade over the whole |
| `skip` | boolean | the empty-space leaps by the block distance |

#### `initView(canvas, palette, alphas, opts)`

| option | type | |
|---|---|---|
| `skip` | boolean | the leaps |
| `timeAll` | boolean | time every draw (the bench) |
| `onSample` | function | a timing sample |

## The materials

The engine names them (`starlab-sim-core/src/materials.rs`); the web colours the ones it draws (`starlab-player.js` MATS). Id 16 is the engine's canary, unnamed.

| id | the engine | the web | colour |
|---|---|---|---|
| 0 | empty | empty | · |
| 1 | sand | sand | <span class="swatch" style="background:#d6bd6f"></span> `#d6bd6f` |
| 2 | water | water | <span class="swatch" style="background:#2f6fd1"></span> `#2f6fd1` |
| 3 | lava | lava | <span class="swatch" style="background:#ff5a1f"></span> `#ff5a1f` |
| 4 | stone | stone | <span class="swatch" style="background:#767c86"></span> `#767c86` |
| 5 | ice | ice | <span class="swatch" style="background:#bfe3ff"></span> `#bfe3ff` |
| 6 | steam | steam | <span class="swatch" style="background:#c7d3e3"></span> `#c7d3e3` |
| 7 | crystal | crystal | <span class="swatch" style="background:#b48cff"></span> `#b48cff` |
| 8 | oil | oil | <span class="swatch" style="background:#2c2a26"></span> `#2c2a26` |
| 9 | fire | fire | <span class="swatch" style="background:#ffa726"></span> `#ffa726` |
| 10 | soil | soil | <span class="swatch" style="background:#6b4a2b"></span> `#6b4a2b` |
| 11 | acid | acid | <span class="swatch" style="background:#9ccc1c"></span> `#9ccc1c` |
| 12 | flora | flora | <span class="swatch" style="background:#3fa34d"></span> `#3fa34d` |
| 13 | fauna | fauna | <span class="swatch" style="background:#f06292"></span> `#f06292` |
| 14 | spore | spore | <span class="swatch" style="background:#5a5f69"></span> `#5a5f69` |
| 15 | coral | coral | <span class="swatch" style="background:#ff8a80"></span> `#ff8a80` |
| 17 | ash | ash | <span class="swatch" style="background:#9a9a94"></span> `#9a9a94` |
| 20 | brick | brick | <span class="swatch" style="background:#b5532c"></span> `#b5532c` |
| 21 | glass | glass | <span class="swatch" style="background:#9fd8d3"></span> `#9fd8d3` |
| 24 | mud | mud | <span class="swatch" style="background:#4e3b2a"></span> `#4e3b2a` |
| 26 | char | char | <span class="swatch" style="background:#1a1a1a"></span> `#1a1a1a` |

<details class="changes">
<summary>The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks</summary>

[[timeline: src=starburn/crates/starlab-wasm/web/view.js,starburn/crates/starlab-wasm/web/starlab-player.js,starburn/crates/starlab-sim-core/src/materials.rs,starburn/crates/starlab-wasm/web/api.json | kinds=commit | days=30]]

[[work: open | src=starburn/crates/starlab-wasm/web/view.js,starburn/crates/starlab-wasm/web/starlab-player.js,starburn/crates/starlab-sim-core/src/materials.rs,starburn/crates/starlab-wasm/web/api.json]]

[[work: checks | rows=lint/web-reference]]

</details>

<nav class="pager"><a href="../worker/">← worker</a><a href="../">The reference</a><a href="../player/">player →</a></nav>

*Generated by `tools/reference_pages.py` from `starburn/crates/starlab-wasm/web/view.js`, `the shims`, `starlab-sim-core/src/materials.rs`, `web/starlab-player.js`, `web/api.json`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
