Examples

Real-world workflow recipes for common rdc-cli tasks. Each example assumes a daemon session is running (rdc open capture.rdc).

Basic Capture Analysis

rdc open scene.rdc
rdc info                        # API, GPU, driver
rdc stats                       # per-pass breakdown
rdc draws --limit 10            # top draw calls
rdc close

Quick Metrics with count

# How many events / draws / shaders / resources / passes?
rdc count events
rdc count draws
rdc count shaders
rdc count resources
rdc count passes

Output Format Cheatsheet

# Default TSV — pipe into sort, awk, cut
rdc draws

# JSON — for jq processing
rdc draws --json

# Streaming JSONL — one object per line, good for large lists
rdc events --jsonl

# No header — cleaner for awk/cut scripts
rdc draws --no-header

# Quiet — IDs only, great for xargs loops
rdc draws -q
# → 11
14
19

# Combine: export all draw render targets
for eid in $(rdc draws -q); do
  rdc rt "$eid" -o "rt_$${eid}.png"
done

Find the Heaviest Draw Call

# TSV approach
rdc draws --sort tri_count | tail -1

# JSON approach
rdc draws --json | jq 'sort_by(.tri_count) | last'

Debug a Pixel Color

# Quick result
rdc debug pixel 142 400 300

# Full step-by-step trace
rdc debug pixel 142 400 300 --trace

# Dump variables at a specific source line
rdc debug pixel 142 400 300 --dump-at 15

CI/CD Pipeline Assertions

#!/bin/bash
set -e
rdc open test_capture.rdc

# No validation errors
rdc assert-clean

# At least 12 draw calls
rdc assert-count draws --expect 12 --op ge

# Verify pixel color at coordinates
rdc assert-pixel 142 256 256 --expect "1.0 0.0 0.0 1.0"

# Visual regression test
rdc assert-image expected.png actual.png --threshold 1.0

rdc close

Compute Shader Analysis

# Compute dispatches have a different pipeline type
rdc pipeline 8                    # → COMP_PIPE=345
rdc shader 8 cs                   # compute shader disassembly
rdc shader 8 cs --constants       # bound uniform values

# Check bindings (storage buffers, images)
rdc bindings 8                    # → cs rw Pos_var

# GPU counters for compute work
rdc counters --eid 8              # → CS invocations: 24576

Comparing Two Captures

# Overall summary
rdc diff before.rdc after.rdc

# Draw call changes
rdc diff before.rdc after.rdc --draws

# Pixel-level framebuffer diff
rdc diff before.rdc after.rdc --framebuffer

# Per-pass statistics diff
rdc diff before.rdc after.rdc --stats

Advanced Assertions

# Assert pipeline state with dot-path navigation
rdc assert-state 11 topology --expect TriangleList
rdc assert-state 11 "vs.shader" --expect "133"
rdc assert-state 11 "vs.entry" --expect "main"

# Assert counts with comparison operators
rdc assert-count draws --expect 1 --op eq        # exactly 1 draw
rdc assert-count draws --expect 100 --op ge       # at least 100 draws
rdc assert-count events --expect 6                # default: eq

# Assert no high-severity validation messages
rdc assert-clean --min-severity HIGH

# Visual regression with threshold
rdc assert-image golden.png actual.png --threshold 0.001
rdc assert-image golden.png actual.png --json     # → diff_ratio in JSON

Shader Hot-Reload

# Extract current shader
rdc shader 142 ps --source -o original.frag

# ... edit original.frag in your editor ...

# Compile the modified shader (returns shader_id)
rdc shader-build original.frag --stage ps

# Hot-swap the shader in the capture
rdc shader-replace 142 ps --with 1

# Check the visual result
rdc rt 142 -o modified.png

# Revert all changes
rdc shader-restore-all

Export Everything for Offline Analysis

# Complete snapshot: pipeline + shaders + render target
rdc snapshot 142 -o ./snapshot/

# Individual exports
rdc texture 5 -o albedo.png             # specific texture
rdc buffer 3 -o vertex_data.bin         # raw buffer data
rdc mesh 142 -o geometry.obj            # post-transform mesh

Shell Pipeline Power

# Find all draws using a specific shader
rdc shader-map | grep "HASH_PREFIX" | cut -f1

# Export all textures
for id in $(rdc resources --type texture -q); do
  rdc texture "$id" -o "tex_${id}.png"
done

# Count triangles per pass
rdc draws --json | jq 'group_by(.pass) | .[] | {pass: .[0].pass, tris: [.[].tri_count] | add}'

Capture a Frame

# Basic capture
rdc capture ./myapp -o frame.rdc

# Capture with API validation and callstacks
rdc capture ./myapp -o frame.rdc --api-validation --callstacks

# Capture specific frame number
rdc capture ./myapp -o frame.rdc --frame 100

# Capture and immediately open for analysis
rdc capture ./myapp -o frame.rdc --auto-open

# JSON output for CI pipelines
rdc capture ./myapp -o frame.rdc --json

End-to-End CI Pipeline

#!/bin/bash
set -e

# 1. Capture a frame
rdc capture ./myapp -o test.rdc --api-validation --timeout 30

# 2. Open for analysis
rdc open test.rdc

# 3. Assert no validation errors
rdc assert-clean

# 4. Assert expected draw count
rdc assert-count draws --expect 50 --op ge

# 5. Assert pixel color
rdc assert-pixel 142 256 256 --expect "1.0 0.0 0.0 1.0"

# 6. Clean up
rdc close

Target Control (Live Capture)

# Inject and get target ident
rdc capture ./myapp --trigger
# → prints ident=12345

# Attach to running target
rdc attach 12345

# Trigger a capture manually
rdc capture-trigger

# List captured frames
rdc capture-list

# Copy a capture locally
rdc capture-copy 0 snapshot.rdc

# Open and analyze
rdc open snapshot.rdc

Multi-Session A/B Comparison

# Open two captures in named sessions
rdc --session before open before.rdc
rdc --session after open after.rdc

# Compare draws side-by-side
diff <(rdc --session before draws) <(rdc --session after draws)

# Compare specific pipeline states
diff <(rdc --session before pipeline 142) <(rdc --session after pipeline 142)

# Compare shader disassembly
diff <(rdc --session before cat /draws/142/shader/ps) \
     <(rdc --session after cat /draws/142/shader/ps)

# Clean up both sessions
rdc --session before close
rdc --session after close

Render Pass Analysis

# List all render passes
rdc passes

# Inspect a specific pass
rdc pass GBuffer

# List draws in a pass
rdc draws --pass GBuffer

# Find passes with many draws
rdc passes --json | jq '.[] | select(.draw_count > 50)'

Pixel Investigation Ladder

# Step 1: Read pixel color at (400, 300)
rdc pick-pixel 142 400 300

# Step 2: Full pixel history — who modified this pixel?
rdc pixel 142 400 300

# Step 3: Debug the pixel shader that drew it
rdc debug pixel 142 400 300

# Step 4: Step-by-step shader trace
rdc debug pixel 142 400 300 --trace

# Step 5: Dump variables at a specific line
rdc debug pixel 142 400 300 --dump-at 15

Buffer Decode via VFS

# Read decoded constant buffer values
rdc cat /draws/142/cbuffer/0/0

# Read decoded vertex buffer
rdc cat /draws/142/vbuffer

# Read decoded index buffer
rdc cat /draws/142/ibuffer

# View descriptor bindings
rdc cat /draws/142/descriptors

# Export raw buffer data
rdc cat /buffers/55/data > vertex_buffer.bin

Custom Queries with rdc script

# Inline Python: count unique shader hashes
rdc script -c "
shaders = set()
for a in controller.GetRootActions():
    if a.flags & rd.ActionFlags.Drawcall:
        controller.SetFrameEvent(a.eventId, True)
        pipe = controller.GetPipelineState()
        ps = pipe.GetShader(rd.ShaderStage.Pixel)
        if int(ps):
            shaders.add(int(ps))
print(len(shaders))
"

# Run a script file
rdc script analysis.py -- --verbose

Performance Profiling

# List available GPU counters
rdc counters --list

# Profile a specific draw call
rdc counters --eid 142

# Profile with specific counter IDs
rdc counters --ids 1,2,5 --eid 142

# JSON output for analysis
rdc counters --eid 142 --json

Resource Hunting

# Find largest resources
rdc resources --sort size | tail -10

# Find all textures
rdc resources --type texture

# Search by name
rdc resources --name "albedo"

# Trace a resource's usage across the frame
rdc usage 88

# Detailed resource metadata
rdc resource 88
# Search all shaders for a pattern
rdc search "shadowMap"

# Find which draws use a shader
rdc shader-map | grep "a1b2c3"

# List unique shaders
rdc shaders

# View shader reflection data
rdc shader 142 ps --reflect

# View constant buffer values
rdc shader 142 ps --constants

Validation Error Debugging

# Check for validation errors
rdc log

# Filter by severity
rdc log --level error

# Assert no errors in CI
rdc assert-clean --min-severity error

# Check pipeline state for issues
rdc pipeline 142
rdc bindings 142

Texture Analysis

# Texture statistics (min/max values)
rdc tex-stats 142

# With histogram
rdc tex-stats 142 --histogram

# Export texture as PNG
rdc texture 88 -o albedo.png

# Export render target
rdc rt 142 -o render_target.png

# Export with debug overlay
rdc rt 142 -o wireframe.png --overlay wireframe

Working with Advanced Vulkan Features

# Tessellation: view high-poly output
rdc mesh 33                       # → 688 vertices, 358 faces
rdc counters --eid 33             # → VS invocations: 692

# Multi-draw indirect: all sub-commands expand
rdc draws                         # → 225+ DrawIndexedIndirect sub-commands
rdc pipeline 28                   # → gfx_pipe=2818, TriangleList

# Dynamic rendering (Vulkan 1.3)
rdc passes                        # → vkCmdBeginRendering passes
rdc pipeline 15                   # → gfx_pipe=330, TriangleList
rdc pick-pixel 640 360 15         # → pixel color at dynamic pass draw

VFS Deep Exploration

# Top-level structure
rdc tree / --depth 1

# Browse draw calls
rdc ls /draws
rdc ls /draws/142

# Explore shader stages
rdc ls /draws/142/shader
rdc cat /draws/142/shader/ps/disasm

# Browse passes
rdc ls -l /passes

# Navigate via current event alias
rdc goto 142
rdc cat /current/shader/ps