rdc-cli 0.5.4__tar.gz → 0.5.5__tar.gz

{rdc_cli-0.5.4 → rdc_cli-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdc-cli
-Version: 0.5.4
+Version: 0.5.5
 Summary: CLI for RenderDoc .rdc captures
 Author: Jim
 License-Expression: MIT

{rdc_cli-0.5.4 → rdc_cli-0.5.5}/docs-astro/src/data/commands.json

@@ -201,6 +201,12 @@
           "help": "Export buffer raw data.",
           "usage": "rdc buffer <ID> [-o PATH] [--raw]"
         },
+        {
+          "name": "cbuffer",
+          "id": "cbuffer",
+          "help": "Decode a constant buffer to JSON or export its raw bytes.",
+          "usage": "rdc cbuffer [EID] [--stage CHOICE] [--set INTEGER] [--binding INTEGER] [--json] [--raw] [-o PATH]"
+        },
         {
           "name": "rt",
           "id": "rt",

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/proposal.md

@@ -0,0 +1,90 @@
+# Fix #225: D3D12 Multi-GPU Capture Replay
+
+## Summary
+
+Fix `_match_capture_gpu()` incorrectly returning the integrated GPU on multi-GPU
+systems when replaying D3D12 captures, causing an `E_INVALIDARG` heap failure on
+devices with insufficient VRAM.
+
+## Motivation
+
+`_match_capture_gpu()` only matches GPUs via the Vulkan `vkEnumeratePhysicalDevices`
+structured-data chunk. For D3D12 captures that chunk is absent, so the function
+falls through to `return gpus[0]`. On reporter's machine the GPU enumeration order
+was: AMD Radeon Graphics iGPU 2 GB, NVIDIA RTX 4500 Ada 24 GB, WARP. The iGPU was
+selected, D3D12 heap creation required more VRAM than available, and renderdoc
+returned `E_INVALIDARG`.
+
+The same fall-through also affects the remote-replay call site at line 368, which
+additionally never passes `sd` to the helper, so even the Vulkan path was silently
+bypassed on every remote replay.
+
+## Design
+
+### 1. D3D12 structured-data matching
+
+Walk the capture's structured data looking for chunks whose name contains
+`DriverInit`, `EnumAdapters`, or `CreateDXGIFactory`. Inside each matching chunk
+descend into child objects to find a child named `AdapterDesc` and within it a
+string field named `Description` or `DeviceName`. Perform a case-insensitive
+substring match of that string against `gpu.name`. Return the first GPU that
+matches.
+
+### 2. Vendor-preference fallback
+
+When no structured-data chunk produces a match, filter out Software/WARP adapters
+(`renderdoc.GPUVendor.Software`), then rank remaining GPUs by vendor:
+nVidia > AMD > Intel. Return the highest-ranked GPU, or the first non-Software GPU
+if no ranked match exists.
+
+### 3. Single-GPU short-circuit
+
+If `len(gpus) == 1` return that GPU immediately without inspecting structured data.
+
+### 4. Signature and call-site corrections
+
+Pass `rd` (the renderdoc module) into `_match_capture_gpu()` so that
+`GPUVendor` enum values are accessible without a module-level import assumption.
+Update the remote-replay call site (line 368) to pass `sd` in addition to `rd`,
+matching the local-replay call site.
+
+## Spec Delta
+
+A new scenario "Multi-GPU capture replay" should be appended under the existing
+**Requirement: Replay lifecycle** section in `openspec/specs/daemon/spec.md`:
+
+```
+#### Scenario: Multi-GPU capture replay
+- WHEN the capture was taken on a multi-GPU system
+- AND multiple GPUs are available for replay
+- THEN the daemon selects the GPU whose name matches structured-data adapter
+  metadata extracted from the capture
+- AND if no structured-data match exists, Software/WARP adapters are excluded
+  and the highest-ranked discrete GPU is preferred (nVidia > AMD > Intel)
+- AND a single available GPU is always returned directly without inspection
+```
+
+This proposal targets that scenario. The spec file itself is not modified here;
+the delta is applied in the implementing task (see `tasks.md`).
+
+## Files Changed
+
+- `src/rdc/daemon_server.py` — `_match_capture_gpu` body; call sites at lines 223
+  and 368
+- `tests/unit/test_daemon_server_unit.py` — new unit tests (see `test-plan.md`)
+
+## Risks
+
+- The exact D3D12 chunk name (`DriverInit` / `EnumAdapters` / `CreateDXGIFactory`)
+  has not been confirmed against a real renderdoc 1.42 D3D12 capture. The matching
+  uses substring search rather than exact equality as a defensive measure; a real
+  capture should be obtained from the issue reporter for verification before merge.
+- `renderdoc.GPUVendor.nVidia` uses a lower-case `n`. Attribute access should use
+  `getattr(rd.GPUVendor, "nVidia", 4)` with an integer fallback to avoid
+  `AttributeError` on builds where the spelling differs.
+- The Vulkan low-VRAM edge case (structured-data match returns a GPU that has less
+  VRAM than required) is not addressed here; the fix only corrects selection
+  behaviour and does not validate VRAM sufficiency.
+- Integration testing on Linux is not possible without Windows D3D12 multi-GPU
+  hardware. The unit tests use mocks. Full verification must be performed by the
+  issue reporter on their machine.

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/tasks.md

@@ -0,0 +1,10 @@
+# Fix #225: Tasks
+
+- [ ] `daemon_server.py`: add D3D12 structured-data matching to `_match_capture_gpu` (walk `DriverInit`/`EnumAdapters`/`CreateDXGIFactory` chunks, match `AdapterDesc.Description`/`DeviceName` against `gpu.name`)
+- [ ] `daemon_server.py`: add vendor-preference fallback (drop Software/WARP, prefer nVidia > AMD > Intel via `getattr` on `rd.GPUVendor`)
+- [ ] `daemon_server.py`: add single-GPU short-circuit at top of `_match_capture_gpu`
+- [ ] `daemon_server.py`: add `rd` parameter to `_match_capture_gpu` signature; update both call sites (lines 223 and 368)
+- [ ] `daemon_server.py`: pass `sd` at the remote-replay call site (line 368)
+- [ ] `openspec/specs/daemon/spec.md`: append "Multi-GPU capture replay" scenario under **Requirement: Replay lifecycle**
+- [ ] `tests/unit/test_daemon_server_unit.py`: implement all 8 unit test cases from `test-plan.md`
+- [ ] `pixi run lint && pixi run test` passes

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/test-plan.md

@@ -0,0 +1,33 @@
+# Fix #225: Test Plan
+
+## Unit tests — `tests/unit/test_daemon_server_unit.py`
+
+- [ ] `test_single_gpu_returns_it` — given `len(gpus) == 1` with any `sd` value
+  (including `None`), assert that GPU is returned without inspecting structured data
+
+- [ ] `test_vulkan_match_by_devicename` — regression guard for the existing Vulkan
+  path; mock structured data containing a `vkEnumeratePhysicalDevices` chunk with a
+  `DeviceName` field matching one of two GPU names; assert the matching GPU is
+  returned
+
+- [ ] `test_d3d12_match_via_driverinit_adapterdesc` — mock structured data with a
+  `DriverInit` chunk whose `AdapterDesc` child has a `Description` field matching
+  one GPU among three (iGPU, discrete, WARP); assert the discrete GPU is returned
+
+- [ ] `test_d3d12_fallback_skips_warp_prefers_nvidia` — no structured-data match;
+  three GPUs with vendors Software (WARP), AMD (iGPU), nVidia (discrete); assert
+  the nVidia GPU is returned
+
+- [ ] `test_d3d12_fallback_amd_over_intel` — no structured-data match; vendors
+  [Intel, AMD, Software]; assert the AMD GPU is returned
+
+- [ ] `test_no_structured_data_uses_fallback_not_gpu0` — `sd=None`; two GPUs in
+  order [AMD iGPU, NVIDIA discrete]; assert NVIDIA is returned, reproducing the
+  literal issue #225 scenario (iGPU was previously returned as `gpus[0]`)
+
+- [ ] `test_empty_gpu_list_returns_none` — `gpus=[]`; assert return value is `None`
+  (no exception raised)
+
+- [ ] `test_remote_replay_passes_sd` — mock the `_match_capture_gpu` call site at
+  the remote-replay path (line 368); assert it is invoked with a non-`None` `sd`
+  argument when structured data is available

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/proposal.md

@@ -0,0 +1,95 @@
+# OpenSpec: issue-224-cbuffer-export
+
+## Summary
+
+Expose `rdc cbuffer` as a first-class CLI command with decoded JSON output and optional
+raw binary export (`--raw`).
+
+## Context and Motivation
+
+OpenSpec phase2-buffer-decode (archived 2026-02-19) originally planned three CLI commands:
+`rdc cbuffer`, `rdc vbuffer`, and `rdc ibuffer`. The daemon handler `cbuffer_decode` and its
+VFS route shipped in that phase. The CLI half — `rdc cbuffer` — was never implemented.
+This change completes that unshipped work.
+
+GitHub issue #224 (part 2) tracks the gap. Users who rely on `rdc buffer --raw` for raw bytes
+have no ergonomic path to decoded constant-buffer variables without constructing VFS paths
+manually.
+
+**Scope note:** The archived phase2-buffer-decode plan envisioned `rdc cbuffer` as a thin VFS
+`cat` wrapper; this change implements a richer direct command with decoded JSON output, a new
+`cbuffer_raw` handler, and a new VFS `leaf_bin` route — reviewers should not expect a pure VFS
+wrapper.
+
+## Design
+
+### New command: `rdc cbuffer`
+
+```
+rdc cbuffer [EID] --stage [vs|hs|ds|gs|ps|cs] --set N --binding N [--json] [--raw -o file.bin]
+```
+
+- `EID`: optional; resolved via `complete_eid` if omitted (matches existing `rdc buffer` pattern).
+- `--stage`: default `ps`.
+- `--set`: default `0`.
+- `--binding`: default `0`.
+- `--json`: emit decoded variables as JSON (default output mode).
+- `--raw -o file.bin`: export the raw constant-buffer bytes to a file.
+
+### Decoded path
+
+Calls the existing `cbuffer_decode` daemon handler unchanged.  Returns
+`{"eid", "set", "binding", "variables": [{name, type, value}, ...]}` and writes it via
+`write_json`.  No daemon changes required for this path.
+
+### Raw path
+
+Adds a new `cbuffer_raw` daemon handler in `handlers/buffer.py`.  The handler repeats the
+reflection lookup (`fixedBindSetOrSpace` / `fixedBindNumber`), obtains
+`GetConstantBlock(...).descriptor`, calls `controller.GetBufferData(resource, byteOffset,
+byteSize)`, writes the bytes to `state.temp_dir/cbuffer_<eid>_<set>_<binding>.bin`, and
+returns `{"path", "size"}`.
+
+The handler is exposed as a VFS `leaf_bin` route at
+`/draws/<eid>/cbuffer/<set>/<binding>/data` in `vfs/router.py`, mirroring the way `buf_raw`
+is wired at `/buffers/<id>/data`.  The CLI calls
+`_export_vfs_path(f"/draws/{eid}/cbuffer/{set}/{binding}/data", output, raw)` (from
+`commands/export.py`), which follows the same `vfs_ls` + `resolve_path` → `_deliver_binary`
+flow used by `rdc buffer --raw`.  `_deliver_binary` (vfs.py:216) is the final delivery
+step — it calls `call(match.handler, match.args)` through the VFS resolve layer; it is NOT
+a standalone "call handler, get path, write bytes" helper invoked directly.
+
+The `hasattr(pipe_state, "GetConstantBlock")` guard present in `cbuffer_decode` is preserved
+in `cbuffer_raw` for RenderDoc version drift safety.
+
+### New source file
+
+`src/rdc/commands/cbuffer.py` — registered in `src/rdc/cli.py` adjacent to `buffer_cmd`
+(~line 138).
+
+## Risks
+
+### Non-buffer-backed constant buffers
+
+`ConstantBlock.bufferBacked == False` for push constants (Vulkan) and D3D12 root constants.
+These have no backing buffer resource; `GetBufferData` would operate on a null resource.
+
+Defined behavior: `--raw` MUST return a JSON-RPC error with a descriptive message
+(e.g. `"cbuffer is not buffer-backed (push constant or root constant)"`) rather than crash
+or silently return zero bytes.  Decoded `--json` output is unaffected and continues to work
+via `GetCBufferVariableContents`.
+
+### D3D12 root constants / register spaces
+
+The `fixedBindSetOrSpace` / `fixedBindNumber` mapping for D3D12 root constants cannot be
+verified on this Linux development machine.  The Vulkan (vkcube) integration test exercises
+the buffer-backed path only.  Behavior on D3D12 root-constant captures is verified by
+reporter @Misaka-Mikoto-Tech on real D3D12 hardware after the PR ships.
+
+### `_extract_value` type coverage (optional improvement)
+
+The existing `_extract_value` helper (`buffer.py:163-173`) handles only `f32v` members;
+integer and unsigned-integer shader variables degrade silently.  `_flatten_shader_var`
+in `handlers/_helpers.py` already handles `u32v`/`s32v` and is used by `shader_constants`.
+Switching `cbuffer_decode` to use `_flatten_shader_var` is an optional polish step; it does
+not block this change but is tracked as a separate optional task.

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/specs/daemon/spec.md

@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Constant Buffer Raw Export
+The daemon SHALL expose a handler to export raw constant-buffer bytes to a temporary file.
+
+#### Scenario: Export buffer-backed constant buffer
+- **WHEN** client requests `cbuffer_raw` with `eid`, `set`, `binding`, and `stage`
+- **THEN** daemon resolves the constant block via `fixedBindSetOrSpace` / `fixedBindNumber`,
+  calls `GetBufferData(resource, byteOffset, byteSize)`, writes bytes to
+  `state.temp_dir/cbuffer_<eid>_<set>_<binding>.bin`, and returns `{"path", "size"}`.
+- **IF** `state.adapter` is None, return error -32002.
+- **IF** `eid` is not a valid draw event, return error.
+
+#### Scenario: Reject non-buffer-backed constant buffer
+- **WHEN** client requests `cbuffer_raw` and `ConstantBlock.bufferBacked == False`
+- **THEN** daemon returns a JSON-RPC error with a message indicating the cbuffer is not
+  buffer-backed (push constant or root constant) and does not write any file.
+
+#### Scenario: RenderDoc version guard
+- **WHEN** `GetConstantBlock` is not present on the pipeline state object
+- **THEN** daemon returns an error indicating the API is unavailable on this RenderDoc version.
+
+### Requirement: Constant Buffer CLI Command
+The CLI SHALL expose `rdc cbuffer` as a first-class command for decoded and raw export.
+
+#### Scenario: Decoded JSON output
+- **WHEN** user runs `rdc cbuffer [EID] --stage STAGE --set N --binding N`
+- **THEN** CLI calls `cbuffer_decode` handler and writes the JSON response to stdout.
+- **IF** `EID` is omitted, CLI resolves it via `complete_eid`.
+
+#### Scenario: Raw binary export
+- **WHEN** user runs `rdc cbuffer [EID] --raw -o FILE`
+- **THEN** CLI resolves the VFS path `/draws/<eid>/cbuffer/<set>/<binding>/data` via
+  `_export_vfs_path` (vfs_ls + resolve_path → _deliver_binary), exactly mirroring how
+  `rdc buffer --raw` uses `/buffers/<id>/data`, and writes bytes to `FILE`.
+- **IF** `-o` is not specified alongside `--raw`, CLI exits with a usage error.
+
+#### Scenario: No active session
+- **WHEN** user runs `rdc cbuffer` and no daemon session is active
+- **THEN** CLI exits with code 1 and prints an error message to stderr.

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/tasks.md

@@ -0,0 +1,47 @@
+# Tasks: issue-224-cbuffer-export
+
+## Phase A: Mock API additions
+
+- [ ] Add `GetBufferData` stub to `mock_renderdoc.py` (anchor: ~line 1356 `GetConstantBlock`).
+  The happy-path test must give the mock `Descriptor` (returned via
+  `GetConstantBlock(...).descriptor`) a non-null `resource`, `byteOffset`, and `byteSize` —
+  these are the fields the raw-path handler keys off (`buffer.py:143-147`).
+- [ ] Add `bufferBacked=False` variant to the mock `ConstantBlock` for the push-constant
+  clean-error test; this stubs the reflection-level field used to reject non-buffer-backed
+  cbuffers before `GetBufferData` is called.
+
+## Phase B: `cbuffer_raw` daemon handler (tests first)
+
+- [ ] Extend `tests/unit/test_buffer_decode.py` with `cbuffer_raw` cases (happy path,
+  `bufferBacked=False` error, no-adapter guard)
+- [ ] Implement `cbuffer_raw` handler in `src/rdc/handlers/buffer.py` (~line 370,
+  adjacent to `HANDLERS` dict)
+- [ ] Register `cbuffer_raw` in `HANDLERS`
+- [ ] Add VFS `leaf_bin` route for `/draws/<eid>/cbuffer/<set>/<binding>/data` →
+  `cbuffer_raw` in `src/rdc/vfs/router.py`, mirroring
+  `/buffers/<id>/data` → `buf_raw` (router.py:184)
+- [ ] Verify handler unit tests pass
+
+## Phase C: `rdc cbuffer` CLI command (tests first)
+
+- [ ] Write `tests/unit/test_cbuffer_commands.py` (JSON mode, `--raw -o`, no-session error,
+  `complete_eid` fallback, `--raw` without `-o` usage error)
+- [ ] Implement `src/rdc/commands/cbuffer.py`; raw path calls
+  `_export_vfs_path(f"/draws/{eid}/cbuffer/{set}/{binding}/data", output, raw)` from
+  `commands/export.py` — no direct handler dispatch
+- [ ] Register `cbuffer_cmd` in `src/rdc/cli.py` (~line 138, adjacent to `buffer_cmd`)
+- [ ] Verify CLI unit tests pass
+
+## Phase D: Integration + verification
+
+- [ ] Extend `tests/integration/test_daemon_handlers_real.py` with `@pytest.mark.gpu`
+  tests for `cbuffer_raw` (Vulkan vkcube capture)
+- [ ] Run `pixi run lint && pixi run test` — all pass, coverage ≥ 80% for new paths
+- [ ] Run GPU integration tests against real capture — pass
+- [ ] Code review
+
+## Phase E: Optional polish (non-blocking)
+
+- [ ] Switch `cbuffer_decode` to use `_flatten_shader_var` from `handlers/_helpers.py`
+  instead of `_extract_value` to fix int/uint member degradation
+- [ ] Extend `test_buffer_decode.py` with int/uint value assertions

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/test-plan.md

@@ -0,0 +1,78 @@
+# Test Plan: issue-224-cbuffer-export
+
+## Scope
+
+### In scope
+- New daemon handler `cbuffer_raw` (unit + integration)
+- New CLI command `rdc cbuffer` (unit: JSON mode, raw mode, error paths)
+- `bufferBacked == False` error path for `cbuffer_raw`
+- Optional: `_extract_value` int/uint coverage in `test_buffer_decode.py`
+
+### Out of scope
+- Existing `cbuffer_decode` handler correctness (covered by prior test suite)
+- `rdc vbuffer` / `rdc ibuffer` (separate issue)
+- D3D12 root-constant register-space mapping (cannot run on this Linux box; deferred to reporter verification)
+
+## Test Matrix
+
+| Layer | Test Type | File |
+|-------|-----------|------|
+| Unit | `cbuffer_raw` handler (mock) | `tests/unit/test_buffer_decode.py` (extend) |
+| Unit | `rdc cbuffer` CLI command | `tests/unit/test_cbuffer_commands.py` (new) |
+| Integration | real capture decoded + raw | `tests/integration/test_daemon_handlers_real.py` (extend) |
+
+## Cases
+
+### `cbuffer_raw` handler (extend `test_buffer_decode.py`)
+
+- **Happy path**: mock `GetConstantBlock` returns a buffer-backed descriptor (`bufferBacked=True`,
+  known `byteOffset`/`byteSize`); mock `GetBufferData` returns 16 known bytes.
+  Assert response contains `{"path": "...", "size": 16}` and the temp file exists with the
+  expected bytes.
+- **bufferBacked=False**: mock `GetConstantBlock` returns `bufferBacked=False`.
+  Assert the handler returns a JSON-RPC error (code -32602 or equivalent) with a message
+  containing `"not buffer-backed"`.  Assert no temp file is created.
+- **No adapter**: `state.adapter is None` → assert error -32002 (standard no-adapter guard).
+- **Missing eid**: invalid `eid` → assert error from `SetFrameEvent`.
+
+Mock anchor: `mock_renderdoc.py` `GetConstantBlock` (~line 1356), `GetBufferData`.
+
+### `rdc cbuffer` CLI command (new `test_cbuffer_commands.py`)
+
+Mirror structure of `tests/unit/test_mesh_commands.py` (monkeypatch `rdc.commands.cbuffer.call`).
+
+- **JSON mode (default)**: monkeypatch `call("cbuffer_decode", ...)` returns
+  `{"eid": 10, "set": 0, "binding": 0, "variables": [{"name": "mvp", "type": "mat4", "value": [...]}]}`.
+  Invoke `rdc cbuffer 10 --stage ps --set 0 --binding 0`.
+  Assert exit code 0, stdout is valid JSON matching the payload.
+- **`--json` explicit flag**: same as above with `--json` flag; assert identical output.
+- **`--raw -o file.bin`**: monkeypatch `call("cbuffer_raw", ...)` returns `{"path": "/tmp/cbuffer_10_0_0.bin", "size": 16}`;
+  monkeypatch binary delivery (`_deliver_binary` / `fetch_remote_file`).
+  Assert exit code 0, output file contains the expected bytes.
+- **No session**: `call` raises connection error → assert exit code 1, message on stderr.
+- **`--raw` without `-o`**: assert exit code non-zero with usage error on stderr.
+- **EID omitted**: monkeypatch `complete_eid` returns `42`; assert the handler is called with `eid=42`.
+
+### Integration (`test_daemon_handlers_real.py`, `@pytest.mark.gpu`)
+
+Extend analogous to `test_cbuffer_decode_returns_data` (~line 1965), using a vkcube/Vulkan
+capture with a known draw EID that has a buffer-backed cbuffer.
+
+- **`cbuffer_raw` returns file**: call `cbuffer_raw` with valid `eid`/`set`/`binding`.
+  Assert response contains `path` and `size > 0`; assert temp file exists and `size` matches
+  `os.path.getsize(path)`.
+- **`cbuffer_decode` + `cbuffer_raw` size agreement**: decoded `variables` total byte footprint
+  is consistent with the raw `size`.
+
+## Assertions (all tests)
+
+- Exit code 0 on success, non-zero on error.
+- JSON output: valid JSON, `variables` array present for decoded mode.
+- Raw output: file written at `-o` path, byte count matches `size` from handler.
+- Error messages go to stderr; stdout is empty on error.
+- `bufferBacked=False` produces an error message containing `"not buffer-backed"` (case-insensitive).
+
+## Coverage Gate
+
+CI enforces ≥ 80% line coverage for `src/rdc/commands/cbuffer.py` and the new
+`cbuffer_raw` code path in `src/rdc/handlers/buffer.py`.

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-vsin-mesh/proposal.md

@@ -0,0 +1,95 @@
+# OpenSpec: issue-224-vsin-mesh
+
+## Summary
+
+Expose vertex shader input (VS-In) mesh geometry through the existing `rdc mesh` CLI command
+and the underlying daemon mesh handler.
+
+## Motivation
+
+The `rdc mesh` command currently supports `--stage vs-out` and `--stage gs-out` but not
+`--stage vs-in`. VS-In corresponds to `MeshDataStage.VSIn = 0` in the RenderDoc API and
+represents the raw per-vertex data fed to the Input Assembler — the most common geometry
+inspection target for artists and tools debugging vertex attribute issues.
+
+This change completes part of the unshipped geometry export plan from archived
+`openspec/changes/archive/2026-02-19-phase2-buffer-decode`.
+
+**Premise correction (adversarial review, 2026-05-15).** An earlier draft of this
+proposal asserted that `_handle_mesh_data` and the OBJ-export path were "already generic;
+only the stage map and the CLI option list need extending" and that "no changes needed
+below the map". **That premise is RETRACTED.** Cross-checking against RenderDoc's official
+`decode_mesh.py` reference revealed three correctness defects that are masked for
+`vs-out`/`gs-out` (where `baseVertex == 0` and the position attribute is element 0) but
+break `vs-in`:
+
+1. `mesh.baseVertex` was never applied to decoded indices. RenderDoc's reference adds
+   `mesh.baseVertex` to every index. For base-vertex `vs-in` draws the decoded mesh was
+   wrong; for `vs-out`/`gs-out` it is a no-op (`baseVertex == 0`).
+2. The position was read at `i*stride` (start of the interleaved vertex) instead of
+   `i*stride + mesh.vertexByteOffset`, so `vs-in` positions were wrong whenever POSITION
+   is not the first element of the vertex.
+3. Index-buffer width is honored from `mesh.indexByteStride` (16-bit vs 32-bit), matching
+   the reference; this is now covered by explicit regression tests.
+
+The fix applies `baseVertex` and `vertexByteOffset` uniformly (not stage-special-cased),
+exactly as the reference does, with a regression test asserting `vs-out` behavior is
+unchanged.
+
+## Design
+
+### Daemon layer
+
+`_MESH_STAGE_MAP` in `buffer.py` maps CLI stage strings to `MeshDataStage` integer values.
+Add `"vs-in": 0` alongside the existing `"vs-out": 1` and `"gs-out": 2` entries.
+
+The decode path calls `GetPostVSData(instance, view, stage_int)` and decodes the returned
+`MeshFormat`. The decoder is corrected to match RenderDoc's `decode_mesh.py` reference:
+indices are offset by `mesh.baseVertex`, the position attribute is read at
+`i*stride + mesh.vertexByteOffset`, and the index width follows `mesh.indexByteStride`.
+These corrections are applied uniformly across all stages (no stage special-casing); they
+are no-ops for `vs-out`/`gs-out` where `baseVertex == 0` and the position is element 0.
+
+The error string at the invalid-stage guard (~buffer.py:283) currently reads
+`"invalid stage <name>; use vs-out or gs-out"`. This change must update that string to
+include `vs-in` so callers see a consistent list of valid values.
+
+### CLI layer
+
+The `--stage` Click `Choice` in `mesh_cmd` (`mesh.py`) hardcodes `["vs-out", "gs-out"]`.
+Add `"vs-in"` as a valid choice. No other CLI logic changes.
+
+## Risks and Limitations
+
+- **Non-draw events**: `GetPostVSData(VSIn)` returns an empty `MeshFormat` (zero
+  `vertexResourceId` / `vertexByteStride`) for compute or non-draw events. The existing
+  guard at ~buffer.py:293 returns JSON-RPC error `-32001` `"no PostVS data at this event"`
+  in this case — identical to the contract `vs-out` and `gs-out` already have. No
+  silent-empty path exists; behavior is consistent across all three stages.
+
+### What vs-in supports
+
+- **Position geometry**: the single position attribute described by `mesh.format`,
+  located at `mesh.vertexByteOffset` within the interleaved vertex stride. Decoded
+  positions are `vertexByteOffset`-correct.
+- **Triangle connectivity**: `TriangleList` / `TriangleStrip` / `TriangleFan`, with
+  indices that are `baseVertex`-correct (RenderDoc `decode_mesh` parity).
+
+### Known limitations (vs-in)
+
+- **Only the position attribute is exported**, not full per-attribute IA. Other vertex
+  attributes (normals, UVs, colors) are not decoded. The lower-level fallback
+  (`GetVertexInputs` / `GetVBuffers` / `GetIBuffer`) for full per-attribute IA decoding is
+  explicitly out of scope for this change.
+- **Packed / non-float position formats are unsupported**: the decoder only handles
+  1/2/4-byte float-style components; packed formats (e.g. `R10G10B10A2`, SNORM/UNORM
+  integer-packed) are not decoded.
+- **Non-triangle topology exports vertices only**: `LineList`, `PointList`, patch and
+  adjacency topologies produce no OBJ faces. Rather than silently emitting an empty/
+  face-less OBJ, the CLI now prints a clear stderr warning naming the topology
+  (e.g. `mesh: topology 'PatchList_3' has no OBJ face mapping; exported N vertices,
+  0 faces`) so geometry loss is never silent.
+
+- **D3D12 on Linux**: This development box runs Linux; D3D12 captures cannot be exercised
+  locally. Verification follows the established model: ship the change, reporter
+  (@Misaka-Mikoto-Tech) verifies against real D3D12 captures (same approach as PR #226).

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-vsin-mesh/specs/daemon/spec.md

@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: VS-In Mesh Stage Support
+The daemon SHALL accept `vs-in` as a valid mesh stage identifier in addition to the
+existing `vs-out` and `gs-out` stages.
+
+#### Scenario: VS-In Stage Accepted
+- **WHEN** client requests `mesh_data` with `stage` equal to `"vs-in"`
+- **THEN** daemon calls `GetPostVSData` with stage integer `0` (`MeshDataStage.VSIn`)
+- **THEN** daemon decodes the returned `MeshFormat` using the existing geometry decode path
+- **THEN** daemon returns vertex positions (and any available attributes) in OBJ format
+
+#### Scenario: VS-In on Non-Draw Event
+- **WHEN** client requests `mesh_data` with `stage` equal to `"vs-in"` for a non-draw event
+  (or any event where the IA/VSIn stage produced no data)
+- **THEN** `GetPostVSData` returns a `MeshFormat` with zero `vertexResourceId` or zero `vertexByteStride`
+- **THEN** daemon returns JSON-RPC error `-32001` with message `"no PostVS data at this event"`
+- **NOTE** this is the same error contract `vs-out` and `gs-out` already have; no silent-empty
+  path exists
+
+#### Scenario: Invalid Stage String
+- **WHEN** client requests `mesh_data` with an unrecognized `stage` value
+- **THEN** daemon returns an error response
+- **AND** the error message SHALL list `vs-in`, `vs-out`, and `gs-out` as valid values
+- **NOTE** the error string at ~buffer.py:283 currently omits `vs-in`; this change requires
+  updating it to `"invalid stage <name>; use vs-in, vs-out or gs-out"`
+
+## MODIFIED Requirements
+
+### Requirement: Mesh CLI Stage Option
+The `rdc mesh` CLI command SHALL accept `vs-in` as a valid `--stage` argument.
+
+#### Scenario: VS-In CLI Invocation
+- **WHEN** user runs `rdc mesh <eid> --stage vs-in`
+- **THEN** CLI forwards `stage: vs-in` to the daemon `mesh_data` handler
+- **THEN** CLI writes the returned OBJ content to stdout
+
+#### Scenario: Unknown Stage Rejected at CLI
+- **WHEN** user supplies an unrecognized `--stage` value
+- **THEN** Click validation rejects the input with exit code 2 before any daemon call is made

rdc_cli-0.5.5/openspec/changes/archive/2026-05-15-issue-224-vsin-mesh/tasks.md

@@ -0,0 +1,31 @@
+# Tasks: issue-224-vsin-mesh
+
+## Phase A: Mock
+
+- [ ] Add stage int `0` entry to `GetPostVSData` mock in `tests/mocks/mock_renderdoc.py`
+      with a minimal `MeshFormat` (position attribute, Triangle topology, ≥3 vertices)
+- [ ] Verify `tests/integration/test_mock_api_sync.py` still passes after mock change
+
+## Phase B: Daemon handler
+
+- [ ] Add `"vs-in": 0` to `_MESH_STAGE_MAP` in `src/rdc/handlers/buffer.py`
+- [ ] Update the invalid-stage error string (~buffer.py:283) to include `vs-in`
+- [ ] Extend `tests/unit/test_buffer_decode.py`:
+      - happy-path test for `vs-in` stage
+      - empty-MeshFormat test for non-draw eid at stage `0`
+      - invalid-stage error message includes `vs-in`
+- [ ] Run `pixi run test tests/unit/test_buffer_decode.py` — all pass
+
+## Phase C: CLI
+
+- [ ] Add `"vs-in"` to `--stage` Click `Choice` in `src/rdc/commands/mesh.py`
+- [ ] Extend `tests/unit/test_mesh_commands.py` with `vs-in` forwarding case
+- [ ] Run `pixi run test tests/unit/test_mesh_commands.py` — all pass
+
+## Phase D: Integration + verification
+
+- [ ] Extend `tests/integration/test_daemon_handlers_real.py` with `@pytest.mark.gpu`
+      VS-In test analogous to `test_mesh_data_real`
+- [ ] Run `pixi run lint && pixi run test` — all pass, coverage ≥ 80%
+- [ ] Run GPU integration test against vkcube capture — passes
+- [ ] Code review