From 84e7213e86d125acb54c21ac5779bd96c92f7bee Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Mon, 23 Mar 2026 18:50:16 +0800 Subject: [PATCH] docs: update README with accurate function signatures --- engine/tools/renderdoc_parser/README.md | 83 ++++++++++++------------- 1 file changed, 41 insertions(+), 42 deletions(-) diff --git a/engine/tools/renderdoc_parser/README.md b/engine/tools/renderdoc_parser/README.md index c9f85d13..7792fd1c 100644 --- a/engine/tools/renderdoc_parser/README.md +++ b/engine/tools/renderdoc_parser/README.md @@ -41,75 +41,75 @@ print(get_frame_overview()) | `get_action(event_id)` | Get a single ActionDescription by event ID. | | `set_event(event_id)` | Navigate to a specific event. | | `search_actions(name_pattern=None, flags=None)` | Search actions by name substring or ActionFlags. | -| `find_draws(filter=None)` | Find all draw calls, optionally filtered by name substring. | +| `find_draws(blend=None, min_vertices=None, texture_id=None, shader_id=None, render_target_id=None, max_results=50)` | Find draw calls matching criteria. | ### Pipeline State (4 functions) | Function | Description | |----------|-------------| -| `get_pipeline_state(event_id)` | Full pipeline state at an event (shaders, blend, rasterizer, depth-stencil, etc.). | -| `get_shader_bindings(event_id, stage=None)` | Shader resource bindings. `stage` accepts `"vertex"`, `"pixel"`, `"compute"`, etc. | -| `get_vertex_inputs(event_id)` | Vertex input layout (format, semantic, register). | -| `get_draw_call_state(event_id)` | Summary of the draw call at an event (indices, instances, topology, outputs). | +| `get_pipeline_state(event_id=None)` | Full pipeline state at an event: shaders, viewports, scissors, blend, stencil, output targets. | +| `get_shader_bindings(stage, event_id=None)` | Shader resource bindings. `stage` is required: `"vertex"`, `"hull"`, `"domain"`, `"geometry"`, `"pixel"`, `"compute"`. | +| `get_vertex_inputs(event_id=None)` | Vertex input layout (format, semantic, register, stride). | +| `get_draw_call_state(event_id=None)` | Summary of the draw call at an event (indices, instances, topology, textures, shaders). | ### Resources (4 functions) | Function | Description | |----------|-------------| -| `list_textures()` | All textures with dimensions, format, mip levels, memory estimate. | -| `list_buffers()` | All buffers with length and creation flags. | -| `list_resources()` | All resources (textures + buffers) unified. | +| `list_textures(filter_format=None, min_width=0)` | All textures with dimensions, format, mip levels. | +| `list_buffers(min_size=0)` | All buffers with length and creation flags. | +| `list_resources(type_filter=None, name_pattern=None)` | All resources (textures + buffers) unified. | | `get_resource_usage(resource_id)` | Which events use a given resource and how. | ### Data Reading (8 functions) | Function | Description | |----------|-------------| -| `save_texture(resource_id, path, fmt=None)` | Save a texture to file. `fmt` accepts `"png"`, `"jpg"`, `"bmp"`, `"tga"`, `"hdr"`, `"exr"`, `"dds"`. | -| `get_buffer_data(resource_id)` | Raw bytes of a buffer. | -| `pick_pixel(x, y, event_id=None)` | RGBA value at a pixel. Defaults to current event if `event_id` is `None`. | -| `get_texture_stats(resource_id)` | Min/max/avg values for a texture. | -| `read_texture_pixels(resource_id, x, y, w, h)` | Pixel region as a 2D list of RGBA values. | -| `export_draw_textures(event_id, path)` | Save all render targets at a draw call to image files. | -| `save_render_target(resource_id, path)` | Save a specific render target to file. | -| `export_mesh(event_id, vertex_buffer=None, index_buffer=None)` | Export mesh data (positions, normals, UVs, indices) as a structured dict. | +| `save_texture(resource_id, output_path, file_type=None, mip=0, event_id=None)` | Save a texture to file. `file_type` accepts `"png"`, `"jpg"`, `"bmp"`, `"tga"`, `"hdr"`, `"exr"`, `"dds"`. | +| `get_buffer_data(resource_id, offset=0, length=None, format=None)` | Raw bytes of a buffer. | +| `pick_pixel(resource_id, x, y, event_id=None)` | RGBA value at a pixel. | +| `get_texture_stats(resource_id, event_id=None, all_slices=False)` | Min/max/avg values for a texture. | +| `read_texture_pixels(resource_id, x, y, width, height, mip_level=0, array_slice=0, event_id=None)` | Pixel region as a 2D list of RGBA values. | +| `export_draw_textures(event_id, output_dir, skip_small=True)` | Save all render targets at a draw call to image files. | +| `save_render_target(event_id, output_path, save_depth=False)` | Save a specific render target to file. | +| `export_mesh(event_id, output_path=None)` | Export mesh data (positions, normals, UVs, indices) as a structured dict. | ### Shader Analysis (3 functions) | Function | Description | |----------|-------------| -| `disassemble_shader(event_id, stage=None, target=None)` | Disassembled shader code. `stage` is required. | -| `get_shader_reflection(event_id, stage=None)` | Shader reflection: inputs, outputs, cbuffers, textures, samplers. | -| `get_cbuffer_contents(event_id, stage, slot)` | Contents of a constant buffer slot for a given stage. | +| `disassemble_shader(stage, target=None, event_id=None, line_range=None, search=None)` | Disassembled shader code. `stage` is required. `target` is a disassembly backend (e.g. `"DXBC/DXIL"`). | +| `get_shader_reflection(stage, event_id=None)` | Shader reflection: inputs, outputs, cbuffers, textures, samplers. | +| `get_cbuffer_contents(stage, cbuffer_index, event_id=None, filter=None)` | Contents of a constant buffer slot for a given stage. | ### Advanced (6 functions) | Function | Description | |----------|-------------| -| `pixel_history(x, y)` | All events that wrote to or modified a pixel, with before/after values. | -| `get_post_vs_data(event_id, stage="vertex")` | Post-vertex-shader data (positions, clip positions, cull distances). | -| `diff_draw_calls(event_id1, event_id2)` | Diff two draw calls: state differences and likely causes. | -| `analyze_render_passes(event_id)` | Render pass grouping: which draw calls contribute to which render targets. | -| `sample_pixel_region(x, y, w, h, event_id=None)` | Sample all pixels in a region. Returns NaN/Inf/negative/bright pixel counts. | -| `debug_shader_at_pixel(x, y, event_id=None)` | Step-by-step shader debug at a pixel. | +| `pixel_history(resource_id, x, y, event_id=None)` | All events that wrote to or modified a pixel, with before/after values. | +| `get_post_vs_data(stage="vertex", max_vertices=None, event_id=None)` | Post-vertex-shader data (positions, clip positions, cull distances). | +| `diff_draw_calls(eid1, eid2)` | Diff two draw calls: state differences and likely causes. | +| `analyze_render_passes()` | Render pass grouping: which draw calls contribute to which render targets. | +| `sample_pixel_region(event_id=None, resource_id=None, region=None, sample_count=64, anomaly_threshold=0.5)` | Sample all pixels in a region. Returns NaN/Inf/negative/bright pixel counts. | +| `debug_shader_at_pixel(event_id=None, pixel_x=None, pixel_y=None, stage=None, watch_variables=None)` | Step-by-step shader debug at a pixel. | ### Performance (4 functions) | Function | Description | |----------|-------------| | `get_pass_timing(granularity="pass", top_n=20)` | GPU timing per pass or per draw call. | -| `analyze_overdraw(sample_count=64)` | Overdraw heatmap data: which pixels are shaded how many times. | -| `analyze_bandwidth()` | Estimated memory bandwidth: texture reads, render target writes, buffer traffic. | -| `analyze_state_changes(track=None)` | Track state changes between draw calls. `track` accepts `["blend", "depth", "stencil", "rasterizer", "shader", "vertex", "index", "viewport"]`. | +| `analyze_overdraw(pass_name=None, region=None, sample_count=64)` | Overdraw analysis: draw counts per render target. | +| `analyze_bandwidth(breakdown_by=None)` | Estimated memory bandwidth: texture reads, render target writes, buffer traffic. | +| `analyze_state_changes(pass_name=None, change_types=None)` | Track state changes between draw calls. `change_types` accepts `["blend", "depth", "cull", "shader", "vertex", "index", "render_target"]`. | ### Diagnostics (4 functions) | Function | Description | |----------|-------------| -| `diagnose_negative_values(event_id)` | Detect render targets receiving negative values — undefined behavior on many GPUs. | -| `diagnose_precision_issues(event_id)` | Detect potential half-float precision issues in shaders. | -| `diagnose_reflection_mismatch(event_id)` | Detect shader resource counts/types that differ from pipeline state. | -| `diagnose_mobile_risks(event_id)` | Mobile GPU-specific risks based on detected driver (Adreno, Mali, PowerVR, Apple). | +| `diagnose_negative_values(check_targets=None, trace_depth=100)` | Detect render targets receiving negative values. Operates on current event. | +| `diagnose_precision_issues(focus=None, threshold=None)` | Detect potential half-float precision issues. | +| `diagnose_reflection_mismatch(reflection_pass_hint=None, object_hint=None)` | Detect shader resource counts/types that differ from pipeline state. | +| `diagnose_mobile_risks(check_categories=None, severity_filter="all")` | Mobile GPU-specific risks based on detected driver (Adreno, Mali, PowerVR, Apple). Operates on current event. | ## Return Format @@ -128,18 +128,17 @@ engine/tools/renderdoc_parser/ ├── __init__.py # Re-exports all 42 functions at package level ├── session.py # RenderDoc session singleton ├── util.py # load_renderdoc(), serialization helpers, enum maps -├── test.rdc # Sample capture for testing └── tools/ ├── __init__.py # Re-exports all functions by module - ├── session_tools.py # open_capture, close_capture, get_capture_info, get_frame_overview - ├── event_tools.py # list_actions, get_action, set_event, search_actions, find_draws - ├── pipeline_tools.py # get_pipeline_state, get_shader_bindings, get_vertex_inputs, get_draw_call_state - ├── resource_tools.py # list_textures, list_buffers, list_resources, get_resource_usage - ├── data_tools.py # save_texture, get_buffer_data, pick_pixel, get_texture_stats, ... - ├── shader_tools.py # disassemble_shader, get_shader_reflection, get_cbuffer_contents - ├── advanced_tools.py # pixel_history, get_post_vs_data, diff_draw_calls, ... - ├── performance_tools.py # get_pass_timing, analyze_overdraw, analyze_bandwidth, analyze_state_changes - └── diagnostic_tools.py # diagnose_negative_values, diagnose_precision_issues, ... + ├── session_tools.py # open_capture, close_capture, get_capture_info, get_frame_overview + ├── event_tools.py # list_actions, get_action, set_event, search_actions, find_draws + ├── pipeline_tools.py # get_pipeline_state, get_shader_bindings, get_vertex_inputs, get_draw_call_state + ├── resource_tools.py # list_textures, list_buffers, list_resources, get_resource_usage + ├── data_tools.py # save_texture, get_buffer_data, pick_pixel, get_texture_stats, ... + ├── shader_tools.py # disassemble_shader, get_shader_reflection, get_cbuffer_contents + ├── advanced_tools.py # pixel_history, get_post_vs_data, diff_draw_calls, ... + ├── performance_tools.py # get_pass_timing, analyze_overdraw, analyze_bandwidth, analyze_state_changes + └── diagnostic_tools.py # diagnose_negative_values, diagnose_precision_issues, ... ``` ## GPU Quirks