Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Split the native tracer host into modules and freeze the v2 scene pack format (#893)

Nguyen Xuan And3c852d2cd35
diff --git a/changes/893.md b/changes/893.md
new file mode 100644
index 00000000..ed0a40e7
--- /dev/null
+++ b/changes/893.md
@@ -0,0 +1 @@
+- The native path tracer package takes a `kernel` option (`"legacy"` or `"cycles"`, default `"legacy"`) and documents its v2 scene pack format (#893)
diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.md
new file mode 100644
index 00000000..ed00962f
--- /dev/null
+++ b/packages/render-native/FORMAT-v2.md
@@ -0,0 +1,330 @@
+# Native Scene Pack Format v2 (`FORMAT-v2`)
+
+Frozen binary layout shared by the JavaScript v2 scene packer (`pack-input-v2.mjs`), the Rust Vulkan host (`src/host/`), and the Cycles-parity WGSL kernel (`src/cycles/`, starting with [src/cycles/abi.wgsl](./src/cycles/abi.wgsl)).
+
+All integers and IEEE-754 `f32` values are **little-endian**. Every structured record has **16-byte alignment**, zero implicit WGSL padding, and a total byte stride that is an exact multiple of 16 bytes.
+
+## `@group(0)` Binding Layout
+
+| Binding | WGSL Identifier | Kind | Element Type | Stride (B) | Align (B) | Contents |
+| ---: | :--- | :--- | :--- | ---: | ---: | :--- |
+| `0` | `kernel_params` | `uniform` | `KernelParamsV2` | `320` | `16` | Header, version, camera, bounce limits, clamp, filter, world, volume |
+| `1` | `scene_tlas` | `acceleration_structure` | Hardware TLAS | — | — | Top-level acceleration structure over per-mesh BLASes |
+| `2` | `instances` | `storage, read` | `InstanceRecord` | `160` | `16` | Per-instance transforms, BLAS/triangle offsets, visibility, light mask |
+| `3` | `triangles` | `storage, read` | `TriangleRecord` | `224` | `16` | Object-space mesh triangles (opaque first, then alpha-cutout per BLAS) |
+| `4` | `materials` | `storage, read` | `MaterialRecord` | `256` | `16` | Principled BSDF v2 parameters, flags, absorption, texture indices |
+| `5` | `emissive_triangles` | `storage, read` | `EmissiveTriangleRecord` | `96` | `16` | World-space emissive triangle list for NEE and BSDF-hit MIS |
+| `6` | `lights` | `storage, read` | `LightRecord` | `128` | `16` | Analytic lights (`point`, `spot`, `area_rect`, `area_disk`, `sun`) |
+| `7` | `light_tree_nodes` | `storage, read` | `LightTreeNode` | `64` | `16` | Orientation-aware light BVH nodes over analytic + emissive emitters |
+| `8` | `texture_descriptors` | `storage, read` | `TextureDescriptor` | `32` | `16` | Mipmapped 2D texture headers and UV transforms |
+| `9` | `texture_texels` | `storage, read` | `u32` | `4` | `4` | Packed RGBA8 / RGBA32F / RG16F texel words, IES profiles, Sobol tables |
+| `10` | `environment_texels` | `storage, read` | `vec4<f32>` | `16` | `16` | Linear HDRI texels followed by marginal/conditional CDF rows |
+| `11` | `film_accumulation` | `storage, read_write` | `vec4<f32>` | `16` | `16` | 4 planes of `image_width * image_height` vec4s (radiance+Z, albedo, normal, moments+count) |
+
+---
+
+## 1. Header & Dispatch Uniform — `KernelParamsV2` (`@binding(0)`)
+
+Total size: **320 bytes** (`20 × 16 B`), alignment: **16 bytes**.
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `4` | `4` | `u32` | `magic` | Magic word `0x36375054` (`"TP76"` / `67PT` little-endian) |
+| `4` | `4` | `4` | `u32` | `format_version` | Format version (`2` for `FORMAT-v2`) |
+| `8` | `4` | `4` | `u32` | `image_width` | Film width in pixels |
+| `12` | `4` | `4` | `u32` | `image_height` | Film height in pixels |
+| `16` | `4` | `4` | `u32` | `sample_offset` | First sample index for the current dispatch |
+| `20` | `4` | `4` | `u32` | `samples_per_dispatch` | Samples traced per pixel in one dispatch (`>= 1`) |
+| `24` | `4` | `4` | `u32` | `total_samples` | Target total samples per pixel |
+| `28` | `4` | `4` | `u32` | `seed` | Deterministic scramble seed |
+| `32` | `4` | `4` | `u32` | `kernel_flags` | Bitmask: `1=USE_LIGHT_TREE`, `2=HAS_VOLUME`, `4=HAS_SUBSURFACE`, `8=ORTHOGRAPHIC_CAMERA`, `16=ADAPTIVE_SAMPLING`, `32=TRANSPARENT_BACKGROUND` |
+| `36` | `4` | `4` | `f32` | `adaptive_threshold` | Adaptive stop threshold (`0.0` = disabled) |
+| `40` | `4` | `4` | `f32` | `clamp_direct` | Effective direct radiance ceiling at bounce `0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_direct * 3.0`) |
+| `44` | `4` | `4` | `f32` | `clamp_indirect` | Effective indirect radiance ceiling at bounce `> 0` (`0.0` or `>= 1e30` = unclamped; Cycles `sample_clamp_indirect * 3.0`) |
+| `48` | `4` | `4` | `u32` | `max_bounces` | Maximum total path bounces |
+| `52` | `4` | `4` | `u32` | `max_diffuse_bounces` | Maximum diffuse bounces |
+| `56` | `4` | `4` | `u32` | `max_glossy_bounces` | Maximum glossy specular bounces |
+| `60` | `4` | `4` | `u32` | `max_transmission_bounces` | Maximum refractive transmission bounces |
+| `64` | `4` | `4` | `u32` | `max_volume_bounces` | Maximum volume scatter bounces |
+| `68` | `4` | `4` | `u32` | `max_transparent_bounces` | Maximum straight-through alpha transparent steps |
+| `72` | `4` | `4` | `u32` | `min_bounce_rr` | Minimum bounce index before Russian roulette termination |
+| `76` | `4` | `4` | `u32` | `filter_type` | Pixel reconstruction filter (`0=box`, `1=gaussian`, `2=blackman_harris`) |
+| `80` | `4` | `4` | `f32` | `filter_width` | Filter full width in pixels (`1.0` box, `1.5` Cycles default Blackman-Harris) |
+| `84` | `4` | `4` | `u32` | `instance_count` | Number of entries in `instances` |
+| `88` | `4` | `4` | `u32` | `triangle_count` | Number of entries in `triangles` |
+| `92` | `4` | `4` | `u32` | `material_count` | Number of entries in `materials` |
+| `96` | `4` | `4` | `u32` | `emissive_triangle_count` | Number of entries in `emissive_triangles` |
+| `100` | `4` | `4` | `u32` | `light_count` | Number of entries in `lights` |
+| `104` | `4` | `4` | `u32` | `light_tree_node_count` | Number of entries in `light_tree_nodes` |
+| `108` | `4` | `4` | `u32` | `texture_count` | Number of entries in `texture_descriptors` |
+| `112` | `12` | `16` | `vec3<f32>` | `camera_position` | World-space camera origin |
+| `124` | `4` | `4` | `f32` | `camera_near` | Near clip distance in metres |
+| `128` | `12` | `16` | `vec3<f32>` | `camera_forward` | Unit world-space forward direction |
+| `140` | `4` | `4` | `f32` | `camera_far` | Far clip distance in metres |
+| `144` | `12` | `16` | `vec3<f32>` | `camera_right` | Scaled horizontal sensor half-extent vector in world space |
+| `156` | `4` | `4` | `f32` | `aperture_radius` | Thin-lens aperture radius in metres (`0.0` = pinhole) |
+| `160` | `12` | `16` | `vec3<f32>` | `camera_up` | Scaled vertical sensor half-extent vector in world space |
+| `172` | `4` | `4` | `f32` | `focal_distance` | Thin-lens focus distance in metres along `camera_forward` |
+| `176` | `8` | `8` | `vec2<f32>` | `lens_shift` | Sensor shift `(shift_x, shift_y)` in normalized sensor units |
+| `184` | `4` | `4` | `u32` | `aperture_blades` | Polygonal bokeh blade count (`0` = circular disk, `>= 3` = polygon) |
+| `188` | `4` | `4` | `f32` | `aperture_rotation` | Bokeh diaphragm rotation in radians |
+| `192` | `4` | `4` | `u32` | `env_width` | Equirectangular HDRI width (`0` = constant `env_color` only) |
+| `196` | `4` | `4` | `u32` | `env_height` | Equirectangular HDRI height |
+| `200` | `4` | `4` | `u32` | `env_cdf_offset` | `vec4<f32>` index in `environment_texels` where CDF tables start |
+| `204` | `4` | `4` | `f32` | `env_rotation` | HDRI azimuth rotation in radians |
+| `208` | `12` | `16` | `vec3<f32>` | `env_color` | Background linear RGB radiance / HDRI multiplier |
+| `220` | `4` | `4` | `f32` | `env_total_weight` | Total integrated HDRI weight (`luminance * sin(theta) * d_omega`) |
+| `224` | `12` | `16` | `vec3<f32>` | `volume_bounds_min` | World AABB minimum of homogeneous fog volume |
+| `236` | `4` | `4` | `f32` | `volume_density` | Extinction density `sigma_t` (`0.0` = no world volume) |
+| `240` | `12` | `16` | `vec3<f32>` | `volume_bounds_max` | World AABB maximum of homogeneous fog volume |
+| `252` | `4` | `4` | `f32` | `volume_anisotropy` | Henyey-Greenstein phase `g` in `[-0.99, 0.99]` |
+| `256` | `12` | `16` | `vec3<f32>` | `volume_albedo` | Single-scatter RGB albedo of homogeneous fog |
+| `268` | `4` | `4` | `f32` | `emissive_total_weight` | Sum of `EmissiveTriangleRecord.selection_weight` |
+| `272` | `4` | `4` | `f32` | `analytic_light_total_weight` | Sum of analytic light selection weights |
+| `276` | `4` | `4` | `f32` | `ray_epsilon` | Ray origin offset scale (default `1e-4`) |
+| `280` | `4` | `4` | `u32` | `adaptive_min_samples` | Minimum samples before adaptive convergence checks |
+| `284` | `4` | `4` | `u32` | `ies_table_offset` | Word offset into `texture_texels` for packed IES profiles |
+| `288` | `4` | `4` | `f32` | `film_exposure` | Linear exposure multiplier applied on film accumulation (default `1.0`) |
+| `292` | `4` | `4` | `f32` | `background_mis_weight` | `1.0` when environment MIS is active, `0.0` otherwise |
+| `296` | `4` | `4` | `u32` | `sobol_table_offset` | Word offset into `texture_texels` for Sobol / blue-noise tables |
+| `300` | `4` | `4` | `u32` | `reserved_u0` | Reserved (`0`) |
+| `304` | `16` | `16` | `vec4<u32>` | `reserved_tail` | Reserved (`[0, 0, 0, 0]`) |
+
+---
+
+## 2. Instance Table — `InstanceRecord` (`@binding(2)`)
+
+Total stride: **160 bytes** (`10 × 16 B`), alignment: **16 bytes**. Indexed by `ray_query` `intersection.instance_custom_data` (or `instance_index`).
+
+Both 3×4 affine transforms are stored as three row vectors `row0..row2`: transforming an object-space point `p` computes `vec3(dot(row0.xyz, p) + row0.w, dot(row1.xyz, p) + row1.w, dot(row2.xyz, p) + row2.w)`. Object-space normals transform by the transpose of the upper-left 3×3 of `world_to_object` (`n_world = normalize(n.x * w2o_row0.xyz + n.y * w2o_row1.xyz + n.z * w2o_row2.xyz)`).
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `16` | `16` | `vec4<f32>` | `object_to_world_row0` | Affine row 0 `[m00, m01, m02, tx]` (matches `wgpu::TlasInstance` row 0) |
+| `16` | `16` | `16` | `vec4<f32>` | `object_to_world_row1` | Affine row 1 `[m10, m11, m12, ty]` |
+| `32` | `16` | `16` | `vec4<f32>` | `object_to_world_row2` | Affine row 2 `[m20, m21, m22, tz]` |
+| `48` | `16` | `16` | `vec4<f32>` | `world_to_object_row0` | Inverse affine row 0 `[im00, im01, im02, itx]` |
+| `64` | `16` | `16` | `vec4<f32>` | `world_to_object_row1` | Inverse affine row 1 `[im10, im11, im12, ity]` |
+| `80` | `16` | `16` | `vec4<f32>` | `world_to_object_row2` | Inverse affine row 2 `[im20, im21, im22, itz]` |
+| `96` | `4` | `4` | `u32` | `blas_index` | Mesh BLAS index in the host acceleration pool |
+| `100` | `4` | `4` | `u32` | `triangle_offset` | Base index into `triangles` for this mesh's primitives |
+| `104` | `4` | `4` | `u32` | `opaque_triangle_count` | Count of opaque primitives in BLAS geometry `0`; cutout geometry `1` starts at `triangle_offset + opaque_triangle_count` |
+| `108` | `4` | `4` | `u32` | `total_triangle_count` | Total primitives (`opaque + cutout`) in this mesh BLAS |
+| `112` | `4` | `4` | `u32` | `material_override` | Override material index (e.g. clay pass), or `0xFFFFFFFF` to use `TriangleRecord.material_index` |
+| `116` | `4` | `4` | `u32` | `visibility_flags` | Bitmask: `1=CAMERA`, `2=DIFFUSE`, `4=GLOSSY`, `8=TRANSMISSION`, `16=SHADOW`, `32=VOLUME_SCATTER`, `64=NEGATIVE_SCALE` (`det(M) < 0`) |
+| `120` | `4` | `4` | `u32` | `light_group_mask_lo` | Low 32 bits of 64-bit receiver light-linking mask (default `0xFFFFFFFF`) |
+| `124` | `4` | `4` | `u32` | `light_group_mask_hi` | High 32 bits of 64-bit receiver light-linking mask (default `0xFFFFFFFF`) |
+| `128` | `4` | `4` | `u32` | `emissive_base_offset` | Base index in `emissive_triangles` for this instance, or `0xFFFFFFFF` if non-emissive |
+| `132` | `4` | `4` | `u32` | `object_id` | Cycles Object Info `Object Index` |
+| `136` | `4` | `4` | `f32` | `object_random` | Deterministic `[0, 1)` per-instance Object Info `Random` hash |
+| `140` | `4` | `4` | `f32` | `shadow_terminator_offset` | Cycles shadow terminator normal shift in `[0, 1)` |
+| `144` | `16` | `16` | `vec4<f32>` | `object_color` | Cycles Object Info linear RGBA colour |
+
+---
+
+## 3. Object-Space Mesh Triangles — `TriangleRecord` (`@binding(3)`)
+
+Total stride: **224 bytes** (`14 × 16 B`), alignment: **16 bytes**. Within each mesh BLAS slice (`triangle_offset .. triangle_offset + total_triangle_count`), opaque triangles occupy `[0 .. opaque_triangle_count)` (BLAS geometry `0`) and alpha-cutout triangles occupy `[opaque_triangle_count .. total_triangle_count)` (BLAS geometry `1`, when `opaque_triangle_count > 0`; otherwise geometry `0`).
+
+When `InstanceRecord.emissive_base_offset != 0xFFFFFFFF` and `TriangleRecord.local_emissive_offset != 0xFFFFFFFF`, the world-space `EmissiveTriangleRecord` for MIS is at `emissive_base_offset + local_emissive_offset`.
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `12` | `16` | `vec3<f32>` | `p0` | Object-space vertex 0 position |
+| `12` | `4` | `4` | `u32` | `material_index` | Default `MaterialRecord` index |
+| `16` | `12` | `16` | `vec3<f32>` | `edge1` | Object-space `p1 - p0` |
+| `28` | `4` | `4` | `u32` | `local_emissive_offset` | Offset from `InstanceRecord.emissive_base_offset`, or `0xFFFFFFFF` |
+| `32` | `12` | `16` | `vec3<f32>` | `edge2` | Object-space `p2 - p0` |
+| `44` | `4` | `4` | `u32` | `flags` | Bitmask: `1=SMOOTH_NORMALS`, `2=HAS_VERTEX_COLORS`, `4=HAS_UV1`, `8=HAS_TANGENTS`, `16=DOUBLE_SIDED` |
+| `48` | `12` | `16` | `vec3<f32>` | `n0` | Object-space vertex 0 normal |
+| `60` | `4` | `4` | `f32` | `uv0_u` | Primary UV0 `u` at vertex 0 |
+| `64` | `12` | `16` | `vec3<f32>` | `n1` | Object-space vertex 1 normal |
+| `76` | `4` | `4` | `f32` | `uv0_v` | Primary UV0 `v` at vertex 0 |
+| `80` | `12` | `16` | `vec3<f32>` | `n2` | Object-space vertex 2 normal |
+| `92` | `4` | `4` | `f32` | `uv1_u` | Primary UV0 `u` at vertex 1 |
+| `96` | `12` | `16` | `vec3<f32>` | `tangent0` | Object-space vertex 0 tangent |
+| `108` | `4` | `4` | `f32` | `uv1_v` | Primary UV0 `v` at vertex 1 |
+| `112` | `12` | `16` | `vec3<f32>` | `tangent1` | Object-space vertex 1 tangent |
+| `124` | `4` | `4` | `f32` | `uv2_u` | Primary UV0 `u` at vertex 2 |
+| `128` | `12` | `16` | `vec3<f32>` | `tangent2` | Object-space vertex 2 tangent |
+| `140` | `4` | `4` | `f32` | `uv2_v` | Primary UV0 `v` at vertex 2 |
+| `144` | `12` | `16` | `vec3<f32>` | `color0` | Linear RGB vertex colour at vertex 0 |
+| `156` | `4` | `4` | `f32` | `tangent_sign` | Bitangent handedness (`+1.0` or `-1.0`) |
+| `160` | `12` | `16` | `vec3<f32>` | `color1` | Linear RGB vertex colour at vertex 1 |
+| `172` | `4` | `4` | `u32` | `mesh_id` | Mesh identifier |
+| `176` | `12` | `16` | `vec3<f32>` | `color2` | Linear RGB vertex colour at vertex 2 |
+| `188` | `4` | `4` | `u32` | `primitive_id` | Original mesh primitive index |
+| `192` | `8` | `8` | `vec2<f32>` | `uv_set1_0` | Secondary UV1 (`UV2`) at vertex 0 |
+| `200` | `8` | `8` | `vec2<f32>` | `uv_set1_1` | Secondary UV1 (`UV2`) at vertex 1 |
+| `208` | `8` | `8` | `vec2<f32>` | `uv_set1_2` | Secondary UV1 (`UV2`) at vertex 2 |
+| `216` | `4` | `4` | `u32` | `attribute_offset` | Optional custom attribute word offset in `texture_texels`, or `0xFFFFFFFF` |
+| `220` | `4` | `4` | `u32` | `reserved_u0` | Reserved (`0`) |
+
+---
+
+## 4. Material Table (Principled BSDF v2) — `MaterialRecord` (`@binding(4)`)
+
+Total stride: **256 bytes** (`16 × 16 B`), alignment: **16 bytes**.
+
+Includes all Principled BSDF v2 fields needed for Cycles parity:
+- **Multiscatter GGX**: bit `0` (`MATERIAL_FLAG_MULTISCATTER_GGX = 1`) in `flags` (offset `192`).
+- **Conductor F82-tint & dielectric specular tint**: `f82_tint` (`vec3<f32>` at offset `32`) plus `MATERIAL_FLAG_F82_METALLIC` (`32`).
+- **Surface anisotropy**: `anisotropy` (`f32` at offset `44`), `anisotropy_rotation` (`f32` at offset `48`), `anisotropy_tex` (`i32` at offset `244`).
+- **Clearcoat with tint**: `coat_tint` (`vec3<f32>` at offset `64`), `coat_weight` (`f32` at offset `76`), `coat_roughness` (`f32` at offset `80`), `coat_ior` (`f32` at offset `84`).
+- **Thin-film iridescence**: `thin_film_thickness` (`f32` nm at offset `88`), `thin_film_ior` (`f32` at offset `92`).
+- **Microfiber sheen**: `sheen_tint` (`vec3<f32>` at offset `96`), `sheen_weight` (`f32` at offset `108`), `sheen_roughness` (`f32` at offset `176`).
+- **Beer-Lambert volume absorption**: `absorption_color` (`vec3<f32>` at offset `112`) and `absorption_distance` (`f32` metres at offset `124`; when `> 0`, `sigma_a = -ln(max(absorption_color, vec3(1e-6))) / absorption_distance`).
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `12` | `16` | `vec3<f32>` | `base_color` | Linear RGB base albedo `[0, 1]` |
+| `12` | `4` | `4` | `f32` | `metallic` | Metallic weight `[0, 1]` |
+| `16` | `4` | `4` | `f32` | `roughness` | Perceptual specular roughness `[0, 1]` |
+| `20` | `4` | `4` | `f32` | `ior` | Base dielectric index of refraction (default `1.5`) |
+| `24` | `4` | `4` | `f32` | `specular_ior_level` | Cycles Specular IOR Level (`0.5` = unscaled dielectric Fresnel) |
+| `28` | `4` | `4` | `f32` | `diffuse_roughness` | Oren-Nayar / Principled v2 diffuse roughness `[0, 1]` |
+| `32` | `12` | `16` | `vec3<f32>` | `f82_tint` | Conductor F82 grazing tint / dielectric specular tint RGB (default `[1, 1, 1]`) |
+| `44` | `4` | `4` | `f32` | `anisotropy` | Microfacet aspect anisotropy `[0, 1]` |
+| `48` | `4` | `4` | `f32` | `anisotropy_rotation` | Tangent rotation in `[0, 1)` turns (`* 2 * pi` radians) |
+| `52` | `4` | `4` | `f32` | `transmission_weight` | Dielectric refractive transmission weight `[0, 1]` |
+| `56` | `4` | `4` | `f32` | `alpha` | Base opacity `[0, 1]` (default `1.0`) |
+| `60` | `4` | `4` | `f32` | `alpha_cutoff` | Alpha-mask threshold `[0, 1]` (`0.0` if `alpha_mode != MASK`) |
+| `64` | `12` | `16` | `vec3<f32>` | `coat_tint` | Clearcoat transmission tint RGB (default `[1, 1, 1]`) |
+| `76` | `4` | `4` | `f32` | `coat_weight` | Clearcoat layer weight `[0, 1]` |
+| `80` | `4` | `4` | `f32` | `coat_roughness` | Clearcoat perceptual roughness `[0, 1]` |
+| `84` | `4` | `4` | `f32` | `coat_ior` | Clearcoat IOR (default `1.5`) |
+| `88` | `4` | `4` | `f32` | `thin_film_thickness` | Thin-film thickness in nanometres (`0.0` = disabled) |
+| `92` | `4` | `4` | `f32` | `thin_film_ior` | Thin-film refractive index (default `1.33`) |
+| `96` | `12` | `16` | `vec3<f32>` | `sheen_tint` | Principled v2 sheen RGB tint (default `[1, 1, 1]`) |
+| `108` | `4` | `4` | `f32` | `sheen_weight` | Sheen layer weight `[0, 1]` |
+| `112` | `12` | `16` | `vec3<f32>` | `absorption_color` | Beer-Lambert transmitted RGB colour at `absorption_distance` |
+| `124` | `4` | `4` | `f32` | `absorption_distance` | Beer-Lambert reference distance in metres (`0.0` = no interior absorption) |
+| `128` | `12` | `16` | `vec3<f32>` | `emission_color` | Linear RGB emission colour |
+| `140` | `4` | `4` | `f32` | `emission_strength` | Emission radiance multiplier in `W/(sr·m²)` |
+| `144` | `12` | `16` | `vec3<f32>` | `subsurface_radius` | Scaled RGB subsurface mean free path in metres |
+| `156` | `4` | `4` | `f32` | `subsurface_weight` | Subsurface scattering blend weight `[0, 1]` |
+| `160` | `12` | `16` | `vec3<f32>` | `subsurface_color` | Subsurface scattering RGB albedo |
+| `172` | `4` | `4` | `f32` | `subsurface_anisotropy` | Subsurface phase anisotropy `[-0.9, 0.9]` |
+| `176` | `4` | `4` | `f32` | `sheen_roughness` | Principled v2 microfiber sheen roughness `[0, 1]` |
+| `180` | `4` | `4` | `f32` | `subsurface_ior` | Subsurface boundary IOR (default `1.4`) |
+| `184` | `4` | `4` | `f32` | `normal_scale` | Base normal map strength (default `1.0`) |
+| `188` | `4` | `4` | `f32` | `coat_normal_scale` | Clearcoat normal map strength (default `1.0`) |
+| `192` | `4` | `4` | `u32` | `flags` | Bitmask: `1=MULTISCATTER_GGX`, `2=THIN_WALLED`, `4=TRANSPARENT_SHADOW`, `8=DOUBLE_SIDED`, `16=EMISSIVE_MIS`, `32=F82_METALLIC`, `64=HAS_SHADER_GRAPH` |
+| `196` | `4` | `4` | `u32` | `alpha_mode` | `0=OPAQUE`, `1=MASK`, `2=BLEND` |
+| `200` | `4` | `4` | `f32` | `bump_distance` | Height-map bump world scale in metres (`0.0` = disabled) |
+| `204` | `4` | `4` | `u32` | `svm_node_offset` | Shader graph bytecode word offset, or `0xFFFFFFFF` |
+| `208` | `4` | `4` | `i32` | `base_color_tex` | `TextureDescriptor` index, or `-1` |
+| `212` | `4` | `4` | `i32` | `metallic_roughness_tex` | `TextureDescriptor` index (G = roughness, B = metallic), or `-1` |
+| `216` | `4` | `4` | `i32` | `normal_tex` | `TextureDescriptor` index, or `-1` |
+| `220` | `4` | `4` | `i32` | `emission_tex` | `TextureDescriptor` index, or `-1` |
+| `224` | `4` | `4` | `i32` | `transmission_tex` | `TextureDescriptor` index, or `-1` |
+| `228` | `4` | `4` | `i32` | `coat_weight_roughness_tex` | `TextureDescriptor` index, or `-1` |
+| `232` | `4` | `4` | `i32` | `coat_tint_tex` | `TextureDescriptor` index, or `-1` |
+| `236` | `4` | `4` | `i32` | `coat_normal_tex` | `TextureDescriptor` index, or `-1` |
+| `240` | `4` | `4` | `i32` | `sheen_color_roughness_tex` | `TextureDescriptor` index, or `-1` |
+| `244` | `4` | `4` | `i32` | `anisotropy_tex` | `TextureDescriptor` index, or `-1` |
+| `248` | `4` | `4` | `i32` | `alpha_tex` | `TextureDescriptor` index, or `-1` |
+| `252` | `4` | `4` | `i32` | `bump_tex` | `TextureDescriptor` index, or `-1` |
+
+---
+
+## 5. Emissive Triangle List — `EmissiveTriangleRecord` (`@binding(5)`)
+
+Total stride: **96 bytes** (`6 × 16 B`), alignment: **16 bytes**.
+
+Stored in **world space** (one entry per emissive `(instance, triangle)` pair) so NEE area/solid-angle sampling, light-tree bounds, and BSDF-hit MIS PDF evaluation require no per-sample matrix transforms.
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `12` | `16` | `vec3<f32>` | `p0` | World-space vertex 0 |
+| `12` | `4` | `4` | `f32` | `area` | World-space surface area `0.5 * length(cross(edge1, edge2))` in `m²` (`> 0`) |
+| `16` | `12` | `16` | `vec3<f32>` | `edge1` | World-space `p1 - p0` |
+| `28` | `4` | `4` | `u32` | `instance_index` | Owning `InstanceRecord` index |
+| `32` | `12` | `16` | `vec3<f32>` | `edge2` | World-space `p2 - p0` |
+| `44` | `4` | `4` | `u32` | `triangle_index` | Owning `TriangleRecord` index |
+| `48` | `12` | `16` | `vec3<f32>` | `geometric_normal` | Unit world-space outward geometric normal (flipped when `NEGATIVE_SCALE` is set) |
+| `60` | `4` | `4` | `u32` | `material_index` | Resolved `MaterialRecord` index |
+| `64` | `12` | `16` | `vec3<f32>` | `radiance` | Emitted linear RGB radiance in `W/(sr·m²)` (mean radiance if textured) |
+| `76` | `4` | `4` | `f32` | `selection_weight` | Unnormalized importance weight (`luminance(radiance) * area`) |
+| `80` | `4` | `4` | `f32` | `selection_pdf` | Discrete flat-table selection probability in `(0, 1]` |
+| `84` | `4` | `4` | `f32` | `cdf_upper` | Inclusive cumulative probability in `(0, 1]` for binary search |
+| `88` | `4` | `4` | `u32` | `light_group_mask_lo` | Low 32 bits of 64-bit emitter light-linking mask |
+| `92` | `4` | `4` | `u32` | `light_group_mask_hi` | High 32 bits of 64-bit emitter light-linking mask |
+
+---
+
+## 6. Analytic Light Table — `LightRecord` (`@binding(6)`)
+
+Total stride: **128 bytes** (`8 × 16 B`), alignment: **16 bytes**.
+
+Convention: `direction` is always the **unit emission direction pointing from the emitter into the scene** (spot cone axis, area light front normal, and sun ray travel direction; rays toward the sun trace along `-direction`).
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `12` | `16` | `vec3<f32>` | `position` | World-space centre (`point`, `spot`, `area_rect`, `area_disk`; unused for `sun`) |
+| `12` | `4` | `4` | `u32` | `light_type` | `0=point`, `1=spot`, `2=area_rect`, `3=area_disk`, `4=sun` |
+| `16` | `12` | `16` | `vec3<f32>` | `radiance` | Emitted linear RGB radiance (`W/(sr·m²)` for finite-area/sun, intensity `W/sr` when `radius == 0`) |
+| `28` | `4` | `4` | `u32` | `flags` | Bitmask: `1=CAST_SHADOW`, `2=MULTIPLE_IMPORTANCE`, `4=CAMERA_VISIBLE`, `8=PORTAL`, `16=NORMALIZE` |
+| `32` | `12` | `16` | `vec3<f32>` | `direction` | Unit world-space emission direction |
+| `44` | `4` | `4` | `f32` | `radius` | Sphere radius in metres for `point` / `spot` (`0.0` = delta emitter) |
+| `48` | `12` | `16` | `vec3<f32>` | `axis_u` | Unit tangent axis U for area / IES orientation |
+| `60` | `4` | `4` | `f32` | `size_u` | Full width in metres (`area_rect`) or major diameter (`area_disk`) |
+| `64` | `12` | `16` | `vec3<f32>` | `axis_v` | Unit bitangent axis V (`cross(direction, axis_u)`) |
+| `76` | `4` | `4` | `f32` | `size_v` | Full height in metres (`area_rect`) or minor diameter (`area_disk`) |
+| `80` | `4` | `4` | `f32` | `cos_half_angle` | `cos(spot_size * 0.5)` for `spot`; `cos(sun_angle * 0.5)` for `sun` |
+| `84` | `4` | `4` | `f32` | `spot_blend` | Cycles spot softness blend `[0, 1]` |
+| `88` | `4` | `4` | `f32` | `tan_half_spread` | `tan(spread * 0.5)` for Cycles area beam spread |
+| `92` | `4` | `4` | `f32` | `spread_normalization` | Cycles area beam spread normalization multiplier |
+| `96` | `4` | `4` | `f32` | `area_or_solid_angle` | Emitter surface area (`m²`) or sun solid angle `2 * pi * (1 - cos_half_angle)` (`sr`) |
+| `100` | `4` | `4` | `f32` | `max_distance` | Maximum influence distance in metres (`>= 1e30` = infinite) |
+| `104` | `4` | `4` | `i32` | `ies_profile_index` | IES photometric profile index, or `-1` |
+| `108` | `4` | `4` | `u32` | `tree_leaf_index` | Owning `LightTreeNode` leaf index, or `0xFFFFFFFF` |
+| `112` | `4` | `4` | `f32` | `selection_pdf` | Discrete flat-table selection probability in `(0, 1]` |
+| `116` | `4` | `4` | `f32` | `cdf_upper` | Inclusive cumulative probability in `(0, 1]` |
+| `120` | `4` | `4` | `u32` | `light_group_mask_lo` | Low 32 bits of 64-bit emitter light-linking mask |
+| `124` | `4` | `4` | `u32` | `light_group_mask_hi` | High 32 bits of 64-bit emitter light-linking mask |
+
+---
+
+## 7. Light Tree Nodes — `LightTreeNode` (`@binding(7)`)
+
+Total stride: **64 bytes** (`4 × 16 B`), alignment: **16 bytes**.
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `12` | `16` | `vec3<f32>` | `bounds_min` | World AABB minimum of emitters in subtree |
+| `12` | `4` | `4` | `f32` | `energy` | Total radiant flux proxy of subtree |
+| `16` | `12` | `16` | `vec3<f32>` | `bounds_max` | World AABB maximum of emitters in subtree |
+| `28` | `4` | `4` | `f32` | `theta_o` | Orientation cone axis half-angle `[0, pi]` |
+| `32` | `12` | `16` | `vec3<f32>` | `cone_axis` | Unit orientation cone axis |
+| `44` | `4` | `4` | `f32` | `theta_e` | Emission spread half-angle `[0, pi]` |
+| `48` | `4` | `4` | `i32` | `left_child` | Left child index when `>= 0`; `< 0` marks a leaf node |
+| `52` | `4` | `4` | `u32` | `right_or_first_emitter` | Right child index (internal) or first emitter index (leaf) |
+| `56` | `4` | `4` | `u32` | `emitter_count_and_kind` | Bits `0..15`: leaf count; bit `16`: `0=LightRecord`, `1=EmissiveTriangleRecord`; bit `17`: distant subtree |
+| `60` | `4` | `4` | `u32` | `light_group_mask_or` | Bitwise OR of subtree low-32 light-linking masks |
+
+---
+
+## 8. Texture Descriptors — `TextureDescriptor` (`@binding(8)`)
+
+Total stride: **32 bytes** (`2 × 16 B`), alignment: **16 bytes**.
+
+| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
+| ---: | ---: | ---: | :--- | :--- | :--- |
+| `0` | `4` | `16` | `u32` | `data_offset` | Base `u32` word offset in `texture_texels` (`@binding(9)`, `@align(16)`) |
+| `4` | `4` | `4` | `u32` | `width` | Mip `0` width in texels |
+| `8` | `4` | `4` | `u32` | `height` | Mip `0` height in texels |
+| `12` | `4` | `4` | `u32` | `format_and_sampler` | Bits `0..7`: `0=RGBA8_UNORM`, `1=RGBA8_SRGB`, `2=RGBA32_FLOAT`, `3=RG16_FLOAT`; bits `8..15`: mip count; bits `16..17`: wrap U; bits `18..19`: wrap V; bit `20`: nearest; bit `21`: use `UV1` |
+| `16` | `8` | `8` | `vec2<f32>` | `uv_scale` | UV scale `(su, sv)` |
+| `24` | `8` | `8` | `vec2<f32>` | `uv_offset` | UV offset `(ou, ov)` |
+
+---
+
+## 9. Film Accumulation Buffer (`@binding(11)`)
+
+`film_accumulation` holds `4 * image_width * image_height` elements of `vec4<f32>` (`64 bytes` per pixel across 4 contiguous planes of length `pixel_count = image_width * image_height`):
+
+1. **Plane 0 (`0 .. pixel_count`)**: `[sum_r, sum_g, sum_b, sum_depth]`
+2. **Plane 1 (`pixel_count .. 2 * pixel_count`)**: `[sum_albedo_r, sum_albedo_g, sum_albedo_b, 0.0]`
+3. **Plane 2 (`2 * pixel_count .. 3 * pixel_count`)**: `[sum_normal_x, sum_normal_y, sum_normal_z, 0.0]`
+4. **Plane 3 (`3 * pixel_count .. 4 * pixel_count`)**: `[sum_luminance, sum_luminance_sq, converged_flag, sample_count]`
diff --git a/packages/render-native/README.md b/packages/render-native/README.md
index f8ac633e..62f8ce89 100644
--- a/packages/render-native/README.md
+++ b/packages/render-native/README.md
@@ -19,7 +19,7 @@ const { rgba, adapter, tracedSeconds } = traceNative(input, options);
`rgba` is linear float RGBA, rows from the top, averaged over the samples. `albedo` and `normal` (three floats per pixel, normalise the normal), `depth` and `variance` (one float) are the first-hit features the wavelet and OIDN denoisers read. `pack-input.mjs` holds `buildNativeInput` without Node imports, so the job page packs the scene itself. `bench/native-tracer` compares it with the browser kernel.
-Fog (`scene.volume`), subsurface scattering and `options.noiseThreshold` (the CPU tracer's stop rule: converged pixels draw no more samples, `averageSamples` in the result is the mean drawn) are in the kernel. `traceNative` also takes `maxSeconds`: the trace stops with an error ("passed its time limit") once it has run that long. Alpha cutouts are traced by stepping through transparent texels in the kernel (the acceleration structure is opaque).
+Fog (`scene.volume`), subsurface scattering and `options.noiseThreshold` (the CPU tracer's stop rule: converged pixels draw no more samples, `averageSamples` in the result is the mean drawn) are in the kernel. `traceNative` also takes `maxSeconds` (stopping with an error once the trace has run that long) and `kernel` (`"legacy"` by default, or `"cycles"`, with `JS67_NATIVE_KERNEL` as environment fallback; see [FORMAT-v2.md](./FORMAT-v2.md)). Alpha cutouts are traced by stepping through transparent texels in the kernel (the acceleration structure is opaque).
The light bake uses the texel entry of the same kernel:
diff --git a/packages/render-native/build.mjs b/packages/render-native/build.mjs
index 4a5548d8..f5f15848 100644
--- a/packages/render-native/build.mjs
+++ b/packages/render-native/build.mjs
@@ -2,7 +2,7 @@
// Windows must target MSVC: the default GNU toolchain crashes any wgpu 30 program before main.
import { spawnSync } from 'node:child_process';
import { copyFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const packageDirectory = dirname(fileURLToPath(import.meta.url));
@@ -10,7 +10,10 @@ const targetArguments = process.platform === 'win32' ? ['--target', 'x86_64-pc-w
const build = spawnSync('cargo', ['build', '--release', ...targetArguments], { cwd: packageDirectory, stdio: 'inherit' });
if (build.status !== 0) process.exit(build.status ?? 1);
-const releaseDirectory = join(packageDirectory, 'target', ...(targetArguments.length > 0 ? [targetArguments[1]] : []), 'release');
+const targetDirectory = process.env.CARGO_TARGET_DIR
+ ? resolve(packageDirectory, process.env.CARGO_TARGET_DIR)
+ : join(packageDirectory, 'target');
+const releaseDirectory = join(targetDirectory, ...(targetArguments.length > 0 ? [targetArguments[1]] : []), 'release');
const libraryName = { win32: 'render_native.dll', darwin: 'librender_native.dylib', linux: 'librender_native.so' }[process.platform];
mkdirSync(join(packageDirectory, 'build'), { recursive: true });
copyFileSync(join(releaseDirectory, libraryName), join(packageDirectory, 'build', 'render-native.node'));
diff --git a/packages/render-native/build.rs b/packages/render-native/build.rs
index 0f1b0100..4aeaf110 100644
--- a/packages/render-native/build.rs
+++ b/packages/render-native/build.rs
@@ -1,3 +1,72 @@
+use std::env;
+use std::fs;
+use std::path::{Component, Path, PathBuf};
+
+fn parse_manifest_entries(manifest_text: &str) -> Vec<String> {
+ let mut entries = Vec::new();
+ for raw_line in manifest_text.lines() {
+ let without_comment = raw_line.split('#').next().unwrap_or("");
+ let trimmed = without_comment.trim();
+ if !trimmed.is_empty() {
+ entries.push(trimmed.to_string());
+ }
+ }
+ entries
+}
+
+fn validate_relative_shader_path(cycles_directory: &Path, relative_entry: &str) -> PathBuf {
+ let entry_path = Path::new(relative_entry);
+ if entry_path.is_absolute() {
+ panic!("Cycles kernel manifest entry must be relative: {relative_entry}");
+ }
+ for component in entry_path.components() {
+ if !matches!(component, Component::Normal(_)) {
+ panic!("Cycles kernel manifest entry must stay inside src/cycles: {relative_entry}");
+ }
+ }
+ let resolved = cycles_directory.join(entry_path);
+ if !resolved.is_file() {
+ panic!("Cycles kernel manifest entry does not exist: src/cycles/{relative_entry}");
+ }
+ resolved
+}
+
+fn rust_byte_array_literal(bytes: &[u8]) -> String {
+ let mut text = String::with_capacity(bytes.len() * 4 + 4);
+ text.push_str("&[");
+ for (index, byte) in bytes.iter().enumerate() {
+ if index > 0 {
+ text.push(',');
+ }
+ text.push_str(&byte.to_string());
+ }
+ text.push(']');
+ text
+}
+
fn main() {
napi_build::setup();
+
+ let cycles_directory = PathBuf::from("src").join("cycles");
+ let manifest_path = cycles_directory.join("kernel-manifest.txt");
+ println!("cargo:rerun-if-changed={}", manifest_path.display());
+
+ let manifest_text = fs::read_to_string(&manifest_path)
+ .unwrap_or_else(|error| panic!("Could not read {}: {error}", manifest_path.display()));
+ let entries = parse_manifest_entries(&manifest_text);
+
+ let mut generated = String::from("pub(crate) const CYCLES_MANIFEST_FILES: &[(&str, &[u8])] = &[\n");
+ for entry in &entries {
+ let shader_path = validate_relative_shader_path(&cycles_directory, entry);
+ println!("cargo:rerun-if-changed={}", shader_path.display());
+ let shader_bytes = fs::read(&shader_path)
+ .unwrap_or_else(|error| panic!("Could not read {}: {error}", shader_path.display()));
+ generated.push_str(&format!(" ({entry:?}, {}),\n", rust_byte_array_literal(&shader_bytes)));
+ }
+ generated.push_str("];\n");
+
+ let out_directory = PathBuf::from(env::var("OUT_DIR").expect("OUT_DIR must be set by cargo"));
+ let generated_path = out_directory.join("cycles_manifest_files.rs");
+ fs::write(&generated_path, generated)
+ .unwrap_or_else(|error| panic!("Could not write {}: {error}", generated_path.display()));
}
diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjs
index 0472ca30..d1343bf9 100644
--- a/packages/render-native/index.mjs
+++ b/packages/render-native/index.mjs
@@ -9,19 +9,37 @@ export { buildNativeInput, buildNativeTexelInput } from './pack-input.mjs';
const PACKAGE_DIRECTORY = dirname(fileURLToPath(import.meta.url));
const ADDON_PATH = join(PACKAGE_DIRECTORY, 'build', 'render-native.node');
+const VALID_KERNELS = new Set(['legacy', 'cycles']);
/** The path of the built addon, or null when `npm run build` has not run. */
export function findNativeAddon() {
return existsSync(ADDON_PATH) ? ADDON_PATH : null;
}
+/**
+ * Resolves and validates the native kernel name from `kernel`, falling back to `JS67_NATIVE_KERNEL` and `'legacy'`.
+ */
+export function resolveNativeKernel(kernel) {
+ const envKernel = process.env.JS67_NATIVE_KERNEL;
+ const selectedKernel = kernel !== undefined
+ ? kernel
+ : (envKernel !== undefined && envKernel !== '' ? envKernel : 'legacy');
+ if (typeof selectedKernel !== 'string' || !VALID_KERNELS.has(selectedKernel)) {
+ throw new Error(
+ `Invalid native kernel ${JSON.stringify(selectedKernel)}: pass "legacy" or "cycles" in options.kernel or JS67_NATIVE_KERNEL.`
+ );
+ }
+ return selectedKernel;
+}
+
/**
* Traces the input on the GPU and resolves linear RGBA float data (`rgba`, width * height * 4, rows from the top, the
* average of `samples` paths) with the adapter name and timings in seconds. `maxSeconds` makes the trace fail once it has
- * run that long.
+ * run that long. `kernel` selects `"legacy"` (default) or `"cycles"` (falling back to `JS67_NATIVE_KERNEL` when omitted).
*/
-export function traceNative(input, { width, height, samples, maxSeconds }) {
- return loadAddon().traceScene(input, { width, height, samples, maxSeconds });
+export function traceNative(input, { width, height, samples, maxSeconds, kernel } = {}) {
+ const selectedKernel = resolveNativeKernel(kernel);
+ return loadAddon().traceScene(input, { width, height, samples, maxSeconds, kernel: selectedKernel });
}
/**
diff --git a/packages/render-native/package.json b/packages/render-native/package.json
index 53381cff..6982806c 100644
--- a/packages/render-native/package.json
+++ b/packages/render-native/package.json
@@ -10,6 +10,8 @@
"files": [
"index.mjs",
"pack-input.mjs",
+ "pack-input-v2.mjs",
+ "FORMAT-v2.md",
"build.mjs",
"build.rs",
"Cargo.toml",
diff --git a/packages/render-native/src/cycles/abi.wgsl b/packages/render-native/src/cycles/abi.wgsl
new file mode 100644
index 00000000..76befe0e
--- /dev/null
+++ b/packages/render-native/src/cycles/abi.wgsl
@@ -0,0 +1,529 @@
+enable wgpu_ray_query;
+
+// Cycles-parity native kernel ABI header (`FORMAT-v2.md`).
+// Included first by `src/cycles/kernel-manifest.txt`. Later WGSL modules must not repeat `enable` directives.
+// Contains constants, buffer record structs, shading/closure structs, `@group(0)` bindings, and comment-documented
+// cross-lane function signatures (no `{ ... }` stub bodies).
+
+const PI: f32 = 3.141592653589793;
+const TWO_PI: f32 = 6.283185307179586;
+const INV_PI: f32 = 0.3183098861837907;
+const INV_TWO_PI: f32 = 0.15915494309189535;
+const INVALID_INDEX: u32 = 0xFFFFFFFFu;
+
+const FORMAT_V2_MAGIC: u32 = 0x36375054u;
+const FORMAT_V2_VERSION: u32 = 2u;
+
+// `@group(0)` binding indices matching `FORMAT-v2.md`.
+const BINDING_KERNEL_PARAMS: u32 = 0u;
+const BINDING_SCENE_TLAS: u32 = 1u;
+const BINDING_INSTANCES: u32 = 2u;
+const BINDING_TRIANGLES: u32 = 3u;
+const BINDING_MATERIALS: u32 = 4u;
+const BINDING_EMISSIVE_TRIANGLES: u32 = 5u;
+const BINDING_LIGHTS: u32 = 6u;
+const BINDING_LIGHT_TREE_NODES: u32 = 7u;
+const BINDING_TEXTURE_DESCRIPTORS: u32 = 8u;
+const BINDING_TEXTURE_TEXELS: u32 = 9u;
+const BINDING_ENVIRONMENT_TEXELS: u32 = 10u;
+const BINDING_FILM_ACCUMULATION: u32 = 11u;
+
+// `KernelParamsV2.kernel_flags` bits.
+const KERNEL_FLAG_USE_LIGHT_TREE: u32 = 1u;
+const KERNEL_FLAG_HAS_VOLUME: u32 = 2u;
+const KERNEL_FLAG_HAS_SUBSURFACE: u32 = 4u;
+const KERNEL_FLAG_ORTHOGRAPHIC_CAMERA: u32 = 8u;
+const KERNEL_FLAG_ADAPTIVE_SAMPLING: u32 = 16u;
+const KERNEL_FLAG_TRANSPARENT_BACKGROUND: u32 = 32u;
+
+// `KernelParamsV2.filter_type` values.
+const FILTER_BOX: u32 = 0u;
+const FILTER_GAUSSIAN: u32 = 1u;
+const FILTER_BLACKMAN_HARRIS: u32 = 2u;
+
+// `InstanceRecord.visibility_flags` bits.
+const INSTANCE_VISIBILITY_CAMERA: u32 = 1u;
+const INSTANCE_VISIBILITY_DIFFUSE: u32 = 2u;
+const INSTANCE_VISIBILITY_GLOSSY: u32 = 4u;
+const INSTANCE_VISIBILITY_TRANSMISSION: u32 = 8u;
+const INSTANCE_VISIBILITY_SHADOW: u32 = 16u;
+const INSTANCE_VISIBILITY_VOLUME_SCATTER: u32 = 32u;
+const INSTANCE_FLAG_NEGATIVE_SCALE: u32 = 64u;
+
+// `TriangleRecord.flags` bits.
+const TRIANGLE_FLAG_SMOOTH_NORMALS: u32 = 1u;
+const TRIANGLE_FLAG_HAS_VERTEX_COLORS: u32 = 2u;
+const TRIANGLE_FLAG_HAS_UV1: u32 = 4u;
+const TRIANGLE_FLAG_HAS_TANGENTS: u32 = 8u;
+const TRIANGLE_FLAG_DOUBLE_SIDED: u32 = 16u;
+
+// `LightRecord.light_type` values.
+const LIGHT_TYPE_POINT: u32 = 0u;
+const LIGHT_TYPE_SPOT: u32 = 1u;
+const LIGHT_TYPE_AREA_RECT: u32 = 2u;
+const LIGHT_TYPE_AREA_DISK: u32 = 3u;
+const LIGHT_TYPE_SUN: u32 = 4u;
+
+// `LightRecord.flags` bits.
+const LIGHT_FLAG_CAST_SHADOW: u32 = 1u;
+const LIGHT_FLAG_MULTIPLE_IMPORTANCE: u32 = 2u;
+const LIGHT_FLAG_CAMERA_VISIBLE: u32 = 4u;
+const LIGHT_FLAG_PORTAL: u32 = 8u;
+const LIGHT_FLAG_NORMALIZE: u32 = 16u;
+
+// `MaterialRecord.flags` bits.
+const MATERIAL_FLAG_MULTISCATTER_GGX: u32 = 1u;
+const MATERIAL_FLAG_THIN_WALLED: u32 = 2u;
+const MATERIAL_FLAG_TRANSPARENT_SHADOW: u32 = 4u;
+const MATERIAL_FLAG_DOUBLE_SIDED: u32 = 8u;
+const MATERIAL_FLAG_EMISSIVE_MIS: u32 = 16u;
+const MATERIAL_FLAG_F82_METALLIC: u32 = 32u;
+const MATERIAL_FLAG_HAS_SHADER_GRAPH: u32 = 64u;
+
+// `MaterialRecord.alpha_mode` values.
+const ALPHA_MODE_OPAQUE: u32 = 0u;
+const ALPHA_MODE_MASK: u32 = 1u;
+const ALPHA_MODE_BLEND: u32 = 2u;
+
+// Closure lobe capacity and `Lobe.lobe_type` discriminants.
+const MAX_CLOSURE_LOBES: u32 = 4u;
+const LOBE_NONE: u32 = 0u;
+const LOBE_DIFFUSE: u32 = 1u;
+const LOBE_GLOSSY_GGX: u32 = 2u;
+const LOBE_GLASS_GGX: u32 = 3u;
+const LOBE_COAT_GGX: u32 = 4u;
+const LOBE_SHEEN: u32 = 5u;
+const LOBE_TRANSPARENT: u32 = 6u;
+
+// `Lobe.flags` bits.
+const LOBE_FLAG_MULTISCATTER: u32 = 1u;
+const LOBE_FLAG_F82_TINT: u32 = 2u;
+const LOBE_FLAG_THIN_FILM: u32 = 4u;
+const LOBE_FLAG_THIN_WALLED: u32 = 8u;
+
+// 320 bytes (20 x 16 B), alignment 16 B.
+struct KernelParamsV2 {
+ magic: u32,
+ format_version: u32,
+ image_width: u32,
+ image_height: u32,
+
+ sample_offset: u32,
+ samples_per_dispatch: u32,
+ total_samples: u32,
+ seed: u32,
+
+ kernel_flags: u32,
+ adaptive_threshold: f32,
+ clamp_direct: f32,
+ clamp_indirect: f32,
+
+ max_bounces: u32,
+ max_diffuse_bounces: u32,
+ max_glossy_bounces: u32,
+ max_transmission_bounces: u32,
+
+ max_volume_bounces: u32,
+ max_transparent_bounces: u32,
+ min_bounce_rr: u32,
+ filter_type: u32,
+
+ filter_width: f32,
+ instance_count: u32,
+ triangle_count: u32,
+ material_count: u32,
+
+ emissive_triangle_count: u32,
+ light_count: u32,
+ light_tree_node_count: u32,
+ texture_count: u32,
+
+ camera_position: vec3<f32>,
+ camera_near: f32,
+
+ camera_forward: vec3<f32>,
+ camera_far: f32,
+
+ camera_right: vec3<f32>,
+ aperture_radius: f32,
+
+ camera_up: vec3<f32>,
+ focal_distance: f32,
+
+ lens_shift: vec2<f32>,
+ aperture_blades: u32,
+ aperture_rotation: f32,
+
+ env_width: u32,
+ env_height: u32,
+ env_cdf_offset: u32,
+ env_rotation: f32,
+
+ env_color: vec3<f32>,
+ env_total_weight: f32,
+
+ volume_bounds_min: vec3<f32>,
+ volume_density: f32,
+
+ volume_bounds_max: vec3<f32>,
+ volume_anisotropy: f32,
+
+ volume_albedo: vec3<f32>,
+ emissive_total_weight: f32,
+
+ analytic_light_total_weight: f32,
+ ray_epsilon: f32,
+ adaptive_min_samples: u32,
+ ies_table_offset: u32,
+
+ film_exposure: f32,
+ background_mis_weight: f32,
+ sobol_table_offset: u32,
+ reserved_u0: u32,
+
+ reserved_tail: vec4<u32>,
+}
+
+// 160 bytes (10 x 16 B), alignment 16 B.
+struct InstanceRecord {
+ object_to_world_row0: vec4<f32>,
+ object_to_world_row1: vec4<f32>,
+ object_to_world_row2: vec4<f32>,
+
+ world_to_object_row0: vec4<f32>,
+ world_to_object_row1: vec4<f32>,
+ world_to_object_row2: vec4<f32>,
+
+ blas_index: u32,
+ triangle_offset: u32,
+ opaque_triangle_count: u32,
+ total_triangle_count: u32,
+
+ material_override: u32,
+ visibility_flags: u32,
+ light_group_mask_lo: u32,
+ light_group_mask_hi: u32,
+
+ emissive_base_offset: u32,
+ object_id: u32,
+ object_random: f32,
+ shadow_terminator_offset: f32,
+
+ object_color: vec4<f32>,
+}
+
+// 224 bytes (14 x 16 B), alignment 16 B.
+struct TriangleRecord {
+ p0: vec3<f32>,
+ material_index: u32,
+
+ edge1: vec3<f32>,
+ local_emissive_offset: u32,
+
+ edge2: vec3<f32>,
+ flags: u32,
+
+ n0: vec3<f32>,
+ uv0_u: f32,
+
+ n1: vec3<f32>,
+ uv0_v: f32,
+
+ n2: vec3<f32>,
+ uv1_u: f32,
+
+ tangent0: vec3<f32>,
+ uv1_v: f32,
+
+ tangent1: vec3<f32>,
+ uv2_u: f32,
+
+ tangent2: vec3<f32>,
+ uv2_v: f32,
+
+ color0: vec3<f32>,
+ tangent_sign: f32,
+
+ color1: vec3<f32>,
+ mesh_id: u32,
+
+ color2: vec3<f32>,
+ primitive_id: u32,
+
+ uv_set1_0: vec2<f32>,
+ uv_set1_1: vec2<f32>,
+
+ uv_set1_2: vec2<f32>,
+ attribute_offset: u32,
+ reserved_u0: u32,
+}
+
+// 96 bytes (6 x 16 B), alignment 16 B.
+struct EmissiveTriangleRecord {
+ p0: vec3<f32>,
+ area: f32,
+
+ edge1: vec3<f32>,
+ instance_index: u32,
+
+ edge2: vec3<f32>,
+ triangle_index: u32,
+
+ geometric_normal: vec3<f32>,
+ material_index: u32,
+
+ radiance: vec3<f32>,
+ selection_weight: f32,
+
+ selection_pdf: f32,
+ cdf_upper: f32,
+ light_group_mask_lo: u32,
+ light_group_mask_hi: u32,
+}
+
+// 128 bytes (8 x 16 B), alignment 16 B.
+struct LightRecord {
+ position: vec3<f32>,
+ light_type: u32,
+
+ radiance: vec3<f32>,
+ flags: u32,
+
+ direction: vec3<f32>,
+ radius: f32,
+
+ axis_u: vec3<f32>,
+ size_u: f32,
+
+ axis_v: vec3<f32>,
+ size_v: f32,
+
+ cos_half_angle: f32,
+ spot_blend: f32,
+ tan_half_spread: f32,
+ spread_normalization: f32,
+
+ area_or_solid_angle: f32,
+ max_distance: f32,
+ ies_profile_index: i32,
+ tree_leaf_index: u32,
+
+ selection_pdf: f32,
+ cdf_upper: f32,
+ light_group_mask_lo: u32,
+ light_group_mask_hi: u32,
+}
+
+// 64 bytes (4 x 16 B), alignment 16 B.
+struct LightTreeNode {
+ bounds_min: vec3<f32>,
+ energy: f32,
+
+ bounds_max: vec3<f32>,
+ theta_o: f32,
+
+ cone_axis: vec3<f32>,
+ theta_e: f32,
+
+ left_child: i32,
+ right_or_first_emitter: u32,
+ emitter_count_and_kind: u32,
+ light_group_mask_or: u32,
+}
+
+// 32 bytes (2 x 16 B), alignment 16 B.
+struct TextureDescriptor {
+ @align(16) data_offset: u32,
+ width: u32,
+ height: u32,
+ format_and_sampler: u32,
+
+ uv_scale: vec2<f32>,
+ uv_offset: vec2<f32>,
+}
+
+// 256 bytes (16 x 16 B), alignment 16 B.
+struct MaterialRecord {
+ base_color: vec3<f32>,
+ metallic: f32,
+
+ roughness: f32,
+ ior: f32,
+ specular_ior_level: f32,
+ diffuse_roughness: f32,
+
+ f82_tint: vec3<f32>,
+ anisotropy: f32,
+
+ anisotropy_rotation: f32,
+ transmission_weight: f32,
+ alpha: f32,
+ alpha_cutoff: f32,
+
+ coat_tint: vec3<f32>,
+ coat_weight: f32,
+
+ coat_roughness: f32,
+ coat_ior: f32,
+ thin_film_thickness: f32,
+ thin_film_ior: f32,
+
+ sheen_tint: vec3<f32>,
+ sheen_weight: f32,
+
+ absorption_color: vec3<f32>,
+ absorption_distance: f32,
+
+ emission_color: vec3<f32>,
+ emission_strength: f32,
+
+ subsurface_radius: vec3<f32>,
+ subsurface_weight: f32,
+
+ subsurface_color: vec3<f32>,
+ subsurface_anisotropy: f32,
+
+ sheen_roughness: f32,
+ subsurface_ior: f32,
+ normal_scale: f32,
+ coat_normal_scale: f32,
+
+ flags: u32,
+ alpha_mode: u32,
+ bump_distance: f32,
+ svm_node_offset: u32,
+
+ base_color_tex: i32,
+ metallic_roughness_tex: i32,
+ normal_tex: i32,
+ emission_tex: i32,
+
+ transmission_tex: i32,
+ coat_weight_roughness_tex: i32,
+ coat_tint_tex: i32,
+ coat_normal_tex: i32,
+
+ sheen_color_roughness_tex: i32,
+ anisotropy_tex: i32,
+ alpha_tex: i32,
+ bump_tex: i32,
+}
+
+// Shader-side surface hit differential & frame passed from L3 integrator to L4 closure setup.
+struct ShadingPoint {
+ position: vec3<f32>,
+ ray_t: f32,
+
+ geometric_normal: vec3<f32>,
+ front_face: u32,
+
+ shading_normal: vec3<f32>,
+ material_index: u32,
+
+ coat_normal: vec3<f32>,
+ instance_index: u32,
+
+ tangent: vec3<f32>,
+ triangle_index: u32,
+
+ bitangent: vec3<f32>,
+ emissive_index: u32,
+
+ uv0: vec2<f32>,
+ uv1: vec2<f32>,
+
+ barycentrics: vec2<f32>,
+ object_random: f32,
+ light_group_mask_lo: u32,
+
+ vertex_color: vec3<f32>,
+ light_group_mask_hi: u32,
+}
+
+// Single BSDF lobe parameterized by L4 closure setup.
+struct Lobe {
+ weight: vec3<f32>,
+ sample_weight: f32,
+
+ normal: vec3<f32>,
+ lobe_type: u32,
+
+ tangent: vec3<f32>,
+ flags: u32,
+
+ f0: vec3<f32>,
+ ior: f32,
+
+ f82_or_tint: vec3<f32>,
+ diffuse_roughness: f32,
+
+ alpha_x: f32,
+ alpha_y: f32,
+ thin_film_thickness: f32,
+ thin_film_ior: f32,
+}
+
+// Stacked multi-lobe surface closure evaluated/sampled at `ShadingPoint`.
+struct Closure {
+ lobes: array<Lobe, 4>,
+
+ emission: vec3<f32>,
+ lobe_count: u32,
+
+ absorption_sigma: vec3<f32>,
+ total_sample_weight: f32,
+
+ geometric_normal: vec3<f32>,
+ front_face: u32,
+}
+
+// Return value of `closure_eval`: cosine-foreshortened BSDF value `f(wo, wi) * |dot(N, wi)|` and solid-angle mixture PDF.
+struct ClosureEval {
+ value: vec3<f32>,
+ pdf: f32,
+}
+
+// Return value of `closure_sample`: sampled direction `wi`, solid-angle mixture PDF, cosine-foreshortened `eval`, and lobe type.
+struct ClosureSample {
+ wi: vec3<f32>,
+ pdf: f32,
+ eval: vec3<f32>,
+ sampled_lobe_type: u32,
+}
+
+@group(0) @binding(0) var<uniform> kernel_params: KernelParamsV2;
+@group(0) @binding(1) var scene_tlas: acceleration_structure;
+@group(0) @binding(2) var<storage, read> instances: array<InstanceRecord>;
+@group(0) @binding(3) var<storage, read> triangles: array<TriangleRecord>;
+@group(0) @binding(4) var<storage, read> materials: array<MaterialRecord>;
+@group(0) @binding(5) var<storage, read> emissive_triangles: array<EmissiveTriangleRecord>;
+@group(0) @binding(6) var<storage, read> lights: array<LightRecord>;
+@group(0) @binding(7) var<storage, read> light_tree_nodes: array<LightTreeNode>;
+@group(0) @binding(8) var<storage, read> texture_descriptors: array<TextureDescriptor>;
+@group(0) @binding(9) var<storage, read> texture_texels: array<u32>;
+@group(0) @binding(10) var<storage, read> environment_texels: array<vec4<f32>>;
+@group(0) @binding(11) var<storage, read_write> film_accumulation: array<vec4<f32>>;
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Cross-lane closure interface contract (defined in Lane L4 `src/cycles/closure.wgsl`, called by Lane L3 integrator)
+//
+// No WGSL stub bodies appear in this header because WGSL forbids bodyless forward declarations and stub implementations
+// would collide with Lane L4's definitions when `kernel-manifest.txt` concatenates all modules.
+//
+// Direction and cosine conventions (matching Cycles `intern/cycles/kernel/closure/bsdf.h`):
+// - `wo`: unit vector in world space pointing from `ShadingPoint.position` toward the previous path vertex (`-ray_dir`).
+// - `wi`: unit vector in world space pointing from `ShadingPoint.position` toward the light source / next path vertex.
+// - `ClosureEval.value` and `ClosureSample.eval` ALREADY include the foreshortening cosine `|dot(N, wi)|`
+// (for example, unit-albedo Lambertian returns `value = vec3<f32>(max(dot(N, wi), 0.0) * INV_PI)` and
+// `pdf = max(dot(N, wi), 0.0) * INV_PI`, so the throughput multiplier on a sampled bounce is `sample.eval / sample.pdf`).
+// - `u`: three independent uniform `[0, 1)` random numbers: `u.x` selects the lobe from `closure.lobes[0..closure.lobe_count]`
+// proportional to `Lobe.sample_weight` (and rescales within the selected interval), while `(u.y, u.z)` sample the lobe.
+// - When `closure.lobe_count == 0u`, `closure.total_sample_weight <= 0.0`, or the sampled direction is absorbed / invalid,
+// `closure_sample` returns `pdf = 0.0` and `eval = vec3<f32>(0.0)`.
+//
+// Exact WGSL signatures to be defined by Lane L4 (`src/cycles/closure.wgsl`):
+//
+// fn closure_build(point: ShadingPoint, wo: vec3<f32>) -> Closure
+// fn closure_eval(closure: Closure, wi: vec3<f32>, wo: vec3<f32>) -> ClosureEval
+// fn closure_sample(closure: Closure, wo: vec3<f32>, u: vec3<f32>) -> ClosureSample
+// ---------------------------------------------------------------------------------------------------------------------
diff --git a/packages/render-native/src/cycles/kernel-manifest.txt b/packages/render-native/src/cycles/kernel-manifest.txt
new file mode 100644
index 00000000..f116716b
--- /dev/null
+++ b/packages/render-native/src/cycles/kernel-manifest.txt
@@ -0,0 +1,19 @@
+# Ordered WGSL module manifest for the Cycles-parity native kernel (`kernel: "cycles"`).
+# Blank lines and `#` comments are ignored; listed files are relative to `src/cycles/` and concatenated in order.
+#
+# Planned lane append order:
+# abi.wgsl
+# sampler.wgsl
+# camera.wgsl
+# filter.wgsl
+# closure.wgsl
+# bsdf_diffuse.wgsl
+# bsdf_microfacet.wgsl
+# bsdf_glass.wgsl
+# bsdf_sheen.wgsl
+# bsdf_coat.wgsl
+# lights.wgsl
+# light_tree.wgsl
+# integrator.wgsl
+
+abi.wgsl
diff --git a/packages/render-native/src/cycles/mod.rs b/packages/render-native/src/cycles/mod.rs
new file mode 100644
index 00000000..50e6348d
--- /dev/null
+++ b/packages/render-native/src/cycles/mod.rs
@@ -0,0 +1,107 @@
+use napi::Result;
+
+use crate::host::device::failure;
+
+const KERNEL_MANIFEST_SOURCE: &str = include_str!("kernel-manifest.txt");
+
+include!(concat!(env!("OUT_DIR"), "/cycles_manifest_files.rs"));
+
+/// Parses `kernel-manifest.txt`, ignoring blank lines and `#` comments, and returns relative WGSL paths in order.
+pub(crate) fn parse_kernel_manifest(manifest_text: &str) -> Vec<&str> {
+ let mut entries = Vec::new();
+ for raw_line in manifest_text.lines() {
+ let without_comment = raw_line.split('#').next().unwrap_or("");
+ let trimmed = without_comment.trim();
+ if !trimmed.is_empty() {
+ entries.push(trimmed);
+ }
+ }
+ entries
+}
+
+fn strip_wgsl_comments(source: &str) -> String {
+ let mut cleaned = String::with_capacity(source.len());
+ let bytes = source.as_bytes();
+ let mut index = 0;
+ let mut block_depth = 0usize;
+ while index < bytes.len() {
+ if block_depth > 0 {
+ if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'*' {
+ block_depth += 1;
+ index += 2;
+ continue;
+ }
+ if index + 1 < bytes.len() && bytes[index] == b'*' && bytes[index + 1] == b'/' {
+ block_depth -= 1;
+ index += 2;
+ cleaned.push(' ');
+ continue;
+ }
+ if bytes[index] == b'\n' {
+ cleaned.push('\n');
+ }
+ index += 1;
+ continue;
+ }
+ if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'/' {
+ index += 2;
+ while index < bytes.len() && bytes[index] != b'\n' {
+ index += 1;
+ }
+ continue;
+ }
+ if index + 1 < bytes.len() && bytes[index] == b'/' && bytes[index + 1] == b'*' {
+ block_depth = 1;
+ index += 2;
+ continue;
+ }
+ cleaned.push(bytes[index] as char);
+ index += 1;
+ }
+ cleaned
+}
+
+fn has_compute_main_entry_point(shader_source: &str) -> bool {
+ let uncommented = strip_wgsl_comments(shader_source);
+ let mut saw_compute_attribute = false;
+ for token in uncommented.split_whitespace() {
+ if token.contains("@compute") {
+ saw_compute_attribute = true;
+ }
+ if saw_compute_attribute && (token == "main" || token.starts_with("main(")) {
+ return true;
+ }
+ }
+ false
+}
+
+/// Concatenates the WGSL modules listed in `src/cycles/kernel-manifest.txt` in order and verifies a runnable `@compute`
+/// `main` entry point exists before opening a GPU pipeline.
+pub(crate) fn assemble_cycles_kernel() -> Result<String> {
+ let entries = parse_kernel_manifest(KERNEL_MANIFEST_SOURCE);
+ if entries.is_empty() {
+ return Err(failure(
+ "The Cycles native kernel cannot run: src/cycles/kernel-manifest.txt lists no WGSL files.",
+ ));
+ }
+ let mut assembled = String::new();
+ for entry in &entries {
+ let (_, raw_bytes) = CYCLES_MANIFEST_FILES
+ .iter()
+ .find(|(name, _)| name == entry)
+ .ok_or_else(|| failure(format!("Cycles kernel manifest entry is not embedded: {entry}")))?;
+ let module_source = std::str::from_utf8(raw_bytes)
+ .map_err(|error| failure(format!("Cycles kernel module {entry} is not valid UTF-8: {error}")))?;
+ if !assembled.is_empty() && !assembled.ends_with('\n') {
+ assembled.push('\n');
+ }
+ assembled.push_str(module_source);
+ }
+ if !has_compute_main_entry_point(&assembled) {
+ return Err(failure(format!(
+ "The Cycles native kernel cannot run yet: src/cycles/kernel-manifest.txt defines no @compute main entry point (assembled modules: {}).",
+ entries.join(", ")
+ )));
+ }
+ Ok(assembled)
+}
diff --git a/packages/render-native/src/host/accel.rs b/packages/render-native/src/host/accel.rs
new file mode 100644
index 00000000..55308571
--- /dev/null
+++ b/packages/render-native/src/host/accel.rs
@@ -0,0 +1,131 @@
+use wgpu::util::DeviceExt;
+
+use crate::host::textures::material_is_cutout;
+
+pub(crate) const TRIANGLE_FLOATS: usize = 9 * 4;
+const VERTEX_STRIDE_BYTES: u64 = 12;
+
+pub(crate) struct UnpackedTriangles {
+ pub(crate) vertices: Vec<f32>,
+ pub(crate) slot_map: Vec<u32>,
+ pub(crate) opaque_count: usize,
+}
+
+/// Unpacks corner-plus-two-edges triangle rows into three 3D corners per triangle, placing opaque triangles before
+/// alpha-cutout triangles so each hardware BLAS geometry has a uniform opacity flag.
+pub(crate) fn unpack_triangles(triangle_data: &[f32], materials: &[f32], triangle_count: usize) -> UnpackedTriangles {
+ let mut opaque_vertices: Vec<f32> = Vec::with_capacity(triangle_count * 9);
+ let mut cutout_vertices: Vec<f32> = Vec::new();
+ let mut slot_map: Vec<u32> = Vec::with_capacity(triangle_count);
+ let mut cutout_slots: Vec<u32> = Vec::new();
+ for (slot, triangle) in triangle_data.chunks_exact(TRIANGLE_FLOATS).enumerate() {
+ let corner = [triangle[0], triangle[1], triangle[2]];
+ let edge_first = [triangle[4], triangle[5], triangle[6]];
+ let edge_second = [triangle[8], triangle[9], triangle[10]];
+ let is_cutout = material_is_cutout(materials, triangle[3] as usize);
+ let vertices = if is_cutout { &mut cutout_vertices } else { &mut opaque_vertices };
+ vertices.extend_from_slice(&corner);
+ vertices.extend((0..3).map(|axis| corner[axis] + edge_first[axis]));
+ vertices.extend((0..3).map(|axis| corner[axis] + edge_second[axis]));
+ if is_cutout {
+ cutout_slots.push(slot as u32);
+ } else {
+ slot_map.push(slot as u32);
+ }
+ }
+ let opaque_count = slot_map.len();
+ slot_map.extend(cutout_slots);
+ let mut vertices = opaque_vertices;
+ vertices.extend(cutout_vertices);
+ UnpackedTriangles {
+ vertices,
+ slot_map,
+ opaque_count,
+ }
+}
+
+pub(crate) fn create_vertex_buffer(device: &wgpu::Device, vertices: &[f32]) -> wgpu::Buffer {
+ device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
+ label: Some("triangle corners"),
+ contents: bytemuck::cast_slice(vertices),
+ usage: wgpu::BufferUsages::BLAS_INPUT,
+ })
+}
+
+/// Builds the scene BLAS (split into opaque and candidate cutout geometries) and single-instance TLAS.
+pub(crate) fn build_acceleration_structure(
+ device: &wgpu::Device,
+ queue: &wgpu::Queue,
+ vertex_buffer: &wgpu::Buffer,
+ triangle_count: usize,
+ opaque_count: usize,
+) -> wgpu::Tlas {
+ let mut geometry_sizes: Vec<wgpu::BlasTriangleGeometrySizeDescriptor> = Vec::new();
+ let mut geometry_vertex_starts: Vec<u32> = Vec::new();
+ let cutout_count = triangle_count - opaque_count;
+ for (first_triangle, triangles_in_geometry, flags) in [
+ (0, opaque_count, wgpu::AccelerationStructureGeometryFlags::OPAQUE),
+ (opaque_count, cutout_count, wgpu::AccelerationStructureGeometryFlags::empty()),
+ ] {
+ if triangles_in_geometry == 0 {
+ continue;
+ }
+ geometry_vertex_starts.push((first_triangle * 3) as u32);
+ geometry_sizes.push(wgpu::BlasTriangleGeometrySizeDescriptor {
+ vertex_format: wgpu::VertexFormat::Float32x3,
+ vertex_count: (triangles_in_geometry * 3) as u32,
+ index_format: None,
+ index_count: None,
+ flags,
+ });
+ }
+ let blas = device.create_blas(
+ &wgpu::CreateBlasDescriptor {
+ label: Some("scene"),
+ flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
+ update_mode: wgpu::AccelerationStructureUpdateMode::Build,
+ },
+ wgpu::BlasGeometrySizeDescriptors::Triangles {
+ descriptors: geometry_sizes.clone(),
+ },
+ );
+ let mut tlas = device.create_tlas(&wgpu::CreateTlasDescriptor {
+ label: Some("scene"),
+ flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
+ update_mode: wgpu::AccelerationStructureUpdateMode::Build,
+ max_instances: 1,
+ });
+ tlas[0] = Some(wgpu::TlasInstance::new(
+ &blas,
+ [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
+ 0,
+ 0xFF,
+ ));
+ let triangle_geometries: Vec<wgpu::BlasTriangleGeometry> = geometry_sizes
+ .iter()
+ .zip(&geometry_vertex_starts)
+ .map(|(size, first_vertex)| wgpu::BlasTriangleGeometry {
+ size,
+ vertex_buffer,
+ first_vertex: *first_vertex,
+ vertex_stride: VERTEX_STRIDE_BYTES,
+ index_buffer: None,
+ first_index: None,
+ transform_buffer: None,
+ transform_buffer_offset: None,
+ })
+ .collect();
+ let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
+ label: Some("build"),
+ });
+ build_encoder.build_acceleration_structures(
+ std::iter::once(&wgpu::BlasBuildEntry {
+ blas: &blas,
+ geometry: wgpu::BlasGeometries::TriangleGeometries(triangle_geometries),
+ }),
+ std::iter::once(&tlas),
+ );
+ queue.submit(Some(build_encoder.finish()));
+ let _ = device.poll(wgpu::PollType::wait_indefinitely());
+ tlas
+}
diff --git a/packages/render-native/src/host/device.rs b/packages/render-native/src/host/device.rs
new file mode 100644
index 00000000..6b881ccc
--- /dev/null
+++ b/packages/render-native/src/host/device.rs
@@ -0,0 +1,70 @@
+use napi::{Error, Result};
+use wgpu::util::DeviceExt;
+
+pub(crate) fn failure(message: impl Into<String>) -> Error {
+ Error::from_reason(message.into())
+}
+
+pub(crate) fn storage_buffer(device: &wgpu::Device, label: &str, bytes: &[u8]) -> wgpu::Buffer {
+ let mut padded = bytes.to_vec();
+ let padded_length = padded.len().next_multiple_of(4).max(16);
+ padded.resize(padded_length, 0);
+ device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
+ label: Some(label),
+ contents: &padded,
+ usage: wgpu::BufferUsages::STORAGE,
+ })
+}
+
+pub(crate) fn layout_entry(binding: u32, binding_type: wgpu::BindingType) -> wgpu::BindGroupLayoutEntry {
+ wgpu::BindGroupLayoutEntry {
+ binding,
+ visibility: wgpu::ShaderStages::COMPUTE,
+ ty: binding_type,
+ count: None,
+ }
+}
+
+pub(crate) fn storage_entry(binding: u32, read_only: bool) -> wgpu::BindGroupLayoutEntry {
+ layout_entry(
+ binding,
+ wgpu::BindingType::Buffer {
+ ty: wgpu::BufferBindingType::Storage { read_only },
+ has_dynamic_offset: false,
+ min_binding_size: None,
+ },
+ )
+}
+
+pub(crate) fn open_device() -> Result<(wgpu::Device, wgpu::Queue, wgpu::AdapterInfo)> {
+ let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
+ backends: wgpu::Backends::VULKAN,
+ ..wgpu::InstanceDescriptor::new_without_display_handle()
+ });
+ let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
+ power_preference: wgpu::PowerPreference::HighPerformance,
+ ..Default::default()
+ }))
+ .map_err(|error| failure(format!("No Vulkan adapter: {error}")))?;
+ if !adapter.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY) {
+ return Err(failure("The Vulkan adapter does not support ray queries."));
+ }
+ let adapter_limits = adapter.limits();
+ let required_limits = wgpu::Limits {
+ max_storage_buffer_binding_size: adapter_limits.max_storage_buffer_binding_size.min(1 << 30),
+ max_buffer_size: adapter_limits.max_buffer_size.min(1 << 30),
+ // The light bake binds nine storage buffers (the scene, the accumulation and the texels); the default allows eight.
+ max_storage_buffers_per_shader_stage: adapter_limits.max_storage_buffers_per_shader_stage.min(16),
+ ..wgpu::Limits::default()
+ }
+ .using_minimum_supported_acceleration_structure_values();
+ let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
+ label: Some("render-native"),
+ required_features: wgpu::Features::EXPERIMENTAL_RAY_QUERY,
+ required_limits,
+ experimental_features: unsafe { wgpu::ExperimentalFeatures::enabled() },
+ ..Default::default()
+ }))
+ .map_err(|error| failure(format!("Could not open the device: {error}")))?;
+ Ok((device, queue, adapter.get_info()))
+}
diff --git a/packages/render-native/src/host/film.rs b/packages/render-native/src/host/film.rs
new file mode 100644
index 00000000..6fee2763
--- /dev/null
+++ b/packages/render-native/src/host/film.rs
@@ -0,0 +1,137 @@
+use napi::Result;
+
+use crate::host::device::failure;
+
+const WORKGROUP_SIZE: u32 = 8;
+/// Must match `TEXEL_WORKGROUP_SIZE` in texel.wgsl.
+const TEXEL_WORKGROUP_SIZE: u32 = 64;
+/// A dispatch is at most 65535 workgroups wide; a larger bake wraps onto the second dimension.
+const MAXIMUM_TEXEL_GROUPS_X: u32 = 4096;
+
+pub(crate) struct ResolvedImage {
+ pub(crate) rgba: Vec<f32>,
+ pub(crate) albedo: Vec<f32>,
+ pub(crate) normal: Vec<f32>,
+ pub(crate) depth: Vec<f32>,
+ pub(crate) variance: Vec<f32>,
+ pub(crate) average_samples: f64,
+}
+
+pub(crate) struct ResolvedTexels {
+ pub(crate) radiance: Vec<f32>,
+ pub(crate) escaped: Vec<f32>,
+}
+
+pub(crate) fn image_accumulation_bytes(width: u32, height: u32) -> u64 {
+ let pixel_count = width as u64 * height as u64;
+ pixel_count * 4 * 16
+}
+
+pub(crate) fn image_workgroups(width: u32, height: u32) -> (u32, u32) {
+ let groups_x = width.div_ceil(WORKGROUP_SIZE);
+ let groups_y = height.div_ceil(WORKGROUP_SIZE);
+ (groups_x, groups_y)
+}
+
+pub(crate) fn texel_accumulation_bytes(count: usize) -> u64 {
+ count as u64 * 2 * 16
+}
+
+pub(crate) fn texel_workgroups(count: u32) -> (u32, u32) {
+ let workgroups = count.div_ceil(TEXEL_WORKGROUP_SIZE);
+ let groups_x = workgroups.min(MAXIMUM_TEXEL_GROUPS_X);
+ let groups_y = workgroups.div_ceil(groups_x);
+ (groups_x, groups_y)
+}
+
+pub(crate) fn read_accumulation(
+ device: &wgpu::Device,
+ queue: &wgpu::Queue,
+ accumulation: &wgpu::Buffer,
+ accumulation_bytes: u64,
+) -> Result<Vec<f32>> {
+ let readback = device.create_buffer(&wgpu::BufferDescriptor {
+ label: Some("readback"),
+ size: accumulation_bytes,
+ usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
+ mapped_at_creation: false,
+ });
+ let mut copy_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
+ label: Some("readback"),
+ });
+ copy_encoder.copy_buffer_to_buffer(accumulation, 0, &readback, 0, accumulation_bytes);
+ queue.submit(Some(copy_encoder.finish()));
+ readback.slice(..).map_async(wgpu::MapMode::Read, |_| {});
+ let _ = device.poll(wgpu::PollType::wait_indefinitely());
+ let mapped = readback
+ .slice(..)
+ .get_mapped_range()
+ .map_err(|error| failure(format!("Could not read the result back: {error}")))?;
+ let sums: Vec<f32> = bytemuck::cast_slice::<u8, f32>(&mapped).to_vec();
+ drop(mapped);
+ Ok(sums)
+}
+
+pub(crate) fn resolve_image(sums: &[f32], pixel_count: u64) -> ResolvedImage {
+ let pixel_total = pixel_count as usize;
+ let plane_length = pixel_total * 4;
+ let mut taken_total = 0.0f64;
+ let mut rgba = Vec::with_capacity(pixel_total * 4);
+ let mut albedo = Vec::with_capacity(pixel_total * 3);
+ let mut normal = Vec::with_capacity(pixel_total * 3);
+ let mut depth = Vec::with_capacity(pixel_total);
+ let mut variance = Vec::with_capacity(pixel_total);
+ for pixel in 0..pixel_total {
+ let radiance = &sums[pixel * 4..pixel * 4 + 4];
+ let albedo_sum = &sums[plane_length + pixel * 4..plane_length + pixel * 4 + 3];
+ let normal_sum = &sums[2 * plane_length + pixel * 4..2 * plane_length + pixel * 4 + 3];
+ let statistics = &sums[3 * plane_length + pixel * 4..3 * plane_length + pixel * 4 + 4];
+ // A pixel that converged early drew fewer samples; its sums are divided by its own count.
+ let taken = statistics[3].max(1.0);
+ taken_total += taken as f64;
+ let sample_scale = 1.0 / taken;
+ let variance_divisor = (taken - 1.0).max(1.0);
+ rgba.extend_from_slice(&[
+ radiance[0] * sample_scale,
+ radiance[1] * sample_scale,
+ radiance[2] * sample_scale,
+ 1.0,
+ ]);
+ depth.push(radiance[3] * sample_scale);
+ albedo.extend(albedo_sum.iter().map(|value| value * sample_scale));
+ normal.extend(normal_sum.iter().map(|value| value * sample_scale));
+ let mean_luminance = statistics[0] * sample_scale;
+ let luminance_variance = (statistics[1] * sample_scale - mean_luminance * mean_luminance).max(0.0);
+ variance.push(luminance_variance / variance_divisor);
+ }
+ let average_samples = taken_total / pixel_count.max(1) as f64;
+ ResolvedImage {
+ rgba,
+ albedo,
+ normal,
+ depth,
+ variance,
+ average_samples,
+ }
+}
+
+/// Three floats per texel, padded to the four the kernel's vec4 arrays read.
+pub(crate) fn pad_texel_vectors(vectors: &[f32], count: usize) -> Vec<u8> {
+ let mut padded: Vec<f32> = Vec::with_capacity(count * 4);
+ for texel in 0..count {
+ padded.extend_from_slice(&vectors[texel * 3..texel * 3 + 3]);
+ padded.push(0.0);
+ }
+ bytemuck::cast_slice(&padded).to_vec()
+}
+
+pub(crate) fn resolve_texels(sums: &[f32], count: usize, samples: u32) -> ResolvedTexels {
+ let sample_scale = 1.0 / samples.max(1) as f32;
+ let mut radiance = Vec::with_capacity(count * 3);
+ let mut escaped = Vec::with_capacity(count);
+ for texel in 0..count {
+ radiance.extend(sums[texel * 4..texel * 4 + 3].iter().map(|value| value * sample_scale));
+ escaped.push(sums[(count + texel) * 4] * sample_scale);
+ }
+ ResolvedTexels { radiance, escaped }
+}
diff --git a/packages/render-native/src/host/mod.rs b/packages/render-native/src/host/mod.rs
new file mode 100644
index 00000000..95fb9769
--- /dev/null
+++ b/packages/render-native/src/host/mod.rs
@@ -0,0 +1,5 @@
+pub(crate) mod accel;
+pub(crate) mod device;
+pub(crate) mod film;
+pub(crate) mod session;
+pub(crate) mod textures;
diff --git a/packages/render-native/src/host/session.rs b/packages/render-native/src/host/session.rs
new file mode 100644
index 00000000..2374c87d
--- /dev/null
+++ b/packages/render-native/src/host/session.rs
@@ -0,0 +1,261 @@
+use std::time::Instant;
+
+use napi::Result;
+
+use crate::host::accel::{
+ build_acceleration_structure, create_vertex_buffer, unpack_triangles, TRIANGLE_FLOATS,
+};
+use crate::host::device::{failure, layout_entry, open_device, storage_entry};
+use crate::host::film::read_accumulation;
+use crate::host::textures::upload_scene_buffers;
+use crate::NativeTraceInput;
+
+const PARAMETER_BYTES: usize = 16 * 16;
+const VOLUME_DENSITY_BYTE_OFFSET: usize = 51 * 4;
+const SUBSURFACE_OFFSET_BYTE_OFFSET: usize = 60 * 4;
+const SAMPLE_INDEX_BYTE_OFFSET: u64 = 43 * 4;
+const SAMPLES_PER_WAIT: u32 = 4;
+
+/// A device with the scene's acceleration structure built and one compute pipeline bound to it.
+pub(crate) struct PreparedScene {
+ pub(crate) device: wgpu::Device,
+ pub(crate) queue: wgpu::Queue,
+ pub(crate) pipeline: wgpu::ComputePipeline,
+ pub(crate) bind_group: wgpu::BindGroup,
+ pub(crate) accumulation: wgpu::Buffer,
+ pub(crate) parameters: wgpu::Buffer,
+ pub(crate) adapter_name: String,
+ pub(crate) backend_name: String,
+ pub(crate) features: String,
+ pub(crate) setup_seconds: f64,
+ pub(crate) compile_seconds: f64,
+ pub(crate) upload_seconds: f64,
+ pub(crate) acceleration_build_seconds: f64,
+ // The bind group keeps the buffers and the structure alive; holding them here makes that visible.
+ pub(crate) _buffers: Vec<wgpu::Buffer>,
+ pub(crate) _tlas: wgpu::Tlas,
+}
+
+/// What one kind of job adds to the shared scene setup: the kernel text, its entry point, the accumulation size and the
+/// extra read only buffers bound after the accumulation (bindings 9 and up).
+pub(crate) struct JobShape<'a> {
+ pub(crate) source: String,
+ pub(crate) entry_point: &'a str,
+ pub(crate) rewrite_specialization_flags: bool,
+ pub(crate) accumulation_bytes: u64,
+ pub(crate) extra_buffers: Vec<(&'a str, Vec<u8>)>,
+}
+
+fn specialize_legacy_kernel(source: &str, parameter_bytes: &[u8]) -> String {
+ // Fog and subsurface scattering compile in only for a scene that uses them: the legacy kernel declares both as false constants.
+ let fog_density_bytes: [u8; 4] = parameter_bytes[VOLUME_DENSITY_BYTE_OFFSET..VOLUME_DENSITY_BYTE_OFFSET + 4]
+ .try_into()
+ .unwrap();
+ let subsurface_offset_bytes: [u8; 4] = parameter_bytes[SUBSURFACE_OFFSET_BYTE_OFFSET..SUBSURFACE_OFFSET_BYTE_OFFSET + 4]
+ .try_into()
+ .unwrap();
+ let fog_density = f32::from_le_bytes(fog_density_bytes);
+ let subsurface_offset = u32::from_le_bytes(subsurface_offset_bytes);
+ source
+ .replace("const HAS_VOLUME: bool = false;", &format!("const HAS_VOLUME: bool = {};", fog_density > 0.0))
+ .replace("const HAS_SUBSURFACE: bool = false;", &format!("const HAS_SUBSURFACE: bool = {};", subsurface_offset > 0))
+}
+
+fn create_bind_group_layout(device: &wgpu::Device, extra_buffer_count: usize) -> wgpu::BindGroupLayout {
+ let mut layout_entries = vec![
+ layout_entry(
+ 0,
+ wgpu::BindingType::Buffer {
+ ty: wgpu::BufferBindingType::Uniform,
+ has_dynamic_offset: false,
+ min_binding_size: None,
+ },
+ ),
+ layout_entry(1, wgpu::BindingType::AccelerationStructure { vertex_return: false }),
+ ];
+ layout_entries.extend((2..=7).map(|binding| storage_entry(binding, true)));
+ layout_entries.push(storage_entry(8, false));
+ layout_entries.extend((0..extra_buffer_count + 1).map(|offset| storage_entry(9 + offset as u32, true)));
+ device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+ label: Some("path tracer"),
+ entries: &layout_entries,
+ })
+}
+
+fn compile_compute_pipeline(
+ device: &wgpu::Device,
+ shader_source: String,
+ entry_point: &str,
+ bind_group_layout: &wgpu::BindGroupLayout,
+) -> Result<wgpu::ComputePipeline> {
+ let error_scope = device.push_error_scope(wgpu::ErrorFilter::Validation);
+ let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+ label: Some("path tracer"),
+ source: wgpu::ShaderSource::Wgsl(shader_source.into()),
+ });
+ let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+ label: Some("path tracer"),
+ bind_group_layouts: &[Some(bind_group_layout)],
+ immediate_size: 0,
+ });
+ let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
+ label: Some("path tracer"),
+ layout: Some(&pipeline_layout),
+ module: &module,
+ entry_point: Some(entry_point),
+ compilation_options: Default::default(),
+ cache: None,
+ });
+ if let Some(validation_error) = pollster::block_on(error_scope.pop()) {
+ return Err(failure(format!("Could not compile the native kernel: {validation_error}")));
+ }
+ Ok(pipeline)
+}
+
+fn create_scene_bind_group(
+ device: &wgpu::Device,
+ bind_group_layout: &wgpu::BindGroupLayout,
+ parameters: &wgpu::Buffer,
+ tlas: &wgpu::Tlas,
+ buffers: &[wgpu::Buffer],
+ accumulation: &wgpu::Buffer,
+) -> wgpu::BindGroup {
+ let mut entries = vec![
+ wgpu::BindGroupEntry { binding: 0, resource: parameters.as_entire_binding() },
+ wgpu::BindGroupEntry { binding: 1, resource: tlas.as_binding() },
+ ];
+ for (offset, buffer) in buffers[..6].iter().enumerate() {
+ entries.push(wgpu::BindGroupEntry {
+ binding: 2 + offset as u32,
+ resource: buffer.as_entire_binding(),
+ });
+ }
+ entries.push(wgpu::BindGroupEntry {
+ binding: 8,
+ resource: accumulation.as_entire_binding(),
+ });
+ for (offset, buffer) in buffers[6..].iter().enumerate() {
+ entries.push(wgpu::BindGroupEntry {
+ binding: 9 + offset as u32,
+ resource: buffer.as_entire_binding(),
+ });
+ }
+ device.create_bind_group(&wgpu::BindGroupDescriptor {
+ label: Some("path tracer"),
+ layout: bind_group_layout,
+ entries: &entries,
+ })
+}
+
+pub(crate) fn prepare_scene(input: &NativeTraceInput, shape: JobShape) -> Result<PreparedScene> {
+ let setup_started = Instant::now();
+ let triangle_count = input.triangle_count as usize;
+ if triangle_count == 0 || input.triangles.len() < triangle_count * TRIANGLE_FLOATS {
+ return Err(failure("The triangle table must hold triangle_count triangles of 9 texels."));
+ }
+ let triangle_data: &[f32] = &input.triangles[..triangle_count * TRIANGLE_FLOATS];
+ if input.parameters.len() != PARAMETER_BYTES {
+ return Err(failure("The parameter block must be 256 bytes."));
+ }
+ let (device, queue, adapter_info) = open_device()?;
+ let setup_seconds = setup_started.elapsed().as_secs_f64();
+
+ let compile_started = Instant::now();
+ let shader_source = if shape.rewrite_specialization_flags {
+ specialize_legacy_kernel(&shape.source, &input.parameters)
+ } else {
+ shape.source
+ };
+ let bind_group_layout = create_bind_group_layout(&device, shape.extra_buffers.len());
+ let pipeline = compile_compute_pipeline(&device, shader_source, shape.entry_point, &bind_group_layout)?;
+ let compile_seconds = compile_started.elapsed().as_secs_f64();
+
+ let upload_started = Instant::now();
+ let unpacked = unpack_triangles(triangle_data, &input.materials, triangle_count);
+ let vertex_buffer = create_vertex_buffer(&device, &unpacked.vertices);
+ let uploaded = upload_scene_buffers(
+ &device,
+ input,
+ triangle_data,
+ &unpacked.slot_map,
+ unpacked.opaque_count,
+ shape.accumulation_bytes,
+ &shape.extra_buffers,
+ );
+ let upload_seconds = upload_started.elapsed().as_secs_f64();
+
+ let build_started = Instant::now();
+ let tlas = build_acceleration_structure(&device, &queue, &vertex_buffer, triangle_count, unpacked.opaque_count);
+ let acceleration_build_seconds = build_started.elapsed().as_secs_f64();
+
+ let bind_group = create_scene_bind_group(
+ &device,
+ &bind_group_layout,
+ &uploaded.parameters,
+ &tlas,
+ &uploaded.buffers,
+ &uploaded.accumulation,
+ );
+ let has_ray_query = device.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY);
+ let features = if has_ray_query { "EXPERIMENTAL_RAY_QUERY" } else { "" };
+ Ok(PreparedScene {
+ device,
+ queue,
+ pipeline,
+ bind_group,
+ accumulation: uploaded.accumulation,
+ parameters: uploaded.parameters,
+ adapter_name: adapter_info.name,
+ backend_name: format!("{:?}", adapter_info.backend),
+ features: features.to_string(),
+ setup_seconds,
+ compile_seconds,
+ upload_seconds,
+ acceleration_build_seconds,
+ _buffers: uploaded.buffers,
+ _tlas: tlas,
+ })
+}
+
+/// Runs every sample over `groups` workgroups and copies the accumulation back. `max_seconds` bounds the run: past it the
+/// trace stops with an error instead of finishing, checked each time the CPU waits for the card.
+pub(crate) fn trace_samples(
+ prepared: &PreparedScene,
+ samples: u32,
+ groups: (u32, u32),
+ accumulation_bytes: u64,
+ max_seconds: Option<f64>,
+) -> Result<(Vec<f32>, f64)> {
+ let trace_started = Instant::now();
+ let device = &prepared.device;
+ let queue = &prepared.queue;
+ for sample_index in 0..samples {
+ queue.write_buffer(&prepared.parameters, SAMPLE_INDEX_BYTE_OFFSET, &sample_index.to_le_bytes());
+ let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
+ label: Some("sample"),
+ });
+ {
+ let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
+ label: None,
+ timestamp_writes: None,
+ });
+ pass.set_pipeline(&prepared.pipeline);
+ pass.set_bind_group(0, &prepared.bind_group, &[]);
+ pass.dispatch_workgroups(groups.0, groups.1, 1);
+ }
+ queue.submit(Some(encoder.finish()));
+ if (sample_index + 1) % SAMPLES_PER_WAIT == 0 {
+ let _ = device.poll(wgpu::PollType::wait_indefinitely());
+ if let Some(limit) = max_seconds {
+ if trace_started.elapsed().as_secs_f64() > limit {
+ return Err(failure(format!(
+ "The native trace passed its time limit of {limit} s after {} of {samples} samples.",
+ sample_index + 1
+ )));
+ }
+ }
+ }
+ }
+ let sums = read_accumulation(device, queue, &prepared.accumulation, accumulation_bytes)?;
+ Ok((sums, trace_started.elapsed().as_secs_f64()))
+}
diff --git a/packages/render-native/src/host/textures.rs b/packages/render-native/src/host/textures.rs
new file mode 100644
index 00000000..98b67e83
--- /dev/null
+++ b/packages/render-native/src/host/textures.rs
@@ -0,0 +1,69 @@
+use wgpu::util::DeviceExt;
+
+use crate::host::device::storage_buffer;
+use crate::NativeTraceInput;
+
+const MATERIAL_TEXELS: usize = 10;
+const CUTOUT_START_WORD_INDEX: usize = 47;
+
+pub(crate) struct UploadedSceneBuffers {
+ pub(crate) buffers: Vec<wgpu::Buffer>,
+ pub(crate) accumulation: wgpu::Buffer,
+ pub(crate) parameters: wgpu::Buffer,
+}
+
+/// Whether a material takes its alpha from a colour map and cuts at a threshold. A material is `MATERIAL_TEXELS` vec4s: the cutoff
+/// is the third float of texel 3 and the width of the colour map's atlas rectangle the third float of texel 6.
+pub(crate) fn material_is_cutout(materials: &[f32], material: usize) -> bool {
+ let base = material * MATERIAL_TEXELS * 4;
+ if base + 7 * 4 > materials.len() {
+ return false;
+ }
+ materials[base + 3 * 4 + 2] > 0.0 && materials[base + 6 * 4 + 2] > 0.0
+}
+
+pub(crate) fn upload_scene_buffers(
+ device: &wgpu::Device,
+ input: &NativeTraceInput,
+ triangle_data: &[f32],
+ slot_map: &[u32],
+ opaque_count: usize,
+ accumulation_bytes: u64,
+ extra_buffers: &[(&str, Vec<u8>)],
+) -> UploadedSceneBuffers {
+ // Word 47 of the parameter block tells the kernel where the cutout primitives start in `slot_map`.
+ let mut parameter_bytes = input.parameters.to_vec();
+ let cutout_offset_start = CUTOUT_START_WORD_INDEX * 4;
+ parameter_bytes[cutout_offset_start..cutout_offset_start + 4]
+ .copy_from_slice(&(opaque_count as u32).to_le_bytes());
+
+ let mut buffers = vec![
+ storage_buffer(device, "triangles", bytemuck::cast_slice(triangle_data)),
+ storage_buffer(device, "materials", bytemuck::cast_slice(&input.materials)),
+ storage_buffer(device, "lights", bytemuck::cast_slice(&input.lights)),
+ storage_buffer(device, "atlas", bytemuck::cast_slice(&input.atlas)),
+ storage_buffer(device, "environment colors", bytemuck::cast_slice(&input.environment_colors)),
+ storage_buffer(device, "environment tables", bytemuck::cast_slice(&input.environment_tables)),
+ ];
+ buffers.push(storage_buffer(device, "primitive slots", bytemuck::cast_slice(slot_map)));
+
+ let accumulation = device.create_buffer(&wgpu::BufferDescriptor {
+ label: Some("accumulation"),
+ size: accumulation_bytes,
+ usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
+ mapped_at_creation: false,
+ });
+ for (label, bytes) in extra_buffers {
+ buffers.push(storage_buffer(device, label, bytes));
+ }
+ let parameters = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
+ label: Some("parameters"),
+ contents: &parameter_bytes,
+ usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
+ });
+ UploadedSceneBuffers {
+ buffers,
+ accumulation,
+ parameters,
+ }
+}
diff --git a/packages/render-native/src/lib.rs b/packages/render-native/src/lib.rs
index 7c398eb6..abbb05a5 100644
--- a/packages/render-native/src/lib.rs
+++ b/packages/render-native/src/lib.rs
@@ -1,33 +1,23 @@
//! Hardware ray traced stills for 67js (issue #626). The packed scene tables of the browser path tracer go in, the WGSL
-//! kernel of the #625 spike runs on wgpu with ray queries (Vulkan), and the averaged linear colour comes back.
-//! The kernel keeps the random numbers, light sampling and shading of the browser kernel; only the BVH walk is hardware.
+//! kernel runs on wgpu with ray queries (Vulkan), and the averaged linear colour comes back.
-use std::time::Instant;
+mod cycles;
+mod host;
use napi::bindgen_prelude::{Float32Array, Uint32Array, Uint8Array};
-use napi::{Error, Result};
+use napi::Result;
use napi_derive::napi;
-use wgpu::util::DeviceExt;
+
+use crate::host::device::failure;
+use crate::host::film::{
+ image_accumulation_bytes, image_workgroups, pad_texel_vectors, resolve_image, resolve_texels,
+ texel_accumulation_bytes, texel_workgroups,
+};
+use crate::host::session::{prepare_scene, trace_samples, JobShape};
const KERNEL_SOURCE: &str = include_str!("kernel.wgsl");
/// The texel entry point of the light bake, appended to the kernel for a bake only.
const TEXEL_SOURCE: &str = include_str!("texel.wgsl");
-const WORKGROUP_SIZE: u32 = 8;
-const MATERIAL_TEXELS: usize = 10;
-/// Must match `TEXEL_WORKGROUP_SIZE` in texel.wgsl.
-const TEXEL_WORKGROUP_SIZE: u32 = 64;
-/// A dispatch is at most 65535 workgroups wide; a larger bake wraps onto the second dimension.
-const MAXIMUM_TEXEL_GROUPS_X: u32 = 4096;
-const TRIANGLE_FLOATS: usize = 9 * 4;
-/// The parameter block is 16 vec4s: the 12 of the kernel, the fog box and medium, and the subsurface table offset.
-const PARAMETER_BYTES: usize = 16 * 16;
-/// Byte offsets of the fog density (the fourth float of the first fog vector) and of the subsurface table's vector index.
-const VOLUME_DENSITY_BYTE_OFFSET: usize = 51 * 4;
-const SUBSURFACE_OFFSET_BYTE_OFFSET: usize = 60 * 4;
-/// Byte offset of the sample index inside the parameter block (`emittersFlagsSample.w`).
-const SAMPLE_INDEX_BYTE_OFFSET: u64 = 43 * 4;
-/// Samples submitted before the CPU waits, so a long trace never queues thousands of dispatches.
-const SAMPLES_PER_WAIT: u32 = 4;
#[napi(object)]
pub struct NativeTraceInput {
@@ -52,6 +42,8 @@ pub struct NativeTraceOptions {
pub samples: u32,
/// Stop with an error once the trace has run this long (checked every few samples); absent means no limit.
pub max_seconds: Option<f64>,
+ /// Selects `"legacy"` (default) or `"cycles"`.
+ pub kernel: Option<String>,
}
#[napi(object)]
@@ -109,423 +101,49 @@ pub struct NativeTraceResult {
pub traced_seconds: f64,
}
-fn failure(message: impl Into<String>) -> Error {
- Error::from_reason(message.into())
-}
-
-fn storage_buffer(device: &wgpu::Device, label: &str, bytes: &[u8]) -> wgpu::Buffer {
- let mut padded = bytes.to_vec();
- padded.resize(padded.len().next_multiple_of(4).max(16), 0);
- device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
- label: Some(label),
- contents: &padded,
- usage: wgpu::BufferUsages::STORAGE,
- })
-}
-
-fn layout_entry(binding: u32, ty: wgpu::BindingType) -> wgpu::BindGroupLayoutEntry {
- wgpu::BindGroupLayoutEntry {
- binding,
- visibility: wgpu::ShaderStages::COMPUTE,
- ty,
- count: None,
- }
-}
-
-fn storage_entry(binding: u32, read_only: bool) -> wgpu::BindGroupLayoutEntry {
- layout_entry(
- binding,
- wgpu::BindingType::Buffer {
- ty: wgpu::BufferBindingType::Storage { read_only },
- has_dynamic_offset: false,
- min_binding_size: None,
- },
- )
-}
-
-/// A device with the scene's acceleration structure built and one compute pipeline bound to it.
-struct PreparedScene {
- device: wgpu::Device,
- queue: wgpu::Queue,
- pipeline: wgpu::ComputePipeline,
- bind_group: wgpu::BindGroup,
- accumulation: wgpu::Buffer,
- parameters: wgpu::Buffer,
- adapter_name: String,
- backend_name: String,
- features: String,
- setup_seconds: f64,
- compile_seconds: f64,
- upload_seconds: f64,
- acceleration_build_seconds: f64,
- // The bind group keeps the buffers and the structure alive; holding them here makes that visible.
- _buffers: Vec<wgpu::Buffer>,
- _tlas: wgpu::Tlas,
-}
-
-/// What one kind of job adds to the shared scene setup: the kernel text, its entry point, the accumulation size and the
-/// extra read only buffers bound after the accumulation (bindings 9 and up).
-struct JobShape<'a> {
- source: String,
- entry_point: &'a str,
- accumulation_bytes: u64,
- extra_buffers: Vec<(&'a str, Vec<u8>)>,
-}
-
-fn open_device() -> Result<(wgpu::Device, wgpu::Queue, wgpu::AdapterInfo)> {
- let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
- backends: wgpu::Backends::VULKAN,
- ..wgpu::InstanceDescriptor::new_without_display_handle()
- });
- let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
- power_preference: wgpu::PowerPreference::HighPerformance,
- ..Default::default()
- }))
- .map_err(|error| failure(format!("No Vulkan adapter: {error}")))?;
- if !adapter.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY) {
- return Err(failure("The Vulkan adapter does not support ray queries."));
- }
- let adapter_limits = adapter.limits();
- let required_limits = wgpu::Limits {
- max_storage_buffer_binding_size: adapter_limits.max_storage_buffer_binding_size.min(1 << 30),
- max_buffer_size: adapter_limits.max_buffer_size.min(1 << 30),
- // The light bake binds nine storage buffers (the scene, the accumulation and the texels); the default allows eight.
- max_storage_buffers_per_shader_stage: adapter_limits.max_storage_buffers_per_shader_stage.min(16),
- ..wgpu::Limits::default()
- }
- .using_minimum_supported_acceleration_structure_values();
- let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
- label: Some("render-native"),
- required_features: wgpu::Features::EXPERIMENTAL_RAY_QUERY,
- required_limits,
- experimental_features: unsafe { wgpu::ExperimentalFeatures::enabled() },
- ..Default::default()
- }))
- .map_err(|error| failure(format!("Could not open the device: {error}")))?;
- Ok((device, queue, adapter.get_info()))
-}
-
-/// Whether a material takes its alpha from a colour map and cuts at a threshold. A material is `MATERIAL_TEXELS` vec4s: the cutoff
-/// is the third float of texel 3 and the width of the colour map's atlas rectangle the third float of texel 6.
-fn material_is_cutout(materials: &[f32], material: usize) -> bool {
- let base = material * MATERIAL_TEXELS * 4;
- if base + 7 * 4 > materials.len() {
- return false;
- }
- materials[base + 3 * 4 + 2] > 0.0 && materials[base + 6 * 4 + 2] > 0.0
-}
-
-fn prepare_scene(input: &NativeTraceInput, shape: JobShape) -> Result<PreparedScene> {
- let setup_started = Instant::now();
- let triangle_count = input.triangle_count as usize;
- if triangle_count == 0 || input.triangles.len() < triangle_count * TRIANGLE_FLOATS {
- return Err(failure("The triangle table must hold triangle_count triangles of 9 texels."));
- }
- let triangle_data: &[f32] = &input.triangles[..triangle_count * TRIANGLE_FLOATS];
- if input.parameters.len() != PARAMETER_BYTES {
- return Err(failure("The parameter block must be 256 bytes."));
- }
- let (device, queue, adapter_info) = open_device()?;
- let setup_seconds = setup_started.elapsed().as_secs_f64();
-
- let compile_started = Instant::now();
- // Fog and subsurface scattering compile in only for a scene that uses them: the kernel declares both as false constants.
- let fog_density = f32::from_le_bytes(input.parameters[VOLUME_DENSITY_BYTE_OFFSET..VOLUME_DENSITY_BYTE_OFFSET + 4].try_into().unwrap());
- let subsurface_offset = u32::from_le_bytes(input.parameters[SUBSURFACE_OFFSET_BYTE_OFFSET..SUBSURFACE_OFFSET_BYTE_OFFSET + 4].try_into().unwrap());
- let source = shape
- .source
- .replace("const HAS_VOLUME: bool = false;", &format!("const HAS_VOLUME: bool = {};", fog_density > 0.0))
- .replace("const HAS_SUBSURFACE: bool = false;", &format!("const HAS_SUBSURFACE: bool = {};", subsurface_offset > 0));
- let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
- label: Some("path tracer"),
- source: wgpu::ShaderSource::Wgsl(source.into()),
- });
- let mut layout_entries = vec![
- layout_entry(
- 0,
- wgpu::BindingType::Buffer {
- ty: wgpu::BufferBindingType::Uniform,
- has_dynamic_offset: false,
- min_binding_size: None,
- },
- ),
- layout_entry(1, wgpu::BindingType::AccelerationStructure { vertex_return: false }),
- ];
- layout_entries.extend((2..=7).map(|binding| storage_entry(binding, true)));
- layout_entries.push(storage_entry(8, false));
- layout_entries.extend((0..shape.extra_buffers.len() + 1).map(|offset| storage_entry(9 + offset as u32, true)));
- let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
- label: Some("path tracer"),
- entries: &layout_entries,
- });
- let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
- label: Some("path tracer"),
- bind_group_layouts: &[Some(&bind_group_layout)],
- immediate_size: 0,
- });
- let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
- label: Some("path tracer"),
- layout: Some(&pipeline_layout),
- module: &module,
- entry_point: Some(shape.entry_point),
- compilation_options: Default::default(),
- cache: None,
- });
- let compile_seconds = compile_started.elapsed().as_secs_f64();
-
- let upload_started = Instant::now();
- // The corners of every triangle: the table stores a corner and two edges in its first three texels. Opaque triangles come
- // first and alpha cutout triangles after them, because the hardware takes its opaque flag per geometry; `slot_map`
- // gives the table slot of each hardware primitive (the opaque ones, then the cutouts).
- let mut opaque_vertices: Vec<f32> = Vec::with_capacity(triangle_count * 9);
- let mut cutout_vertices: Vec<f32> = Vec::new();
- let mut slot_map: Vec<u32> = Vec::with_capacity(triangle_count);
- let mut cutout_slots: Vec<u32> = Vec::new();
- for (slot, triangle) in triangle_data.chunks_exact(TRIANGLE_FLOATS).enumerate() {
- let corner = [triangle[0], triangle[1], triangle[2]];
- let edge_first = [triangle[4], triangle[5], triangle[6]];
- let edge_second = [triangle[8], triangle[9], triangle[10]];
- let is_cutout = material_is_cutout(&input.materials, triangle[3] as usize);
- let vertices = if is_cutout { &mut cutout_vertices } else { &mut opaque_vertices };
- vertices.extend_from_slice(&corner);
- vertices.extend((0..3).map(|axis| corner[axis] + edge_first[axis]));
- vertices.extend((0..3).map(|axis| corner[axis] + edge_second[axis]));
- if is_cutout {
- cutout_slots.push(slot as u32);
- } else {
- slot_map.push(slot as u32);
- }
- }
- let opaque_count = slot_map.len();
- slot_map.extend(cutout_slots);
- let mut vertices = opaque_vertices;
- vertices.extend(cutout_vertices);
- // Word 47 of the parameter block tells the kernel where the cutout primitives start in `slot_map`.
- let mut parameter_bytes = input.parameters.to_vec();
- parameter_bytes[47 * 4..48 * 4].copy_from_slice(&(opaque_count as u32).to_le_bytes());
- let vertex_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
- label: Some("triangle corners"),
- contents: bytemuck::cast_slice(&vertices),
- usage: wgpu::BufferUsages::BLAS_INPUT,
- });
- let mut buffers = vec![
- storage_buffer(&device, "triangles", bytemuck::cast_slice(triangle_data)),
- storage_buffer(&device, "materials", bytemuck::cast_slice(&input.materials)),
- storage_buffer(&device, "lights", bytemuck::cast_slice(&input.lights)),
- storage_buffer(&device, "atlas", bytemuck::cast_slice(&input.atlas)),
- storage_buffer(&device, "environment colors", bytemuck::cast_slice(&input.environment_colors)),
- storage_buffer(&device, "environment tables", bytemuck::cast_slice(&input.environment_tables)),
- ];
- buffers.push(storage_buffer(&device, "primitive slots", bytemuck::cast_slice(&slot_map)));
- let accumulation = device.create_buffer(&wgpu::BufferDescriptor {
- label: Some("accumulation"),
- size: shape.accumulation_bytes,
- usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
- mapped_at_creation: false,
- });
- for (label, bytes) in &shape.extra_buffers {
- buffers.push(storage_buffer(&device, label, bytes));
- }
- let parameters = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
- label: Some("parameters"),
- contents: &parameter_bytes,
- usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
- });
- let upload_seconds = upload_started.elapsed().as_secs_f64();
-
- let build_started = Instant::now();
- // Opaque triangles never reach the any-hit loop of the kernel; cutout triangles are candidates it confirms when the alpha
- // of their colour map reaches the material's cutoff (see `traceRay`).
- let mut geometry_sizes: Vec<wgpu::BlasTriangleGeometrySizeDescriptor> = Vec::new();
- let mut geometry_vertex_starts: Vec<u32> = Vec::new();
- for (first_triangle, triangles_in_geometry, flags) in [
- (0, opaque_count, wgpu::AccelerationStructureGeometryFlags::OPAQUE),
- (opaque_count, triangle_count - opaque_count, wgpu::AccelerationStructureGeometryFlags::empty()),
- ] {
- if triangles_in_geometry == 0 {
- continue;
- }
- geometry_vertex_starts.push((first_triangle * 3) as u32);
- geometry_sizes.push(wgpu::BlasTriangleGeometrySizeDescriptor {
- vertex_format: wgpu::VertexFormat::Float32x3,
- vertex_count: (triangles_in_geometry * 3) as u32,
- index_format: None,
- index_count: None,
- flags,
- });
- }
- let blas = device.create_blas(
- &wgpu::CreateBlasDescriptor {
- label: Some("scene"),
- flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
- update_mode: wgpu::AccelerationStructureUpdateMode::Build,
- },
- wgpu::BlasGeometrySizeDescriptors::Triangles {
- descriptors: geometry_sizes.clone(),
- },
- );
- let mut tlas = device.create_tlas(&wgpu::CreateTlasDescriptor {
- label: Some("scene"),
- flags: wgpu::AccelerationStructureFlags::PREFER_FAST_TRACE,
- update_mode: wgpu::AccelerationStructureUpdateMode::Build,
- max_instances: 1,
- });
- tlas[0] = Some(wgpu::TlasInstance::new(
- &blas,
- [1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0],
- 0,
- 0xFF,
- ));
- let triangle_geometries: Vec<wgpu::BlasTriangleGeometry> = geometry_sizes
- .iter()
- .zip(&geometry_vertex_starts)
- .map(|(size, first_vertex)| wgpu::BlasTriangleGeometry {
- size,
- vertex_buffer: &vertex_buffer,
- first_vertex: *first_vertex,
- vertex_stride: 12,
- index_buffer: None,
- first_index: None,
- transform_buffer: None,
- transform_buffer_offset: None,
- })
- .collect();
- let mut build_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("build") });
- build_encoder.build_acceleration_structures(
- std::iter::once(&wgpu::BlasBuildEntry {
- blas: &blas,
- geometry: wgpu::BlasGeometries::TriangleGeometries(triangle_geometries),
- }),
- std::iter::once(&tlas),
- );
- queue.submit(Some(build_encoder.finish()));
- let _ = device.poll(wgpu::PollType::wait_indefinitely());
- let acceleration_build_seconds = build_started.elapsed().as_secs_f64();
-
- let mut entries = vec![
- wgpu::BindGroupEntry { binding: 0, resource: parameters.as_entire_binding() },
- wgpu::BindGroupEntry { binding: 1, resource: tlas.as_binding() },
- ];
- for (offset, buffer) in buffers[..6].iter().enumerate() {
- entries.push(wgpu::BindGroupEntry { binding: 2 + offset as u32, resource: buffer.as_entire_binding() });
- }
- entries.push(wgpu::BindGroupEntry { binding: 8, resource: accumulation.as_entire_binding() });
- for (offset, buffer) in buffers[6..].iter().enumerate() {
- entries.push(wgpu::BindGroupEntry { binding: 9 + offset as u32, resource: buffer.as_entire_binding() });
- }
- let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
- label: Some("path tracer"),
- layout: &bind_group_layout,
- entries: &entries,
- });
- let features = if device.features().contains(wgpu::Features::EXPERIMENTAL_RAY_QUERY) { "EXPERIMENTAL_RAY_QUERY" } else { "" };
- Ok(PreparedScene {
- device,
- queue,
- pipeline,
- bind_group,
- accumulation,
- parameters,
- adapter_name: adapter_info.name,
- backend_name: format!("{:?}", adapter_info.backend),
- features: features.to_string(),
- setup_seconds,
- compile_seconds,
- upload_seconds,
- acceleration_build_seconds,
- _buffers: buffers,
- _tlas: tlas,
- })
-}
-
-/// Runs every sample over `groups` workgroups and copies the accumulation back. `max_seconds` bounds the run: past it the
-/// trace stops with an error instead of finishing, checked each time the CPU waits for the card. Returns the sums and the
-/// seconds it took.
-fn trace_samples(prepared: &PreparedScene, samples: u32, groups: (u32, u32), accumulation_bytes: u64, max_seconds: Option<f64>) -> Result<(Vec<f32>, f64)> {
- let trace_started = Instant::now();
- let device = &prepared.device;
- let queue = &prepared.queue;
- for sample_index in 0..samples {
- queue.write_buffer(&prepared.parameters, SAMPLE_INDEX_BYTE_OFFSET, &sample_index.to_le_bytes());
- let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("sample") });
- {
- let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { label: None, timestamp_writes: None });
- pass.set_pipeline(&prepared.pipeline);
- pass.set_bind_group(0, &prepared.bind_group, &[]);
- pass.dispatch_workgroups(groups.0, groups.1, 1);
- }
- queue.submit(Some(encoder.finish()));
- if (sample_index + 1) % SAMPLES_PER_WAIT == 0 {
- let _ = device.poll(wgpu::PollType::wait_indefinitely());
- if let Some(limit) = max_seconds {
- if trace_started.elapsed().as_secs_f64() > limit {
- return Err(failure(format!(
- "The native trace passed its time limit of {limit} s after {} of {samples} samples.",
- sample_index + 1
- )));
- }
- }
+fn select_kernel_source(requested_kernel: Option<&str>) -> Result<(String, bool)> {
+ let kernel_name = match requested_kernel {
+ Some(name) => name,
+ None => "legacy",
+ };
+ match kernel_name {
+ "legacy" => Ok((KERNEL_SOURCE.to_string(), true)),
+ "cycles" => {
+ let source = cycles::assemble_cycles_kernel()?;
+ Ok((source, false))
}
+ other => Err(failure(format!(
+ "Invalid native kernel {other:?}: pass \"legacy\" or \"cycles\" in options.kernel or JS67_NATIVE_KERNEL."
+ ))),
}
- let readback = device.create_buffer(&wgpu::BufferDescriptor {
- label: Some("readback"),
- size: accumulation_bytes,
- usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
- mapped_at_creation: false,
- });
- let mut copy_encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("readback") });
- copy_encoder.copy_buffer_to_buffer(&prepared.accumulation, 0, &readback, 0, accumulation_bytes);
- queue.submit(Some(copy_encoder.finish()));
- readback.slice(..).map_async(wgpu::MapMode::Read, |_| {});
- let _ = device.poll(wgpu::PollType::wait_indefinitely());
- let mapped = readback.slice(..).get_mapped_range().map_err(|error| failure(format!("Could not read the result back: {error}")))?;
- let sums: Vec<f32> = bytemuck::cast_slice::<u8, f32>(&mapped).to_vec();
- drop(mapped);
- Ok((sums, trace_started.elapsed().as_secs_f64()))
}
/// Traces the packed scene on the GPU with hardware ray queries.
#[napi]
pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Result<NativeTraceResult> {
+ let (source, rewrite_specialization_flags) = select_kernel_source(options.kernel.as_deref())?;
let pixel_count = options.width as u64 * options.height as u64;
- let accumulation_bytes = pixel_count * 4 * 16;
+ let accumulation_bytes = image_accumulation_bytes(options.width, options.height);
let prepared = prepare_scene(
&input,
- JobShape { source: KERNEL_SOURCE.to_string(), entry_point: "main", accumulation_bytes, extra_buffers: Vec::new() },
+ JobShape {
+ source,
+ entry_point: "main",
+ rewrite_specialization_flags,
+ accumulation_bytes,
+ extra_buffers: Vec::new(),
+ },
)?;
- let groups = (options.width.div_ceil(WORKGROUP_SIZE), options.height.div_ceil(WORKGROUP_SIZE));
+ let groups = image_workgroups(options.width, options.height);
let (sums, traced_seconds) = trace_samples(&prepared, options.samples, groups, accumulation_bytes, options.max_seconds)?;
- let plane_length = pixel_count as usize * 4;
- let mut taken_total = 0.0f64;
- let mut rgba = Vec::with_capacity(pixel_count as usize * 4);
- let mut albedo = Vec::with_capacity(pixel_count as usize * 3);
- let mut normal = Vec::with_capacity(pixel_count as usize * 3);
- let mut depth = Vec::with_capacity(pixel_count as usize);
- let mut variance = Vec::with_capacity(pixel_count as usize);
- for pixel in 0..pixel_count as usize {
- let radiance = &sums[pixel * 4..pixel * 4 + 4];
- let albedo_sum = &sums[plane_length + pixel * 4..plane_length + pixel * 4 + 3];
- let normal_sum = &sums[2 * plane_length + pixel * 4..2 * plane_length + pixel * 4 + 3];
- let statistics = &sums[3 * plane_length + pixel * 4..3 * plane_length + pixel * 4 + 4];
- // A pixel that converged early drew fewer samples; its sums are divided by its own count.
- let taken = statistics[3].max(1.0);
- taken_total += taken as f64;
- let sample_scale = 1.0 / taken;
- let variance_divisor = (taken - 1.0).max(1.0);
- rgba.extend_from_slice(&[radiance[0] * sample_scale, radiance[1] * sample_scale, radiance[2] * sample_scale, 1.0]);
- depth.push(radiance[3] * sample_scale);
- albedo.extend(albedo_sum.iter().map(|value| value * sample_scale));
- normal.extend(normal_sum.iter().map(|value| value * sample_scale));
- let mean_luminance = statistics[0] * sample_scale;
- variance.push((statistics[1] * sample_scale - mean_luminance * mean_luminance).max(0.0) / variance_divisor);
- }
+ let resolved = resolve_image(&sums, pixel_count);
Ok(NativeTraceResult {
- rgba: Float32Array::new(rgba),
- albedo: Float32Array::new(albedo),
- normal: Float32Array::new(normal),
- depth: Float32Array::new(depth),
- variance: Float32Array::new(variance),
- average_samples: taken_total / pixel_count.max(1) as f64,
+ rgba: Float32Array::new(resolved.rgba),
+ albedo: Float32Array::new(resolved.albedo),
+ normal: Float32Array::new(resolved.normal),
+ depth: Float32Array::new(resolved.depth),
+ variance: Float32Array::new(resolved.variance),
+ average_samples: resolved.average_samples,
adapter: prepared.adapter_name,
backend: prepared.backend_name,
features: prepared.features,
@@ -537,16 +155,6 @@ pub fn trace_scene(input: NativeTraceInput, options: NativeTraceOptions) -> Resu
})
}
-/// Three floats per texel, padded to the four the kernel's vec4 arrays read.
-fn pad_vectors(vectors: &[f32], count: usize) -> Vec<u8> {
- let mut padded: Vec<f32> = Vec::with_capacity(count * 4);
- for texel in 0..count {
- padded.extend_from_slice(&vectors[texel * 3..texel * 3 + 3]);
- padded.push(0.0);
- }
- bytemuck::cast_slice(&padded).to_vec()
-}
-
/// The light that reaches each lightmap texel: `options.samples` cosine weighted paths from every texel, traced with the
/// scene's ray queries. The parameter block of `input` carries the lights, the bounces and the seed; its texel count and
/// sample count words are the ones `buildNativeTexelInput` writes.
@@ -556,33 +164,26 @@ pub fn trace_texels(input: NativeTraceInput, texels: NativeTexels, options: Nati
if count == 0 || texels.points.len() < count * 3 || texels.normals.len() < count * 3 {
return Err(failure("The texel points and normals must hold three floats for each of `count` texels."));
}
- let accumulation_bytes = count as u64 * 2 * 16;
+ let accumulation_bytes = texel_accumulation_bytes(count);
let prepared = prepare_scene(
&input,
JobShape {
source: format!("{KERNEL_SOURCE}\n{TEXEL_SOURCE}"),
entry_point: "bakeTexels",
+ rewrite_specialization_flags: true,
accumulation_bytes,
extra_buffers: vec![
- ("texel points", pad_vectors(&texels.points, count)),
- ("texel normals", pad_vectors(&texels.normals, count)),
+ ("texel points", pad_texel_vectors(&texels.points, count)),
+ ("texel normals", pad_texel_vectors(&texels.normals, count)),
],
},
)?;
- let workgroups = (count as u32).div_ceil(TEXEL_WORKGROUP_SIZE);
- let groups_x = workgroups.min(MAXIMUM_TEXEL_GROUPS_X);
- let groups = (groups_x, workgroups.div_ceil(groups_x));
+ let groups = texel_workgroups(count as u32);
let (sums, traced_seconds) = trace_samples(&prepared, options.samples, groups, accumulation_bytes, options.max_seconds)?;
- let sample_scale = 1.0 / options.samples.max(1) as f32;
- let mut radiance = Vec::with_capacity(count * 3);
- let mut escaped = Vec::with_capacity(count);
- for texel in 0..count {
- radiance.extend(sums[texel * 4..texel * 4 + 3].iter().map(|value| value * sample_scale));
- escaped.push(sums[(count + texel) * 4] * sample_scale);
- }
+ let resolved = resolve_texels(&sums, count, options.samples);
Ok(NativeTexelResult {
- radiance: Float32Array::new(radiance),
- escaped: Float32Array::new(escaped),
+ radiance: Float32Array::new(resolved.radiance),
+ escaped: Float32Array::new(resolved.escaped),
adapter: prepared.adapter_name,
backend: prepared.backend_name,
setup_seconds: prepared.setup_seconds,
diff --git a/tests/native-pack-input.test.js b/tests/native-pack-input.test.js
index c3bc15b7..a53a50b5 100644
--- a/tests/native-pack-input.test.js
+++ b/tests/native-pack-input.test.js
@@ -1,6 +1,7 @@
import assert from 'node:assert/strict';
import test from 'node:test';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { findNativeAddon, resolveNativeKernel, traceNative } from '../packages/render-native/index.mjs';
import { buildNativeInput } from '../packages/render-native/pack-input.mjs';
import { createCamera } from '../src/path-tracer.js';
import { buildTraceScene } from '../src/path-tracer-scene.js';
@@ -66,3 +67,195 @@ test('the kernel declares the two constants the host rewrites and reads the vect
assert.match(kernel, /const HAS_SUBSURFACE: bool = false;/);
assert.match(kernel, /volumeMinimumDensity: vec4<f32>,\s+volumeMaximumAnisotropy: vec4<f32>,\s+volumeAlbedoDistance: vec4<f32>,\s+\/\/[^\n]*\n\s+extras: vec4<u32>,/);
});
+
+function withKernelEnv(value, callback) {
+ const hadKey = Object.prototype.hasOwnProperty.call(process.env, 'JS67_NATIVE_KERNEL');
+ const previous = process.env.JS67_NATIVE_KERNEL;
+ if (value === undefined) {
+ delete process.env.JS67_NATIVE_KERNEL;
+ } else {
+ process.env.JS67_NATIVE_KERNEL = value;
+ }
+ try {
+ return callback();
+ } finally {
+ if (hadKey) {
+ process.env.JS67_NATIVE_KERNEL = previous;
+ } else {
+ delete process.env.JS67_NATIVE_KERNEL;
+ }
+ }
+}
+
+test('resolveNativeKernel defaults to legacy, falls back to JS67_NATIVE_KERNEL, and rejects unknown names', () => {
+ withKernelEnv(undefined, () => {
+ assert.equal(resolveNativeKernel(undefined), 'legacy');
+ assert.equal(resolveNativeKernel('legacy'), 'legacy');
+ assert.equal(resolveNativeKernel('cycles'), 'cycles');
+ });
+ withKernelEnv('', () => {
+ assert.equal(resolveNativeKernel(undefined), 'legacy');
+ });
+ withKernelEnv('cycles', () => {
+ assert.equal(resolveNativeKernel(undefined), 'cycles');
+ assert.equal(resolveNativeKernel('legacy'), 'legacy');
+ });
+ withKernelEnv('bogus', () => {
+ assert.throws(() => resolveNativeKernel(undefined), /Invalid native kernel.*"legacy".*"cycles"/);
+ assert.equal(resolveNativeKernel('legacy'), 'legacy');
+ });
+ const input = buildNativeInput(buildTraceScene(plainParts, {}), camera, options, pack);
+ for (const invalid of ['optix', '', null, 42]) {
+ assert.throws(
+ () => traceNative(input, { ...options, kernel: invalid }),
+ /Invalid native kernel.*"legacy".*"cycles"/,
+ );
+ }
+});
+
+test('traceNative fails cleanly without crashing when cycles kernel manifest has no main entry point', { skip: !findNativeAddon() }, () => {
+ const input = buildNativeInput(buildTraceScene(plainParts, {}), camera, options, pack);
+ assert.throws(
+ () => traceNative(input, { ...options, kernel: 'cycles' }),
+ /Cycles native kernel.*@compute main/,
+ );
+ withKernelEnv('cycles', () => {
+ assert.throws(
+ () => traceNative(input, options),
+ /Cycles native kernel.*@compute main/,
+ );
+ const legacyResult = traceNative(input, { ...options, kernel: 'legacy' });
+ assert.equal(legacyResult.rgba.length, options.width * options.height * 4);
+ assert.ok(legacyResult.rgba.every(Number.isFinite));
+ });
+});
+
+function wgslFieldMetrics(wgslType) {
+ const table = {
+ u32: { size: 4, align: 4 },
+ i32: { size: 4, align: 4 },
+ f32: { size: 4, align: 4 },
+ 'vec2<f32>': { size: 8, align: 8 },
+ 'vec2<u32>': { size: 8, align: 8 },
+ 'vec3<f32>': { size: 12, align: 16 },
+ 'vec3<u32>': { size: 12, align: 16 },
+ 'vec4<f32>': { size: 16, align: 16 },
+ 'vec4<u32>': { size: 16, align: 16 },
+ };
+ return table[wgslType] ?? null;
+}
+
+function parseWgslStructs(source) {
+ const uncommented = source.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+ const structs = new Map();
+ const structPattern = /struct\s+([A-Za-z_]\w*)\s*\{([^}]*)\}/g;
+ for (const match of uncommented.matchAll(structPattern)) {
+ const [, structName, body] = match;
+ const fields = [];
+ for (const rawField of body.split(/,(?![^<]*>)/)) {
+ const trimmed = rawField.trim();
+ if (!trimmed) continue;
+ const fieldMatch = /^(?:@align\((\d+)\)\s+)?([A-Za-z_]\w*)\s*:\s*(.+)$/.exec(trimmed);
+ assert.ok(fieldMatch, `Could not parse WGSL field in ${structName}: ${trimmed}`);
+ fields.push({
+ explicitAlign: fieldMatch[1] ? Number(fieldMatch[1]) : null,
+ name: fieldMatch[2],
+ type: fieldMatch[3].trim(),
+ });
+ }
+ structs.set(structName, fields);
+ }
+ return { uncommented, structs };
+}
+
+function parseFormatV2Tables(markdown) {
+ const sections = new Map();
+ const sectionPattern = /^##\s+\d+\.[^\n]*`([A-Za-z0-9_]+)`[\s\S]*?Total (?:size|stride):\s*\*\*(\d+) bytes\*\*[\s\S]*?\n\| Byte Offset[^\n]*\n\|[-:\s|]+\n((?:\|[^\n]*\n)+)/gm;
+ for (const match of markdown.matchAll(sectionPattern)) {
+ const [, structName, strideText, rowsText] = match;
+ const rows = rowsText
+ .trim()
+ .split(/\r?\n/)
+ .map(line => {
+ const columns = line.split('|').slice(1, -1).map(cell => cell.trim().replace(/^`|`$/g, ''));
+ return {
+ offset: Number(columns[0]),
+ size: Number(columns[1]),
+ align: Number(columns[2]),
+ type: columns[3],
+ name: columns[4],
+ };
+ });
+ sections.set(structName, { totalStride: Number(strideText), rows });
+ }
+ return sections;
+}
+
+test('cycles kernel manifest, signatures-only abi.wgsl, and FORMAT-v2.md agree byte for byte', () => {
+ const manifestUrl = new URL('../packages/render-native/src/cycles/kernel-manifest.txt', import.meta.url);
+ const manifestEntries = readFileSync(manifestUrl, 'utf8')
+ .split(/\r?\n/)
+ .map(line => line.split('#')[0].trim())
+ .filter(Boolean);
+ assert.ok(manifestEntries.includes('abi.wgsl'), 'kernel-manifest.txt must list abi.wgsl first');
+ for (const entry of manifestEntries) {
+ assert.ok(
+ existsSync(new URL(`../packages/render-native/src/cycles/${entry}`, import.meta.url)),
+ `Missing WGSL file listed in kernel-manifest.txt: ${entry}`,
+ );
+ }
+
+ const abiSource = readFileSync(new URL('../packages/render-native/src/cycles/abi.wgsl', import.meta.url), 'utf8');
+ assert.match(abiSource, /fn closure_eval\(closure: Closure, wi: vec3<f32>, wo: vec3<f32>\) -> ClosureEval/);
+ assert.match(abiSource, /fn closure_sample\(closure: Closure, wo: vec3<f32>, u: vec3<f32>\) -> ClosureSample/);
+
+ const { uncommented, structs } = parseWgslStructs(abiSource);
+ assert.doesNotMatch(uncommented, /\bfn\s+[A-Za-z_]\w*/, 'abi.wgsl must be signatures-only with no stub fn bodies');
+ for (const requiredStruct of ['ShadingPoint', 'Lobe', 'Closure', 'ClosureEval', 'ClosureSample']) {
+ assert.ok(structs.has(requiredStruct), `abi.wgsl must define ${requiredStruct}`);
+ }
+ for (let binding = 0; binding <= 11; binding++) {
+ assert.match(uncommented, new RegExp(`@group\\(0\\)\\s*@binding\\(${binding}\\)`));
+ }
+
+ const formatMarkdown = readFileSync(new URL('../packages/render-native/FORMAT-v2.md', import.meta.url), 'utf8');
+ const documentedStructs = parseFormatV2Tables(formatMarkdown);
+ const expectedBufferStructs = [
+ 'KernelParamsV2',
+ 'InstanceRecord',
+ 'TriangleRecord',
+ 'MaterialRecord',
+ 'EmissiveTriangleRecord',
+ 'LightRecord',
+ 'LightTreeNode',
+ 'TextureDescriptor',
+ ];
+ assert.deepEqual([...documentedStructs.keys()].sort(), [...expectedBufferStructs].sort());
+
+ for (const structName of expectedBufferStructs) {
+ const wgslFields = structs.get(structName);
+ assert.ok(wgslFields, `Missing ${structName} in abi.wgsl`);
+ const documented = documentedStructs.get(structName);
+ assert.equal(wgslFields.length, documented.rows.length, `${structName} field count mismatch`);
+ let cursor = 0;
+ let structAlign = 1;
+ for (let index = 0; index < wgslFields.length; index++) {
+ const wgslField = wgslFields[index];
+ const docRow = documented.rows[index];
+ const baseMetrics = wgslFieldMetrics(wgslField.type);
+ assert.ok(baseMetrics, `Unsupported WGSL field type ${wgslField.type} in ${structName}.${wgslField.name}`);
+ const fieldAlign = Math.max(baseMetrics.align, wgslField.explicitAlign ?? 0);
+ assert.equal(wgslField.name, docRow.name, `${structName} field #${index} name`);
+ assert.equal(wgslField.type, docRow.type, `${structName}.${wgslField.name} type`);
+ assert.equal(cursor % fieldAlign, 0, `${structName}.${wgslField.name} has implicit padding at byte ${cursor}`);
+ assert.equal(cursor, docRow.offset, `${structName}.${wgslField.name} byte offset`);
+ assert.equal(baseMetrics.size, docRow.size, `${structName}.${wgslField.name} byte size`);
+ assert.equal(fieldAlign, docRow.align, `${structName}.${wgslField.name} byte align`);
+ cursor += baseMetrics.size;
+ if (fieldAlign > structAlign) structAlign = fieldAlign;
+ }
+ assert.equal(structAlign, 16, `${structName} must stay 16-byte aligned`);
+ assert.equal(cursor % structAlign, 0, `${structName} total stride ${cursor} must be a multiple of 16`);
+ assert.equal(cursor, documented.totalStride, `${structName} total byte stride`);
+ }
+});