Add cluster acceleration structure API

[skallweitNV]

Summary

Adds cluster acceleration structure support to SGL and its Python bindings.

The API exposes the host-side controls needed to query allocation requirements and execute cluster operations, while keeping GPU-consumed data structures out of the public C++ and Python bindings.

Changes

• Add cluster operation enums, parameters, descriptors, and size results.
• Add Device.get_cluster_operation_sizes().
• Add CommandEncoder.execute_cluster_operation().
• Add RayTracingPipelineFlags.enable_clusters.
• Expose the value of AccelerationStructureHandle and allow constructing one from a raw handle.
• Add slangpy.gpu_structs with NumPy structured dtypes for portable GPU buffer records:
  • indirect draw, indexed draw, and dispatch arguments
  • AABBs
  • opacity micromap triangle descriptors
  • cluster triangle, template instantiation, and cluster arguments
• Add checked packing for the bitfields in TriangleClusterArgs.
• Keep GPU-only record types such as TriangleClusterArgs, InstantiateTemplateArgs, and ClusterArgs out of the SGL C++ types and nanobind API.
• Keep host allocation-contract constants in the main API while placing GPU-record flags and formats in slangpy.gpu_structs.
• Update the opacity micromap test to use the shared GPU-structure dtype.

Testing

• Added size-query and descriptor-conversion coverage.
• Added end-to-end CLAS → BLAS → TLAS construction and ray-tracing coverage.
• Verified supported paths on D3D12, Vulkan, and CUDA.
• Debug build completed successfully.
• Focused cluster, GPU-structure dtype, and opacity micromap tests passed.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds portable GPU record layouts, cluster acceleration structure operation APIs, Python bindings, and device tests covering CLAS, BLAS, TLAS, and ray tracing.

Changes

Cluster acceleration structure support

Layer / File(s)	Summary
GPU record layouts and packing slangpy/gpu_structs.py, slangpy/__init__.py, slangpy/tests/device/test_opacity_micromap.py	Adds exported NumPy GPU record dtypes, cluster encoding constants, unsigned-field validation, and triangle-cluster bitfield packing. The opacity micromap test uses the shared descriptor dtype.
Native cluster operation API src/sgl/device/raytracing.h, src/sgl/device/raytracing.cpp, src/sgl/device/device.h, src/sgl/device/device.cpp, src/sgl/device/command.h, src/sgl/device/command.cpp, src/sgl/device/types.h	Adds cluster operation enums, parameter records, descriptors, size queries, command execution, RHI conversion, constants, and the enable_clusters ray-tracing pipeline flag.
Python API exposure src/slangpy_ext/device/raytracing.cpp, src/slangpy_ext/device/command.cpp, src/slangpy_ext/device/device.cpp, src/slangpy_ext/py_doc.h, tools/postprocess_stub.py	Exposes cluster operation types, enums, constants, size queries, command execution, descriptor conversions, generated documentation, and descriptor TypedDict/Union processing.
Cluster operation validation slangpy/tests/device/test_cluster_acceleration_structure.py, slangpy/tests/device/test_cluster_acceleration_structure.slang	Adds tests for argument-record layouts, explicit CLAS destinations, cluster-enabled acceleration structure construction, and ray tracing through the resulting TLAS.

Merge Risk: 🔵 Low · up to d26bf

The implementation appears sound, but the new trace test may fail the configured Ruff check until it is split into smaller helpers.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 15 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding cluster acceleration structure API support.
Description check	✅ Passed	The description directly covers the cluster acceleration structure API, Python bindings, GPU structure dtypes, and testing changes in the pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 9.52% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 15 files. (2 skipped: 1 unsupported, 1 too large.)

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 766d550d-ef9c-466d-851c-ad04e367862b

📥 Commits

Reviewing files that changed from the base of the PR and between 19625ad and d26bf46.

📒 Files selected for processing (17)

• slangpy/__init__.py
• slangpy/gpu_structs.py
• slangpy/tests/device/test_cluster_acceleration_structure.py
• slangpy/tests/device/test_cluster_acceleration_structure.slang
• slangpy/tests/device/test_opacity_micromap.py
• src/sgl/device/command.cpp
• src/sgl/device/command.h
• src/sgl/device/device.cpp
• src/sgl/device/device.h
• src/sgl/device/raytracing.cpp
• src/sgl/device/raytracing.h
• src/sgl/device/types.h
• src/slangpy_ext/device/command.cpp
• src/slangpy_ext/device/device.cpp
• src/slangpy_ext/device/raytracing.cpp
• src/slangpy_ext/py_doc.h
• tools/postprocess_stub.py

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

[coderabbitai]

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep test_cluster_acceleration_structure_trace below Ruff’s PLR0915 limit. The checked-in .coderabbit.yaml enables Ruff, and PLR0915 uses a 50-statement default limit. This 60-statement test can fail that check. Extract the CLAS build, BLAS build, and TLAS/trace setup into module-level helpers, similar to _execute_implicit_cluster_operation.

🧰 Tools

🪛 Ruff (0.16.3)

[warning] 211-211: Too many statements (60 > 50)

(PLR0915)