Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Document instanced native jobs, emissive offsets and sharing rules (#896)

Nguyen Xuan Anea2cd3c79081
diff --git a/changes/896-instancing-export.md b/changes/896-instancing-export.md
new file mode 100644
index 00000000..98c872db
--- /dev/null
+++ b/changes/896-instancing-export.md
@@ -0,0 +1 @@
+- Native render jobs keep repeated geometry as instances on the `cycles` kernel, and a copy whose material makes the shared mesh emissive is sampled as a light at the right triangle (#896)
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index f7697d12..e6ae81ca 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -63,7 +63,9 @@ Also checked before any ray is traced: samples times pixels times bounces at mos
- Sharing is decided after the trace geometry is resolved. A skinned, flush-lifted or box-mapped part gets a geometry of its own, and a geometry with per-triangle materials is not shared either: those parts are moved into world space once and traced as instances with an identity matrix.
- Limits: 400,000 triangles counted once per shared geometry, 1,024 distinct geometries (the part limit, counted on geometries) and 65,536 instances. An instanced scene has no world-space triangle arrays or CPU BVH, so only `buildNativeInputV2` reads it.
- A part's material is its own entry in `materials`, so copies may differ in material; a multi-material mesh stays one geometry with the materials the part names.
-- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. Render jobs still export flattened tables.
+- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. `traceNative` with `kernel: "legacy"` refuses a FORMAT-v2 input the same way.
+- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, or a scene where no geometry is shared, the job exports flattened tables exactly as before.
+- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.
The same scene and options give the same bytes. Random numbers come from a hash of the pixel, the sample and the seed, never from `Math.random` or the clock, and a pixel does not depend on which thread drew it.
diff --git a/packages/render-native/FORMAT-v2.md b/packages/render-native/FORMAT-v2.md
index 70e244fc..b5e30f0e 100644
--- a/packages/render-native/FORMAT-v2.md
+++ b/packages/render-native/FORMAT-v2.md
@@ -131,6 +131,12 @@ Total stride: **224 bytes** (`14 × 16 B`), alignment: **16 bytes**. Within each
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`.
+**Sharing rules.** Instances that share a mesh share one slice of `triangles` (one BLAS, one `triangle_offset`), so everything in a `TriangleRecord` is the same for every copy. What can differ per copy lives in the `InstanceRecord`: the transform, `material_override`, `visibility_flags`, the light masks, the object id, random and colour, and `emissive_base_offset`. The packer applies these rules:
+
+- A mesh with per-triangle materials is not shared; its triangles are baked into world space and traced with an identity transform.
+- `local_emissive_offset` counts the triangles that keep an area after an instance's transform, in triangle order, and is the same for every copy. A copy that would emit a different set of triangles is refused. A copy whose resolved material is not emissive gets `emissive_base_offset = 0xFFFFFFFF`, so its triangles never index the emissive list.
+- A shadow-only copy clears the camera bit of `visibility_flags` and keeps the others. A mirrored copy (negative determinant) sets the negative-scale bit.
+
| Byte Offset | Size (B) | Alignment (B) | WGSL Type | Field | Description |
| ---: | ---: | ---: | :--- | :--- | :--- |
| `0` | `12` | `16` | `vec3<f32>` | `p0` | Object-space vertex 0 position |
diff --git a/packages/render-native/README.md b/packages/render-native/README.md
index f6b61e05..9465f6ef 100644
--- a/packages/render-native/README.md
+++ b/packages/render-native/README.md
@@ -50,6 +50,10 @@ The Cook kernel splits a render into dispatches that each aim for about 0.5 s, s
The split does not change the image. The `cycles` kernel carries each pixel's running sums through a dispatch and adds one sample at a time in sample order, so the float32 additions into the film come in the same order whether a dispatch draws 1 sample or 64, and two renders of the same scene, seed and settings are byte-identical even when their time-sized splits differ. The `legacy` kernel draws one sample per dispatch and adds it straight to the film, so it has the same property. `tests/native-dispatch-determinism.test.js` renders with different `samplesPerDispatch` values and compares the bytes. A fixed `samplesPerDispatch` of 1 gives the same bytes as before this change; larger batches now match it instead of adding a per-dispatch partial sum.
+## Instanced scenes
+
+`buildTraceScene(parts, environment, { instancing: true })` keeps parts that share one geometry object as instances, and `buildNativeInputV2` packs the unique triangles once with one instance record per part, for `traceNative` with `kernel: "cycles"`. The `legacy` kernel and `buildNativeInput` refuse that input and name the fix. Render jobs on the native backend send instanced scenes to the `cycles` kernel by default. The sharing rules are in [FORMAT-v2.md](./FORMAT-v2.md), the equivalence numbers against flattened in [docs/cycles-parity.md](../../docs/cycles-parity.md), section "Instancing equivalence (#896, slice I2)".
+
## Sessions
`traceNative` builds everything for each call: it opens the device handle, uploads the scene, builds the acceleration structures, compiles the kernel and allocates the film. A session keeps those on the card between frames of one scene (the `cycles` kernel only):