rdc-cli

# rdc-cli Skill

## Overview

rdc-cli is a Unix-friendly command-line interface for RenderDoc GPU captures. It provides a daemon-backed architecture using JSON-RPC over TCP, a virtual filesystem (VFS) path namespace for navigating capture internals, and composable commands designed for shell pipelines, scripting, and CI assertions.

Install: `pip install rdc-cli` (requires a local RenderDoc build with Python bindings).
Check setup: `rdc doctor`.

## Core Workflow

Follow this session lifecycle for any capture analysis task:

1. **Open** a capture:
   - Local: `rdc open path/to/capture.rdc`
   - Remote replay (Proxy): `rdc open capture.rdc --proxy host:port`
   - Split thin-client: `rdc open --connect host:port --token TOKEN`
   - Android device: `rdc open capture.rdc --android [--serial SERIAL]`
2. **Inspect** metadata: `rdc info`, `rdc stats`, `rdc events`
3. **Navigate** the VFS: `rdc ls /`, `rdc ls /textures`, `rdc cat /draws/0/pipeline/summary`
4. **Analyze** specifics: `rdc shaders`, `rdc pipeline`, `rdc resources`, `rdc bindings`
5. **Debug** shaders: `rdc debug pixel EID X Y`, `rdc debug vertex EID VTXID`, `rdc debug thread EID GX GY GZ`
6. **Export** data: `rdc texture ID -o out.png`, `rdc rt EID`, `rdc buffer ID -o buf.bin`, `rdc cbuffer EID --stage ps --binding 0`, `rdc log`
7. **Close** the session: `rdc close`

### Session Management

- Default session name: `default` (or value of `$RDC_SESSION`).
- Override per-command: `rdc --session myname open capture.rdc`.
- Check active session: `rdc status`.
- Navigate to a specific event: `rdc goto EID`.

## Output Formats

All list/table commands default to TSV (tab-separated values) with a header row, suitable for `cut`, `awk`, and `sort`.

| Flag | Format | Use Case |
|------|--------|----------|
| *(default)* | TSV with header | Human reading, shell pipelines |
| `--no-header` | TSV without header | Piping to `awk`/`cut` without stripping |
| `--json` | JSON array | Structured processing with `jq` |
| `--jsonl` | Newline-delimited JSON | Streaming processing, large datasets |
| `-q` / `--quiet` | Minimal (single column) | Extracting IDs for loops |

Example -- get all draw call EIDs as a plain list:

```bash
rdc draws -q
```

Example -- JSON pipeline with jq:

```bash
rdc events --json | jq '.[] | select(.type == "DrawIndexed")'
```

## Render Pass Analysis

### List passes (Phase 8 columns)

`rdc passes` outputs 6 columns: NAME, DRAWS, DISPATCHES, TRIANGLES, BEGIN_EID, END_EID.

```bash
rdc passes                          # TSV table
rdc passes --json                   # includes load_ops/store_ops per pass
rdc passes --deps --table           # per-pass READS/WRITES/LOAD/STORE
```

### Inspect a single pass

`rdc pass <name>` shows enriched attachments: resource name, format, dimensions, and load/store ops.

```bash
rdc pass GBuffer
rdc pass GBuffer --json
rdc pass 0                          # by 0-based index
```

### Detect dead render targets

`rdc unused-targets` finds render targets written but never consumed by visible output. Columns: ID, NAME, WRITTEN_BY, WAVE.

```bash
rdc unused-targets                  # TSV
rdc unused-targets --json           # structured
rdc unused-targets -q               # one resource ID per line (for scripting)
```

### Frame statistics

`rdc stats` outputs three sections: Per-Pass Breakdown, Top Draws by Triangle Count, and Largest Resources.

```bash
rdc stats                           # all three sections
rdc stats --json                    # includes largest_resources array
```

GL/GLES/D3D11 captures without native BeginPass/EndPass markers get synthetic pass inference automatically — no extra flags needed.

## Common Tasks

### Find all draw calls

```bash
rdc draws
rdc draws --pass "GBuffer" --json
```

### Trace a pixel

```bash
rdc debug pixel 1024 512 384            # EID first, then X Y
rdc debug pixel 1024 512 384 --json     # structured output
rdc debug pixel 1024 512 384 --trace    # full step-by-step trace
```

### Search shaders by name or source

```bash
rdc search "main"                  # regex search over shader disassembly
rdc search "Sample" --stage ps -C 2
rdc shaders --name "GBuffer*"
```

### Export render targets

```bash
rdc rt EID -o output.png
rdc rt EID --depth -o depth.png      # export the raw depth attachment
rdc texture ID -o tex.png            # export a texture by resource ID (PNG)
```

### Decode a constant buffer

```bash
rdc cbuffer EID --stage ps --binding 0           # decode to JSON
rdc cbuffer EID --stage vs --binding 0 --raw -o cbuffer.bin
```

### Browse VFS paths

```bash
rdc ls /
rdc ls /textures -l
rdc tree /draws/42/pipeline --depth 2     # pipeline state lives under /draws/<eid>/pipeline/
rdc cat /draws/42/pipeline/summary
rdc cat /events/42
```

### Inspect pipeline state at a draw call

```bash
rdc goto EID
rdc pipeline --json
rdc bindings --json
```

### Compare state before/after a pass

```bash
rdc goto 100 && rdc pipeline --json > before.json
rdc goto 200 && rdc pipeline --json > after.json
diff before.json after.json
```

## CI Assertions

rdc-cli provides assertion commands that exit non-zero on failure, designed for automated testing pipelines:

| Command | Purpose |
|---------|---------|
| `rdc assert-pixel EID X Y --expect "R G B A"` | Assert pixel RGBA (4 space-separated floats) at EID/coordinates |
| `rdc assert-clean` | Assert no validation errors in capture |
| `rdc assert-count <what> --expect N [--op CHOICE]` | Assert a capture metric (e.g. `draws`) satisfies a comparison |
| `rdc assert-state EID KEY-PATH --expect VALUE` | Assert pipeline state value at EID matches expected |
| `rdc assert-image EXPECTED ACTUAL [--threshold FLOAT]` | Compare two image files pixel-by-pixel |

Example CI script:

```bash
#!/bin/bash
set -e
rdc open test_capture.rdc
rdc assert-clean
rdc assert-count draws --expect 10 --op ge
rdc assert-pixel 1024 256 256 --expect "1.0 0.0 0.0 1.0"
rdc close
```

## Shader Edit-Replay

Modify and replay shaders with