[Televiz] fix cross-device ProjectionLayer::submit, expose the CUDA device id

[farbod-nv]

VkContext binds CUDA to the GPU matching its Vulkan physical device — not
necessarily CUDA device 0, since Vulkan and CUDA enumerate GPUs in different
orders. Three fixes for what follows from that.

ProjectionLayer::submit now pins viz's device before touching CUDA, as
ImageLayerBase::submit already did. Without it, any app submitting from a
worker thread (session created on the main thread, frames submitted from a
render thread) died on a multi-GPU box with
cudaSignalExternalSemaphoresAsync(cuda_done_writing) failed: invalid argument.

VizSession::get_cuda_device_id() / .cuda_device_id — producers had no
way to learn which GPU to allocate on and had to guess 0. Interop is
same-device only, and a wrong guess costs a peer copy per submit (1.17 ms vs
0.05 ms for a 1080p RGBD submit, 2x RTX 6000 Ada) when it doesn't fail
outright. Config::physical_device_index is also plumbed through to move viz
instead; it's rejected, not ignored, for kXr and external_context.

Better CUDA errors (viz/core/cuda_error.hpp) — CUDA reports every
cross-device interop call as a bare "invalid argument". Failures now append two
lines naming both devices and the fix, and stay silent when the devices agree.
Wired through every CUDA failure site in device_image, image_layer_base and
projection_layer.

Tests: message content and length, the quiet case, config default, both
physical_device_index rejections, and the accessor cross-checked against the
context and cudaGetDevice. Full viz suites pass (core 201/51, session 399/44,
layers 410/42).

Found via a televiz crash on a dual-GPU workstation; the app-side workarounds in gr00t become no-ops once this ships in a wheel.

Summary by CodeRabbit

• New Features

  • Added optional Vulkan physical-device selection for sessions.
  • Exposed the CUDA device associated with each session.
  • Added Python access to both device-selection and CUDA-device information.
  • Added clearer guidance when device selection is incompatible with XR or external contexts.

• Bug Fixes

  • Improved CUDA error messages with device identifiers and actionable diagnostics.

• Tests

  • Added coverage for CUDA error reporting and session device-selection behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f605940c-88de-4fda-88f3-7f56b53abf2f

📥 Commits

Reviewing files that changed from the base of the PR and between 8d7b8eb and 98047db.

📒 Files selected for processing (10)

• src/viz/core/cpp/device_image.cpp
• src/viz/core/cpp/inc/viz/core/cuda_error.hpp
• src/viz/core_tests/cpp/CMakeLists.txt
• src/viz/core_tests/cpp/test_cuda_error.cpp
• src/viz/layers/cpp/image_layer_base.cpp
• src/viz/layers/cpp/projection_layer.cpp
• src/viz/python/session_bindings.cpp
• src/viz/session/cpp/inc/viz/session/viz_session.hpp
• src/viz/session/cpp/viz_session.cpp
• src/viz/session_tests/cpp/test_viz_session.cpp

---

📝 Walkthrough

Walkthrough

The session can select a Vulkan physical device and expose its matched CUDA device ID through C++ and Python APIs. Invalid device selection with XR or external Vulkan contexts is rejected. CUDA interop paths now use shared error formatting with device-mismatch diagnostics. Tests cover session selection, CUDA device mapping, error messages, and exception behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant VizSession
  participant VkContext
  participant ImageLayerBase
  participant CUDA_Runtime
  participant cuda_error_message

  Caller->>VizSession: create with physical_device_index
  VizSession->>VkContext: initialize selected Vulkan device
  VkContext-->>VizSession: matched CUDA device ID
  ImageLayerBase->>CUDA_Runtime: select matched device and submit CUDA work
  CUDA_Runtime-->>ImageLayerBase: operation result
  ImageLayerBase->>cuda_error_message: format failures with device context

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies both primary changes: fixing cross-device ProjectionLayer submission and exposing the CUDA device ID.
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.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fm/cuda_set_device

---

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