rdc-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{rdc_cli-0.2.0 → rdc_cli-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Jim
+Copyright (c) 2024 BANANASJIM
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

rdc_cli-0.3.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: rdc-cli
+Version: 0.3.0
+Summary: Unix-friendly CLI for RenderDoc .rdc captures
+Author: Jim
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: Pillow>=10.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == "rich"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+```
+ _____  _____   _____
+|  __ \|  __ \ / ____|
+| |__) | |  | | |
+|  _  /| |  | | |
+| | \ \| |__| | |____
+|_|  \_\_____/ \_____|  cli
+```
+
+[![PyPI](https://img.shields.io/pypi/v/rdc-cli)](https://pypi.org/project/rdc-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/rdc-cli/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Commands](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/commands.json)](https://bananasjim.github.io/rdc-cli/)
+[![Tests](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/tests.json)](https://bananasjim.github.io/rdc-cli/)
+[![Coverage](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/coverage.json)](https://bananasjim.github.io/rdc-cli/)
+
+Pipe-friendly TSV output, JSON mode, 51 commands, daemon-backed session for interactive exploration of [RenderDoc](https://renderdoc.org/) `.rdc` captures.
+
+**[Full documentation →](https://bananasjim.github.io/rdc-cli/)**
+
+```bash
+rdc open capture.rdc            # start session
+rdc draws                       # list draw calls (TSV)
+rdc pipeline 142                # pipeline state at EID 142
+rdc shader 142 ps               # pixel shader disassembly
+rdc texture 5 -o out.png        # export texture
+rdc debug 142 ps 400 300        # debug pixel shader at (400,300)
+rdc assert-pixel 142 400 300 \
+    --expect 0.5,0.0,0.0,1.0   # CI pixel assertion
+rdc draws --json | jq '...'     # machine-readable output
+rdc close                       # end session
+```
+
+## Install
+
+**PyPI** (recommended)
+
+```bash
+pipx install rdc-cli
+# build renderdoc Python module (one-time, ~3 min, needs cmake/ninja/python3)
+curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh | bash
+rdc doctor   # verify installation
+```
+
+**AUR** (Arch Linux — builds renderdoc Python module automatically)
+
+```bash
+yay -S rdc-cli-git
+```
+
+**From source**
+
+```bash
+git clone https://github.com/BANANASJIM/rdc-cli.git
+cd rdc-cli
+pixi install && pixi run sync
+```
+
+## Commands
+
+Run `rdc --help` for the full command list, or `rdc <command> --help` for details.
+
+| Category | Commands |
+|----------|----------|
+| Session | `open`, `close`, `status`, `goto` |
+| Inspection | `info`, `stats`, `events`, `draws`, `event`, `draw`, `log` |
+| GPU state | `pipeline`, `bindings`, `shader`, `shaders`, `shader-map` |
+| Debug | `debug`, `pixel`, `pick-pixel`, `tex-stats` |
+| Shader Edit | `shader-build`, `shader-replace`, `shader-restore`, `shader-restore-all`, `shader-encodings` |
+| Resources | `resources`, `resource`, `passes`, `pass`, `usage` |
+| Export | `texture`, `rt`, `buffer`, `mesh`, `snapshot` |
+| Search | `search`, `counters` |
+| Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |
+| VFS | `ls`, `cat`, `tree` |
+| Utility | `doctor`, `completion`, `capture`, `count`, `script`, `diff` |
+
+All commands support `--json` for machine-readable output.
+
+### Shell completions
+
+```bash
+rdc completion bash > ~/.local/share/bash-completion/completions/rdc
+rdc completion zsh  > ~/.zfunc/_rdc
+rdc completion fish > ~/.config/fish/completions/rdc.fish
+```
+
+## Development
+
+```bash
+pixi run sync                 # install deps + activate git hooks
+pixi run check                # lint + typecheck + test (1729 tests, 95.51% coverage)
+pixi run verify               # full packaging verification (19 checks)
+```
+
+GPU integration tests require a real renderdoc module:
+
+```bash
+export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
+pixi run test-gpu
+```
+
+## License
+
+[MIT](LICENSE)

rdc_cli-0.3.0/README.md

@@ -0,0 +1,104 @@
+```
+ _____  _____   _____
+|  __ \|  __ \ / ____|
+| |__) | |  | | |
+|  _  /| |  | | |
+| | \ \| |__| | |____
+|_|  \_\_____/ \_____|  cli
+```
+
+[![PyPI](https://img.shields.io/pypi/v/rdc-cli)](https://pypi.org/project/rdc-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/rdc-cli/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Commands](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/commands.json)](https://bananasjim.github.io/rdc-cli/)
+[![Tests](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/tests.json)](https://bananasjim.github.io/rdc-cli/)
+[![Coverage](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/coverage.json)](https://bananasjim.github.io/rdc-cli/)
+
+Pipe-friendly TSV output, JSON mode, 51 commands, daemon-backed session for interactive exploration of [RenderDoc](https://renderdoc.org/) `.rdc` captures.
+
+**[Full documentation →](https://bananasjim.github.io/rdc-cli/)**
+
+```bash
+rdc open capture.rdc            # start session
+rdc draws                       # list draw calls (TSV)
+rdc pipeline 142                # pipeline state at EID 142
+rdc shader 142 ps               # pixel shader disassembly
+rdc texture 5 -o out.png        # export texture
+rdc debug 142 ps 400 300        # debug pixel shader at (400,300)
+rdc assert-pixel 142 400 300 \
+    --expect 0.5,0.0,0.0,1.0   # CI pixel assertion
+rdc draws --json | jq '...'     # machine-readable output
+rdc close                       # end session
+```
+
+## Install
+
+**PyPI** (recommended)
+
+```bash
+pipx install rdc-cli
+# build renderdoc Python module (one-time, ~3 min, needs cmake/ninja/python3)
+curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh | bash
+rdc doctor   # verify installation
+```
+
+**AUR** (Arch Linux — builds renderdoc Python module automatically)
+
+```bash
+yay -S rdc-cli-git
+```
+
+**From source**
+
+```bash
+git clone https://github.com/BANANASJIM/rdc-cli.git
+cd rdc-cli
+pixi install && pixi run sync
+```
+
+## Commands
+
+Run `rdc --help` for the full command list, or `rdc <command> --help` for details.
+
+| Category | Commands |
+|----------|----------|
+| Session | `open`, `close`, `status`, `goto` |
+| Inspection | `info`, `stats`, `events`, `draws`, `event`, `draw`, `log` |
+| GPU state | `pipeline`, `bindings`, `shader`, `shaders`, `shader-map` |
+| Debug | `debug`, `pixel`, `pick-pixel`, `tex-stats` |
+| Shader Edit | `shader-build`, `shader-replace`, `shader-restore`, `shader-restore-all`, `shader-encodings` |
+| Resources | `resources`, `resource`, `passes`, `pass`, `usage` |
+| Export | `texture`, `rt`, `buffer`, `mesh`, `snapshot` |
+| Search | `search`, `counters` |
+| Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |
+| VFS | `ls`, `cat`, `tree` |
+| Utility | `doctor`, `completion`, `capture`, `count`, `script`, `diff` |
+
+All commands support `--json` for machine-readable output.
+
+### Shell completions
+
+```bash
+rdc completion bash > ~/.local/share/bash-completion/completions/rdc
+rdc completion zsh  > ~/.zfunc/_rdc
+rdc completion fish > ~/.config/fish/completions/rdc.fish
+```
+
+## Development
+
+```bash
+pixi run sync                 # install deps + activate git hooks
+pixi run check                # lint + typecheck + test (1729 tests, 95.51% coverage)
+pixi run verify               # full packaging verification (19 checks)
+```
+
+GPU integration tests require a real renderdoc module:
+
+```bash
+export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
+pixi run test-gpu
+```
+
+## License
+
+[MIT](LICENSE)

{rdc_cli-0.2.0 → rdc_cli-0.3.0}/pyproject.toml

@@ -4,20 +4,30 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rdc-cli"
-version = "0.2.0"
-description = "Unix-friendly CLI for RenderDoc captures"
+version = "0.3.0"
+description = "Unix-friendly CLI for RenderDoc .rdc captures"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 authors = [{name = "Jim"}]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Environment :: Console",
+  "Topic :: Multimedia :: Graphics",
+]
 dependencies = [
   "click>=8.1",
+  "Pillow>=10.0",
+  "numpy>=1.24",
 ]
 
 [project.optional-dependencies]
 rich = ["rich>=13.0"]
-imaging = ["Pillow>=10.0"]
-diff = ["Pillow>=10.0", "numpy>=1.24"]
 dev = [
   "pytest>=8.0",
   "pytest-cov>=5.0",
@@ -31,6 +41,9 @@ rdc = "rdc.cli:main"
 [tool.setuptools]
 package-dir = {"" = "src"}
 
+[tool.setuptools.package-data]
+"rdc._skills" = ["**/*.md"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

rdc_cli-0.3.0/src/rdc/_skills/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: rdc-cli
+description: >
+  Use this skill when working with RenderDoc capture files (.rdc), analyzing GPU frames,
+  tracing shaders, inspecting draw calls, or running CI assertions against GPU captures.
+  Trigger phrases: "open capture", "rdc file", ".rdc", "renderdoc", "shader debug",
+  "pixel trace", "draw calls", "GPU frame", "assert pixel", "export render target".
+---
+
+# 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: `rdc open path/to/capture.rdc`
+2. **Inspect** metadata: `rdc info`, `rdc stats`, `rdc events`
+3. **Navigate** the VFS: `rdc ls /`, `rdc ls /textures`, `rdc cat /pipelines/0`
+4. **Analyze** specifics: `rdc shaders`, `rdc pipeline`, `rdc resources`, `rdc bindings`
+5. **Debug** shaders: `rdc debug pixel X Y`, `rdc debug vertex EID VTXID`, `rdc debug thread EID GX GY GZ`
+6. **Export** data: `rdc texture EID -o out.png`, `rdc rt EID`, `rdc buffer EID -o buf.bin`, `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")'
+```
+
+## Common Tasks
+
+### Find all draw calls
+
+```bash
+rdc draws
+rdc draws --pass "GBuffer" --json
+```
+
+### Trace a pixel
+
+```bash
+rdc debug pixel 512 384
+rdc debug pixel 512 384 --json    # structured output
+rdc debug pixel 512 384 --trace   # full step-by-step trace
+```
+
+### Search shaders by name or source
+
+```bash
+rdc search "main" --type shader
+rdc shaders --name "GBuffer*"
+```
+
+### Export render targets
+
+```bash
+rdc rt EID -o output.png
+rdc texture EID --format png -o tex.png
+```
+
+### Browse VFS paths
+
+```bash
+rdc ls /
+rdc ls /textures -l
+rdc tree /pipelines --depth 2
+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 X Y --expect R,G,B,A` | Assert pixel color at coordinates |
+| `rdc assert-clean` | Assert no validation errors in capture |
+| `rdc assert-count --type DrawIndexed --min N` | Assert minimum draw call count |
+| `rdc assert-state FIELD VALUE` | Assert pipeline state field matches value |
+| `rdc assert-image EID --ref reference.png` | Assert render target matches reference image |
+
+Example CI script:
+
+```bash
+#!/bin/bash
+set -e
+rdc open test_capture.rdc
+rdc assert-clean
+rdc assert-count --type DrawIndexed --min 10
+rdc assert-pixel 256 256 --expect 1.0,0.0,0.0,1.0
+rdc close
+```
+
+## Shader Edit-Replay
+
+Modify and replay shaders without recompiling the application:
+
+```bash
+rdc shader-encodings EID          # list available encodings
+rdc shader EID --source > s.frag  # extract shader source
+# ... edit s.frag ...
+rdc shader-build s.frag --encoding glsl  # compile edited shader
+rdc shader-replace EID s.frag     # hot-swap into capture
+rdc shader-restore EID            # revert single shader
+rdc shader-restore-all            # revert all modifications
+```
+
+## Command Reference
+
+For the complete list of all commands with their arguments, options, types, and defaults, see [references/commands-quick-ref.md](references/commands-quick-ref.md).