rdc-cli 0.2.0__tar.gz

rdc_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rdc_cli-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: rdc-cli
+Version: 0.2.0
+Summary: Unix-friendly CLI for RenderDoc captures
+Author: Jim
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == "rich"
+Provides-Extra: imaging
+Requires-Dist: Pillow>=10.0; extra == "imaging"
+Provides-Extra: diff
+Requires-Dist: Pillow>=10.0; extra == "diff"
+Requires-Dist: numpy>=1.24; extra == "diff"
+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
+
+# rdc-cli
+
+Unix-friendly CLI for [RenderDoc](https://renderdoc.org/) `.rdc` captures. Pipe-friendly TSV output, JSON mode, 33 commands, daemon-backed session for interactive exploration.
+
+```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 draws --json | jq '...'   # Machine-readable output
+rdc close                     # End session
+```
+
+## Install
+
+### PyPI (recommended)
+
+```bash
+pipx install rdc-cli
+```
+
+### AUR (Arch Linux)
+
+```bash
+yay -S rdc-cli-git
+```
+
+This builds the renderdoc Python module automatically — no extra setup needed.
+
+### From source
+
+```bash
+git clone https://github.com/BANANASJIM/rdc-cli.git
+cd rdc-cli
+pixi install && pixi run sync
+```
+
+## Setup renderdoc
+
+`rdc` requires the renderdoc Python module (`renderdoc.cpython-*.so`), which is **not** included in most system packages. Your Python version must match the one used to compile renderdoc.
+
+### Build from source
+
+```bash
+git clone --depth 1 https://github.com/baldurk/renderdoc.git
+cd renderdoc
+cmake -B build -DENABLE_PYRENDERDOC=ON -DENABLE_QRENDERDOC=OFF
+cmake --build build -j$(nproc)
+export RENDERDOC_PYTHON_PATH=$PWD/build/lib
+```
+
+### Module discovery order
+
+1. `RENDERDOC_PYTHON_PATH` environment variable
+2. `/usr/lib/renderdoc`, `/usr/local/lib/renderdoc`
+3. Sibling directory of `renderdoccmd` on PATH
+
+### Verify
+
+```bash
+rdc doctor
+```
+
+## 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` |
+| Resources | `resources`, `resource`, `passes`, `pass`, `usage` |
+| Export | `texture`, `rt`, `buffer` |
+| Search | `search`, `counters` |
+| VFS | `ls`, `cat`, `tree` |
+| Utility | `doctor`, `completion`, `capture`, `count` |
+
+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
+eval "$(rdc completion bash)"
+```
+
+## Development
+
+```bash
+pixi run sync                 # Install Python deps
+pixi run check                # lint + typecheck + test (653 tests, 92% coverage)
+```
+
+GPU integration tests require a real renderdoc module:
+
+```bash
+export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
+pixi run test-gpu
+```
+
+## License
+
+MIT

rdc_cli-0.2.0/README.md

@@ -0,0 +1,106 @@
+# rdc-cli
+
+Unix-friendly CLI for [RenderDoc](https://renderdoc.org/) `.rdc` captures. Pipe-friendly TSV output, JSON mode, 33 commands, daemon-backed session for interactive exploration.
+
+```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 draws --json | jq '...'   # Machine-readable output
+rdc close                     # End session
+```
+
+## Install
+
+### PyPI (recommended)
+
+```bash
+pipx install rdc-cli
+```
+
+### AUR (Arch Linux)
+
+```bash
+yay -S rdc-cli-git
+```
+
+This builds the renderdoc Python module automatically — no extra setup needed.
+
+### From source
+
+```bash
+git clone https://github.com/BANANASJIM/rdc-cli.git
+cd rdc-cli
+pixi install && pixi run sync
+```
+
+## Setup renderdoc
+
+`rdc` requires the renderdoc Python module (`renderdoc.cpython-*.so`), which is **not** included in most system packages. Your Python version must match the one used to compile renderdoc.
+
+### Build from source
+
+```bash
+git clone --depth 1 https://github.com/baldurk/renderdoc.git
+cd renderdoc
+cmake -B build -DENABLE_PYRENDERDOC=ON -DENABLE_QRENDERDOC=OFF
+cmake --build build -j$(nproc)
+export RENDERDOC_PYTHON_PATH=$PWD/build/lib
+```
+
+### Module discovery order
+
+1. `RENDERDOC_PYTHON_PATH` environment variable
+2. `/usr/lib/renderdoc`, `/usr/local/lib/renderdoc`
+3. Sibling directory of `renderdoccmd` on PATH
+
+### Verify
+
+```bash
+rdc doctor
+```
+
+## 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` |
+| Resources | `resources`, `resource`, `passes`, `pass`, `usage` |
+| Export | `texture`, `rt`, `buffer` |
+| Search | `search`, `counters` |
+| VFS | `ls`, `cat`, `tree` |
+| Utility | `doctor`, `completion`, `capture`, `count` |
+
+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
+eval "$(rdc completion bash)"
+```
+
+## Development
+
+```bash
+pixi run sync                 # Install Python deps
+pixi run check                # lint + typecheck + test (653 tests, 92% coverage)
+```
+
+GPU integration tests require a real renderdoc module:
+
+```bash
+export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
+pixi run test-gpu
+```
+
+## License
+
+MIT

rdc_cli-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rdc-cli"
+version = "0.2.0"
+description = "Unix-friendly CLI for RenderDoc captures"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Jim"}]
+dependencies = [
+  "click>=8.1",
+]
+
+[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",
+  "mypy>=1.10",
+  "ruff>=0.6",
+]
+
+[project.scripts]
+rdc = "rdc.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+markers = ["gpu: requires real renderdoc module and GPU"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true

rdc_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rdc_cli-0.2.0/src/rdc/__init__.py

@@ -0,0 +1,4 @@
+"""rdc package."""
+
+__all__ = ["__version__"]
+__version__ = "0.2.0"

rdc_cli-0.2.0/src/rdc/adapter.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+
+def parse_version_tuple(value: str) -> tuple[int, int]:
+    """Parse RenderDoc version string into (major, minor)."""
+    match = re.search(r"(\d+)\.(\d+)", value)
+    if not match:
+        return (0, 0)
+    return int(match.group(1)), int(match.group(2))
+
+
+@dataclass(frozen=True)
+class RenderDocAdapter:
+    """Compatibility adapter for RenderDoc API changes across versions."""
+
+    controller: Any
+    version: tuple[int, int]
+
+    def get_root_actions(self) -> Any:
+        """Return root actions with compatibility handling."""
+        if self.version >= (1, 32) and hasattr(self.controller, "GetRootActions"):
+            return self.controller.GetRootActions()
+        if hasattr(self.controller, "GetDrawcalls"):
+            return self.controller.GetDrawcalls()
+        raise AttributeError("controller has neither GetRootActions nor GetDrawcalls")
+
+    def get_api_properties(self) -> Any:
+        """Return API properties from the controller."""
+        return self.controller.GetAPIProperties()
+
+    def get_resources(self) -> Any:
+        """Return all resources from the controller."""
+        return self.controller.GetResources()
+
+    def get_pipeline_state(self) -> Any:
+        """Return current pipeline state."""
+        return self.controller.GetPipelineState()
+
+    def get_structured_file(self) -> Any:
+        """Return structured file from the controller."""
+        return self.controller.GetStructuredFile()
+
+    def set_frame_event(self, eid: int, force: bool = True) -> None:
+        """Move the replay to the given event ID."""
+        self.controller.SetFrameEvent(eid, force)
+
+    def get_textures(self) -> Any:
+        """Return all texture descriptions from the controller."""
+        return self.controller.GetTextures()
+
+    def get_buffers(self) -> Any:
+        """Return all buffer descriptions from the controller."""
+        return self.controller.GetBuffers()
+
+    def shutdown(self) -> None:
+        """Shutdown the replay controller."""
+        self.controller.Shutdown()

rdc_cli-0.2.0/src/rdc/cli.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import click
+
+from rdc import __version__
+from rdc.commands.capture import capture_cmd
+from rdc.commands.completion import completion_cmd
+from rdc.commands.counters import counters_cmd
+from rdc.commands.doctor import doctor_cmd
+from rdc.commands.events import draw_cmd, draws_cmd, event_cmd, events_cmd
+from rdc.commands.export import buffer_cmd, rt_cmd, texture_cmd
+from rdc.commands.info import info_cmd, log_cmd, stats_cmd
+from rdc.commands.pipeline import bindings_cmd, pipeline_cmd, shader_cmd, shaders_cmd
+from rdc.commands.resources import pass_cmd, passes_cmd, resource_cmd, resources_cmd
+from rdc.commands.search import search_cmd
+from rdc.commands.session import close_cmd, goto_cmd, open_cmd, status_cmd
+from rdc.commands.unix_helpers import count_cmd, shader_map_cmd
+from rdc.commands.usage import usage_cmd
+from rdc.commands.vfs import cat_cmd, complete_cmd, ls_cmd, tree_cmd
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="rdc")
+def main() -> None:
+    """rdc: Unix-friendly CLI for RenderDoc captures."""
+
+
+main.add_command(doctor_cmd, name="doctor")
+main.add_command(capture_cmd, name="capture")
+main.add_command(open_cmd, name="open")
+main.add_command(close_cmd, name="close")
+main.add_command(status_cmd, name="status")
+main.add_command(goto_cmd, name="goto")
+main.add_command(info_cmd, name="info")
+main.add_command(stats_cmd, name="stats")
+main.add_command(events_cmd, name="events")
+main.add_command(draws_cmd, name="draws")
+main.add_command(event_cmd, name="event")
+main.add_command(draw_cmd, name="draw")
+main.add_command(count_cmd, name="count")
+main.add_command(shader_map_cmd, name="shader-map")
+main.add_command(pipeline_cmd, name="pipeline")
+main.add_command(bindings_cmd, name="bindings")
+main.add_command(shader_cmd, name="shader")
+main.add_command(shaders_cmd, name="shaders")
+main.add_command(resources_cmd, name="resources")
+main.add_command(resource_cmd, name="resource")
+main.add_command(passes_cmd, name="passes")
+main.add_command(pass_cmd, name="pass")
+main.add_command(log_cmd, name="log")
+main.add_command(ls_cmd, name="ls")
+main.add_command(cat_cmd, name="cat")
+main.add_command(tree_cmd, name="tree")
+main.add_command(complete_cmd, name="_complete")
+main.add_command(texture_cmd, name="texture")
+main.add_command(rt_cmd, name="rt")
+main.add_command(buffer_cmd, name="buffer")
+main.add_command(search_cmd, name="search")
+main.add_command(usage_cmd, name="usage")
+main.add_command(completion_cmd, name="completion")
+main.add_command(counters_cmd, name="counters")
+
+
+if __name__ == "__main__":
+    main()

rdc_cli-0.2.0/src/rdc/commands/capture.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import click
+
+
+def _find_renderdoccmd() -> str | None:
+    in_path = shutil.which("renderdoccmd")
+    if in_path:
+        return in_path
+
+    common_paths = [
+        Path("/opt/renderdoc/bin/renderdoccmd"),
+        Path("/usr/local/bin/renderdoccmd"),
+    ]
+    for path in common_paths:
+        if path.exists() and path.is_file():
+            return str(path)
+    return None
+
+
+@click.command(
+    "capture",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+)
+@click.option("--api", "api_name", type=str, help="Capture API (maps to --opt-api).")
+@click.option("-o", "--output", type=click.Path(path_type=Path), help="Output capture file path.")
+@click.option("--list-apis", is_flag=True, help="List capture APIs via renderdoccmd and exit.")
+@click.pass_context
+def capture_cmd(
+    ctx: click.Context,
+    api_name: str | None,
+    output: Path | None,
+    list_apis: bool,
+) -> None:
+    """Thin wrapper around renderdoccmd capture."""
+    bin_path = _find_renderdoccmd()
+    if not bin_path:
+        click.echo("error: renderdoccmd not found in PATH", err=True)
+        raise SystemExit(1)
+
+    argv: list[str] = [bin_path, "capture"]
+
+    if list_apis:
+        argv.append("--list-apis")
+    else:
+        if api_name:
+            argv.extend(["--opt-api", api_name])
+        if output:
+            argv.extend(["--capture-file", str(output)])
+        argv.extend(ctx.args)
+
+    result = subprocess.run(argv, check=False)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+    if output and not list_apis:
+        click.echo(f"capture saved: {output}", err=True)
+        click.echo(f"next: rdc open {output}", err=True)

rdc_cli-0.2.0/src/rdc/commands/completion.py

@@ -0,0 +1,49 @@
+"""Shell completion script generation."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import click
+
+_SUPPORTED_SHELLS = ("bash", "zsh", "fish")
+
+
+def _detect_shell() -> str:
+    """Detect current shell from $SHELL."""
+    name = Path(os.environ.get("SHELL", "bash")).name
+    return name if name in _SUPPORTED_SHELLS else "bash"
+
+
+def _generate(shell: str) -> str:
+    """Generate completion script via Click's built-in mechanism."""
+    from click.shell_completion import get_completion_class
+
+    from rdc.cli import main  # deferred: rdc.cli imports this module
+
+    cls = get_completion_class(shell)
+    if cls is None:
+        raise click.ClickException(f"Unsupported shell: {shell}")
+    comp = cls(cli=main, ctx_args={}, prog_name="rdc", complete_var="_RDC_COMPLETE")
+    return comp.source()
+
+
+@click.command("completion")
+@click.argument("shell", required=False, type=click.Choice(_SUPPORTED_SHELLS))
+def completion_cmd(shell: str | None) -> None:
+    """Generate shell completion script.
+
+    Prints the completion script to stdout. Redirect or eval as needed.
+
+    \b
+    Examples:
+        rdc completion bash > ~/.local/share/bash-completion/completions/rdc
+        rdc completion zsh > ~/.zfunc/_rdc
+        eval "$(rdc completion bash)"
+    """
+    if shell is None:
+        shell = _detect_shell()
+        click.echo(f"# Detected shell: {shell}", err=True)
+
+    click.echo(_generate(shell))

rdc_cli-0.2.0/src/rdc/commands/counters.py

@@ -0,0 +1,50 @@
+"""rdc counters command — GPU performance counters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from rdc.commands.info import _daemon_call
+from rdc.formatters.json_fmt import write_json
+
+
+@click.command("counters")
+@click.option("--list", "show_list", is_flag=True, help="List available counters.")
+@click.option("--eid", type=int, default=None, help="Filter to specific event ID.")
+@click.option("--name", "name_filter", default=None, help="Filter counters by name substring.")
+@click.option("--json", "use_json", is_flag=True, help="JSON output.")
+def counters_cmd(
+    show_list: bool,
+    eid: int | None,
+    name_filter: str | None,
+    use_json: bool,
+) -> None:
+    """Query GPU performance counters.
+
+    Use --list to enumerate available counters, or run without --list
+    to fetch counter values for all draw events.
+    """
+    if show_list:
+        result = _daemon_call("counter_list")
+        if use_json:
+            write_json(result)
+            return
+        click.echo("ID\tNAME\tUNIT\tTYPE\tCATEGORY")
+        for c in result.get("counters", []):
+            click.echo(f"{c['id']}\t{c['name']}\t{c['unit']}\t{c['type']}\t{c['category']}")
+        return
+
+    params: dict[str, Any] = {}
+    if eid is not None:
+        params["eid"] = eid
+    if name_filter is not None:
+        params["name"] = name_filter
+    result = _daemon_call("counter_fetch", params)
+    if use_json:
+        write_json(result)
+        return
+    click.echo("EID\tCOUNTER\tVALUE\tUNIT")
+    for r in result.get("rows", []):
+        click.echo(f"{r['eid']}\t{r['counter']}\t{r['value']}\t{r['unit']}")