Refactor/path tracer modules

[Mike-Leo-Smith]

This pull request significantly updates the build and validation documentation, improves the CMake build system for reliability and reproducibility, and splits the path tracer implementation into modular translation units. The changes clarify the fallback backend requirements, enforce stricter validation, and add new focused tests for Sobol sampling and the fallback backend.

Documentation and Validation Improvements:

• Updated BUILD.md to clarify the required versions and installation steps for LLVM, Embree, X11, and libuuid for the fallback backend, and to specify the exact LuisaCompute commit pinned (next@f42f3c6e). The fallback validation baseline is now Ubuntu 24.04 LTS with LLVM 22.1.8 and Embree 4.3.0. [1] [2]
• Expanded documentation on the fallback backend validation process, including new focused tests, explicit kernel cache behavior, and detailed sample count handling. [1] [2] [3] [4]
• Added a new section describing the modular source layout of the path tracer implementation.
• Improved troubleshooting guidance, including stricter requirements for fallback backend detection and X11 header dependencies.

Build System and Fallback Backend:

• Changed the fallback backend source selection order: removed support for the external PSYCLES_LUISA_SOURCE_DIR override, now always preferring the submodule or FetchContent. The PSYCLES_FETCH_LUISA_NEXT option is now used only if the submodule is unavailable. [1] [2] [3]
• The CMake configuration now strictly fails if the fallback backend is requested but not built, ensuring no silent fallback to a core-only build.
• Disabled the unused Luisa GUI component for headless builds. [1] [2]

Path Tracer Refactoring:

• Split the monolithic src/luisa/path_tracer.cpp into multiple translation units (path_tracer_common.cpp, path_tracer_sampling.cpp, etc.) for better maintainability and modularity. [1] [2]

Testing Enhancements:

• Added new focused tests for tabulated Sobol sampling (psycles_tabulated_sobol_tests) and fallback backend validation (psycles_luisa_sobol_fallback_tests). These are now part of the validation gates and are registered as CTest targets. [1] [2]

Core Library Updates:

• Added src/sampling/tabulated_sobol.cpp to the core library build.

These changes collectively improve build reproducibility, validation rigor, and code maintainability.

[Copilot]

Pull request overview

This pull request refactors the Luisa path tracer into modular translation units, introduces a host/device tabulated-Sobol sampling implementation aligned with Blender 4.5.10 Cycles, tightens the Luisa fallback build configuration, and expands validation with focused Sobol and fallback-device tests.

Changes:

• Added a new psycles::sampling::tabulated_sobol module (header + core implementation) plus a deterministic fixture test.
• Added Luisa-side Cycles Sobol lowering (include/psycles/luisa/cycles_sampler.h) and a fallback-device bit-exact validation test, and extended the Luisa compile test to instantiate the sampler kernel.
• Refactored the Luisa path tracer into multiple private translation units and updated the CMake build + docs to enforce/describe the stricter fallback backend requirements.

Reviewed changes

Copilot reviewed 31 out of 33 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
CMakeLists.txt	Removes external Luisa source override, enforces fallback target existence when requested, disables Luisa GUI, wires new modules/tests, and splits path tracer sources into multiple TUs.
BUILD.md	Updates build prerequisites and validation baseline for the fallback backend; documents new module layout and stricter fallback expectations.
DEVELOP.md	Updates development checkpoint narrative to reflect Sobol integration, module split, and validation gates.
HANDOFF.md	Adds a detailed handoff snapshot describing verified checkpoints, pins, and follow-up work.
README.md	Updates guidance to reflect relying on the pinned LuisaCompute submodule rather than an external override.
include/psycles/contract/render.h	Extends SampleRange with total to represent whole-render AA sample count for stable sampling state across progressive chunks.
include/psycles/sampling/tabulated_sobol.h	Introduces public host-side tabulated-Sobol API/constants and sampling helpers.
src/sampling/tabulated_sobol.cpp	Implements Cycles-derived tabulated-Sobol table generation + hashing/scrambling utilities.
tests/test_tabulated_sobol.cpp	Adds a deterministic host-side fixture test (fingerprint + specific row/bit fixtures).
include/psycles/luisa/cycles_sampler.h	Adds Luisa DSL lowering of Cycles’ tabulated-Sobol sampling utilities for device execution.
tests/test_luisa_sobol_fallback.cpp	Adds fallback-device bit-exact fixture test for Sobol sampling (device-side bitcasts + metadata checks).
tests/test_luisa_compile.cpp	Extends the Luisa AST compile test to also instantiate a Sobol sampler kernel.
examples/render_luisa_demo.cpp	Updates render invocation to populate SampleRange.total.
examples/render_blender_scene.cpp	Updates render invocation to populate SampleRange.total.
src/luisa/path_tracer_internal.h	Introduces shared private declarations/types/aliases used across the new path-tracer modules.
src/luisa/path_tracer_types.h	Adds LUISA_STRUCT-backed ABI structs for host/device interop used by the modularized kernel.
src/luisa/path_tracer_common.cpp	Implements shared helpers: packing/unpacking calls, conversions, pass helpers, and diagnostics.
src/luisa/path_tracer_sampling.h / src/luisa/path_tracer_sampling.cpp	Adds pixel-filter sampling callables (box/gaussian/blackman-harris).
src/luisa/path_tracer_lighting.h / src/luisa/path_tracer_lighting.cpp	Adds lighting/MIS helpers and emissive-triangle PDF callable construction.
src/luisa/path_tracer_surfaces.h / src/luisa/path_tracer_surfaces.cpp	Adds strongly-typed surface callable signatures and construction.
src/luisa/path_tracer_shader_services.h	Adds buffer-backed ShaderServices implementation for device-side shading queries.
src/luisa/path_tracer_geometry.h / src/luisa/path_tracer_geometry.cpp	Adds transparent shadow traversal callable and material/geometry fetch logic.
src/luisa/path_tracer_environment.h / src/luisa/path_tracer_environment.cpp	Adds environment/world evaluation callables, including Nishita and environment sun paths.
src/luisa/path_tracer_scene.cpp	Adds scene/material/geometry/light compilation and GPU resource upload for the modular path tracer.
src/luisa/path_tracer_session.cpp	Adds render-session logic for Sobol upload, progressive validation, dispatch, and pass readback.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.