@woosh/meep-engine 3.14.5 → 3.15.0

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Tunables of the adaptive voxel-based OIT path. See `AVBOIT_PLAN_2026_09_03.md` §3 for what each one
+ * trades against; none of them is exposed on `Renderer` yet (plan §7).
+ */
+/**
+ * Physical depth slices of the extinction volume — what is actually allocated and integrated.
+ * The deck ships 128.
+ * @type {number}
+ */
+export const AVBOIT_PHYSICAL_SLICES: number;
+/**
+ * Virtual depth slices at which occupancy is measured before adaptation. Must be a power of two
+ * multiple of {@link AVBOIT_PHYSICAL_SLICES} and a multiple of 32 (one occupancy bit per slice,
+ * packed in `u32` words). Halved until the occupied count fits the physical budget.
+ *
+ * This sets the slice floor — the finest depth separation two surfaces can have and still occlude
+ * each other — when the volume is sparse enough not to halve. The curve is pure log from
+ * `near + AVBOIT_DEPTH_CURVE_NEAR_OFFSET` (see `avboit_build_depth_curve`), so virtual slice
+ * thickness at view depth `z` is `z · ln(far / offset) / (V - 1)`. With `near = 0.1`, `far = 200` and
+ * this value: 1.6 cm at 10 m, 3.2 cm at 20 m, 8 cm at 50 m. The draw's two-slice bias means two
+ * surfaces need more than two slices between them, so 5 cm of separation resolves out to roughly
+ * 15 m. At 1024 the same numbers were four times coarser and 5 cm at 10 m already blended (ledger
+ * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and a longer
+ * single-lane loop in the warp build — none of which registers.
+ * @type {number}
+ */
+export const AVBOIT_VIRTUAL_SLICES_MAX: number;
+/**
+ * Occupancy words: one bit per virtual slice.
+ * @type {number}
+ */
+export const AVBOIT_OCCUPANCY_WORDS: number;
+/**
+ * The extinction volume's XY resolution is the internal resolution divided by this, rounded up. The
+ * deck uses 1/8 at every target resolution it reports.
+ * @type {number}
+ */
+export const AVBOIT_VOXEL_DOWNSCALE: number;
+/**
+ * Where the depth curve starts, in world units past the camera's near plane. The curve is the
+ * engine's log slicing (`build_light_cluster_parameters`, `cluster_depth_to_z_slice`) from
+ * `near + offset` to `far`; the offset keeps the first slices from being spent on the few
+ * centimetres in front of the lens. The engine's own default for its light clusters.
+ * @type {number}
+ */
+export const AVBOIT_DEPTH_CURVE_NEAR_OFFSET: number;
+/**
+ * Extinction that the normalized fixed-point unit `1.0` stands for. `ln 256` puts full saturation at a
+ * transmittance of `1/256`, which the integration treats as zero. The 8-bit splat unit is therefore
+ * `ln 256 / 255 ≈ 0.0217` of extinction, i.e. the finest single-event occlusion that registers in the
+ * volume is about 2.2 %.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCTION_MAX: number;
+/**
+ * Transmittance below which a fragment is fully occluded as far as the volume can tell: the integral
+ * saturates at `1.0`, which is `exp(-AVBOIT_EXTINCTION_MAX) = 1/256`. The draw discards a fragment
+ * whose sampled transmittance is at or below this in every channel before shading it. What that
+ * costs in correctness is bounded: the fragment's own extinction no longer joins the total, so the
+ * background is weighted by at most `1/256` instead of something smaller — below what the 8-bit
+ * volume resolves anyway.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCT_TRANSMITTANCE: number;
+/**
+ * Counts per unit of normalized extinction at the splat: values are stored 8-bit in 10-bit fields, so
+ * the field holds up to four saturating events before a carry reaches the next channel.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCTION_SCALE: number;
+/**
+ * Bits per packed channel field.
+ * @type {number}
+ */
+export const AVBOIT_FIELD_BITS: number;
+/**
+ * Field mask.
+ * @type {number}
+ */
+export const AVBOIT_FIELD_MASK: number;
+/**
+ * How far toward the camera, in virtual slices, the draw pass samples the integral so that a surface
+ * does not occlude itself through its own linear splat. With the exclusive-prefix storage convention
+ * the analytic minimum is 1.5; the deck uses 2. Events closer together than this do not occlude each
+ * other and degrade to weighted blending.
+ * @type {number}
+ */
+export const AVBOIT_SAMPLE_BIAS_SLICES: number;
+/**
+ * Slices of dilation applied to each meshlet's depth range at the occupancy prepass, at the finest
+ * virtual resolution. The warp build dilates again by one slice at whatever resolution it settles on
+ * (plan §3.4), so this only has to be non-zero.
+ * @type {number}
+ */
+export const AVBOIT_OCCUPANCY_DILATION: number;
+/**
+ * Format of the integrated extinction texture. `rgba8unorm` matches the splat quantization and the
+ * deck; `rgba16float` doubles the memory and is the switch to flip if a long smooth gradient bands.
+ * @type {GPUTextureFormat}
+ */
+export const AVBOIT_INTEGRAL_FORMAT: GPUTextureFormat;
+/**
+ * Workgroup edge of the integration pass, one thread per voxel column.
+ * @type {number}
+ */
+export const AVBOIT_INTEGRATE_WORKGROUP_SIZE: number;
+//# sourceMappingURL=AVBOIT_CONSTANTS.d.ts.map

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AVBOIT_CONSTANTS.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,qCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;GAGG;AACH,qCAFU,MAAM,CAEqD;AAErE;;;;GAIG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;;;;GAMG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;;;GAMG;AACH,oCAFU,MAAM,CAEmC;AAEnD;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEoC;AAEpD;;;;GAIG;AACH,sCAFU,MAAM,CAE2B;AAE3C;;;GAGG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;GAGG;AACH,gCAFU,MAAM,CAE8C;AAE9D;;;;;;GAMG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;GAIG;AACH,sDAAmD;AAEnD;;;GAGG;AACH,8CAFU,MAAM,CAEiC"}

package/src/shade/renderer/rasterize/native/avboit/AVBOIT_CONSTANTS.js

@@ -0,0 +1,120 @@
+/**
+ * Tunables of the adaptive voxel-based OIT path. See `AVBOIT_PLAN_2026_09_03.md` §3 for what each one
+ * trades against; none of them is exposed on `Renderer` yet (plan §7).
+ */
+
+/**
+ * Physical depth slices of the extinction volume — what is actually allocated and integrated.
+ * The deck ships 128.
+ * @type {number}
+ */
+export const AVBOIT_PHYSICAL_SLICES = 128;
+
+/**
+ * Virtual depth slices at which occupancy is measured before adaptation. Must be a power of two
+ * multiple of {@link AVBOIT_PHYSICAL_SLICES} and a multiple of 32 (one occupancy bit per slice,
+ * packed in `u32` words). Halved until the occupied count fits the physical budget.
+ *
+ * This sets the slice floor — the finest depth separation two surfaces can have and still occlude
+ * each other — when the volume is sparse enough not to halve. The curve is pure log from
+ * `near + AVBOIT_DEPTH_CURVE_NEAR_OFFSET` (see `avboit_build_depth_curve`), so virtual slice
+ * thickness at view depth `z` is `z · ln(far / offset) / (V - 1)`. With `near = 0.1`, `far = 200` and
+ * this value: 1.6 cm at 10 m, 3.2 cm at 20 m, 8 cm at 50 m. The draw's two-slice bias means two
+ * surfaces need more than two slices between them, so 5 cm of separation resolves out to roughly
+ * 15 m. At 1024 the same numbers were four times coarser and 5 cm at 10 m already blended (ledger
+ * entry 15). The costs of going up are 128 occupancy words instead of 32, a 16 KB LUT, and a longer
+ * single-lane loop in the warp build — none of which registers.
+ * @type {number}
+ */
+export const AVBOIT_VIRTUAL_SLICES_MAX = 4096;
+
+/**
+ * Occupancy words: one bit per virtual slice.
+ * @type {number}
+ */
+export const AVBOIT_OCCUPANCY_WORDS = AVBOIT_VIRTUAL_SLICES_MAX / 32;
+
+/**
+ * The extinction volume's XY resolution is the internal resolution divided by this, rounded up. The
+ * deck uses 1/8 at every target resolution it reports.
+ * @type {number}
+ */
+export const AVBOIT_VOXEL_DOWNSCALE = 8;
+
+/**
+ * Where the depth curve starts, in world units past the camera's near plane. The curve is the
+ * engine's log slicing (`build_light_cluster_parameters`, `cluster_depth_to_z_slice`) from
+ * `near + offset` to `far`; the offset keeps the first slices from being spent on the few
+ * centimetres in front of the lens. The engine's own default for its light clusters.
+ * @type {number}
+ */
+export const AVBOIT_DEPTH_CURVE_NEAR_OFFSET = 0.2;
+
+/**
+ * Extinction that the normalized fixed-point unit `1.0` stands for. `ln 256` puts full saturation at a
+ * transmittance of `1/256`, which the integration treats as zero. The 8-bit splat unit is therefore
+ * `ln 256 / 255 ≈ 0.0217` of extinction, i.e. the finest single-event occlusion that registers in the
+ * volume is about 2.2 %.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCTION_MAX = Math.log(256);
+
+/**
+ * Transmittance below which a fragment is fully occluded as far as the volume can tell: the integral
+ * saturates at `1.0`, which is `exp(-AVBOIT_EXTINCTION_MAX) = 1/256`. The draw discards a fragment
+ * whose sampled transmittance is at or below this in every channel before shading it. What that
+ * costs in correctness is bounded: the fragment's own extinction no longer joins the total, so the
+ * background is weighted by at most `1/256` instead of something smaller — below what the 8-bit
+ * volume resolves anyway.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCT_TRANSMITTANCE = 1 / 256;
+
+/**
+ * Counts per unit of normalized extinction at the splat: values are stored 8-bit in 10-bit fields, so
+ * the field holds up to four saturating events before a carry reaches the next channel.
+ * @type {number}
+ */
+export const AVBOIT_EXTINCTION_SCALE = 255;
+
+/**
+ * Bits per packed channel field.
+ * @type {number}
+ */
+export const AVBOIT_FIELD_BITS = 10;
+
+/**
+ * Field mask.
+ * @type {number}
+ */
+export const AVBOIT_FIELD_MASK = (1 << AVBOIT_FIELD_BITS) - 1;
+
+/**
+ * How far toward the camera, in virtual slices, the draw pass samples the integral so that a surface
+ * does not occlude itself through its own linear splat. With the exclusive-prefix storage convention
+ * the analytic minimum is 1.5; the deck uses 2. Events closer together than this do not occlude each
+ * other and degrade to weighted blending.
+ * @type {number}
+ */
+export const AVBOIT_SAMPLE_BIAS_SLICES = 2.0;
+
+/**
+ * Slices of dilation applied to each meshlet's depth range at the occupancy prepass, at the finest
+ * virtual resolution. The warp build dilates again by one slice at whatever resolution it settles on
+ * (plan §3.4), so this only has to be non-zero.
+ * @type {number}
+ */
+export const AVBOIT_OCCUPANCY_DILATION = 1;
+
+/**
+ * Format of the integrated extinction texture. `rgba8unorm` matches the splat quantization and the
+ * deck; `rgba16float` doubles the memory and is the switch to flip if a long smooth gradient bands.
+ * @type {GPUTextureFormat}
+ */
+export const AVBOIT_INTEGRAL_FORMAT = "rgba8unorm";
+
+/**
+ * Workgroup edge of the integration pass, one thread per voxel column.
+ * @type {number}
+ */
+export const AVBOIT_INTEGRATE_WORKGROUP_SIZE = 8;