rdc-cli 0.2.0__py3-none-any.whl

rdc/__init__.py

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

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.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/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/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/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']}")

rdc/commands/doctor.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+import click
+
+from rdc.discover import find_renderdoc
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+
+
+def _check_python() -> CheckResult:
+    return CheckResult("python", True, sys.version.split()[0])
+
+
+def _check_platform() -> CheckResult:
+    system = platform.system().lower()
+    if system == "linux":
+        return CheckResult("platform", True, "linux")
+    if system == "darwin":
+        return CheckResult("platform", True, "darwin (dev-host only for replay)")
+    return CheckResult("platform", False, f"unsupported system: {system}")
+
+
+_RENDERDOC_BUILD_HINT = """\
+  To build the renderdoc Python module:
+    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"""
+
+
+def _import_renderdoc() -> tuple[Any | None, CheckResult]:
+    module = find_renderdoc()
+    if module is None:
+        return None, CheckResult("renderdoc-module", False, "not found in search paths")
+
+    version = getattr(module, "GetVersionString", lambda: "unknown")()
+    return module, CheckResult("renderdoc-module", True, f"version={version}")
+
+
+def _check_replay_support(module: Any | None) -> CheckResult:
+    if module is None:
+        return CheckResult("replay-support", False, "renderdoc module unavailable")
+
+    has_init = hasattr(module, "InitialiseReplay")
+    has_shutdown = hasattr(module, "ShutdownReplay")
+    has_global_env = hasattr(module, "GlobalEnvironment")
+
+    if has_init and has_shutdown and has_global_env:
+        return CheckResult("replay-support", True, "renderdoc replay API surface found")
+    return CheckResult("replay-support", False, "missing replay API surface")
+
+
+def _check_renderdoccmd() -> CheckResult:
+    path = shutil.which("renderdoccmd")
+    if path:
+        return CheckResult("renderdoccmd", True, path)
+    return CheckResult("renderdoccmd", False, "not found in PATH")
+
+
+def run_doctor() -> list[CheckResult]:
+    module, renderdoc_check = _import_renderdoc()
+    return [
+        _check_python(),
+        _check_platform(),
+        renderdoc_check,
+        _check_replay_support(module),
+        _check_renderdoccmd(),
+    ]
+
+
+@click.command("doctor")
+def doctor_cmd() -> None:
+    """Run environment checks for rdc-cli."""
+    results = run_doctor()
+    has_error = False
+
+    for result in results:
+        icon = "✅" if result.ok else "❌"
+        click.echo(f"{icon} {result.name}: {result.detail}")
+        if not result.ok:
+            has_error = True
+            if result.name == "renderdoc-module":
+                click.echo(_RENDERDOC_BUILD_HINT, err=True)
+
+    if has_error:
+        raise SystemExit(1)

rdc/commands/events.py

@@ -0,0 +1,140 @@
+"""Commands: rdc events, rdc draws, rdc event, rdc draw."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+from rdc.commands.info import _daemon_call, _format_kv
+from rdc.formatters.json_fmt import write_json, write_jsonl
+from rdc.formatters.tsv import write_footer, write_tsv
+
+
+@click.command("events")
+@click.option("--type", "event_type", default=None, help="Filter by type")
+@click.option("--filter", "pattern", default=None, help="Filter by name glob")
+@click.option("--limit", type=int, default=None, help="Max rows")
+@click.option("--range", "eid_range", default=None, help="EID range N:M")
+@click.option("--no-header", is_flag=True, help="Omit TSV header")
+@click.option("--json", "use_json", is_flag=True, help="JSON output")
+@click.option("--jsonl", "use_jsonl", is_flag=True, help="JSONL output")
+@click.option("-q", "--quiet", is_flag=True, help="Only EID column")
+def events_cmd(
+    event_type: str | None,
+    pattern: str | None,
+    limit: int | None,
+    eid_range: str | None,
+    no_header: bool,
+    use_json: bool,
+    use_jsonl: bool,
+    quiet: bool,
+) -> None:
+    """List all events."""
+    params: dict[str, Any] = {}
+    if event_type:
+        params["type"] = event_type
+    if pattern:
+        params["filter"] = pattern
+    if limit is not None:
+        params["limit"] = limit
+    if eid_range:
+        params["range"] = eid_range
+    result = _daemon_call("events", params)
+    rows_data = result.get("events", [])
+    if use_json:
+        write_json(rows_data)
+        return
+    if use_jsonl:
+        write_jsonl(rows_data)
+        return
+    if quiet:
+        for r in rows_data:
+            sys.stdout.write(str(r["eid"]) + chr(10))
+        return
+    header = ["EID", "TYPE", "NAME"]
+    rows = [[r["eid"], r["type"], r["name"]] for r in rows_data]
+    write_tsv(rows, header=header, no_header=no_header)
+
+
+@click.command("draws")
+@click.option("--pass", "pass_name", default=None, help="Filter by pass name")
+@click.option("--sort", "sort_field", default=None, help="Sort field")
+@click.option("--limit", type=int, default=None, help="Max rows")
+@click.option("--no-header", is_flag=True, help="Omit TSV header")
+@click.option("--json", "use_json", is_flag=True, help="JSON output")
+@click.option("--jsonl", "use_jsonl", is_flag=True, help="JSONL output")
+@click.option("-q", "--quiet", is_flag=True, help="Only EID column")
+def draws_cmd(
+    pass_name: str | None,
+    sort_field: str | None,
+    limit: int | None,
+    no_header: bool,
+    use_json: bool,
+    use_jsonl: bool,
+    quiet: bool,
+) -> None:
+    """List draw calls."""
+    params: dict[str, Any] = {}
+    if pass_name:
+        params["pass"] = pass_name
+    if sort_field:
+        params["sort"] = sort_field
+    if limit is not None:
+        params["limit"] = limit
+    result = _daemon_call("draws", params)
+    rows_data = result.get("draws", [])
+    summary = result.get("summary", "")
+    if use_json:
+        write_json(rows_data)
+        return
+    if use_jsonl:
+        write_jsonl(rows_data)
+        return
+    if quiet:
+        for r in rows_data:
+            sys.stdout.write(str(r["eid"]) + chr(10))
+        return
+    header = ["EID", "TYPE", "TRIANGLES", "INSTANCES", "PASS", "MARKER"]
+    rows = [
+        [
+            r["eid"],
+            r["type"],
+            r["triangles"],
+            r["instances"],
+            r.get("pass", "-"),
+            r.get("marker", "-"),
+        ]
+        for r in rows_data
+    ]
+    write_tsv(rows, header=header, no_header=no_header)
+    if summary:
+        write_footer(summary)
+
+
+@click.command("event")
+@click.argument("eid", type=int)
+@click.option("--json", "use_json", is_flag=True, help="JSON output")
+def event_cmd(eid: int, use_json: bool) -> None:
+    """Show single API call detail."""
+    result = _daemon_call("event", {"eid": eid})
+    if use_json:
+        write_json(result)
+        return
+    _format_kv(result)
+
+
+@click.command("draw")
+@click.argument("eid", type=int, required=False, default=None)
+@click.option("--json", "use_json", is_flag=True, help="JSON output")
+def draw_cmd(eid: int | None, use_json: bool) -> None:
+    """Show draw call detail."""
+    params: dict[str, Any] = {}
+    if eid is not None:
+        params["eid"] = eid
+    result = _daemon_call("draw", params)
+    if use_json:
+        write_json(result)
+        return
+    _format_kv(result)

rdc/commands/export.py

@@ -0,0 +1,57 @@
+"""Export convenience commands: texture, rt, buffer."""
+
+from __future__ import annotations
+
+import click
+
+from rdc.commands.info import _daemon_call
+from rdc.commands.vfs import _deliver_binary
+from rdc.vfs.router import resolve_path
+
+
+def _export_vfs_path(vfs_path: str, output: str | None, raw: bool) -> None:
+    """Resolve a VFS path and deliver binary content."""
+    result = _daemon_call("vfs_ls", {"path": vfs_path})
+    kind = result.get("kind")
+
+    if kind != "leaf_bin":
+        click.echo(f"error: {vfs_path}: not a binary node", err=True)
+        raise SystemExit(1)
+
+    resolved = result.get("path", vfs_path)
+    match = resolve_path(resolved)
+    if match is None or match.handler is None:
+        click.echo(f"error: {vfs_path}: no content handler", err=True)
+        raise SystemExit(1)
+
+    _deliver_binary(vfs_path, match, raw, output)
+
+
+@click.command("texture")
+@click.argument("id", type=int)
+@click.option("-o", "--output", type=click.Path(), default=None, help="Write to file")
+@click.option("--mip", default=0, type=int, help="Mip level (default 0)")
+@click.option("--raw", is_flag=True, help="Force raw output even on TTY")
+def texture_cmd(id: int, output: str | None, mip: int, raw: bool) -> None:
+    """Export texture as PNG."""
+    vfs_path = f"/textures/{id}/mips/{mip}.png" if mip > 0 else f"/textures/{id}/image.png"
+    _export_vfs_path(vfs_path, output, raw)
+
+
+@click.command("rt")
+@click.argument("eid", type=int)
+@click.option("-o", "--output", type=click.Path(), default=None, help="Write to file")
+@click.option("--target", default=0, type=int, help="Color target index (default 0)")
+@click.option("--raw", is_flag=True, help="Force raw output even on TTY")
+def rt_cmd(eid: int, output: str | None, target: int, raw: bool) -> None:
+    """Export render target as PNG."""
+    _export_vfs_path(f"/draws/{eid}/targets/color{target}.png", output, raw)
+
+
+@click.command("buffer")
+@click.argument("id", type=int)
+@click.option("-o", "--output", type=click.Path(), default=None, help="Write to file")
+@click.option("--raw", is_flag=True, help="Force raw output even on TTY")
+def buffer_cmd(id: int, output: str | None, raw: bool) -> None:
+    """Export buffer raw data."""
+    _export_vfs_path(f"/buffers/{id}/data", output, raw)