webgpu-capture-analysis

name	webgpu-capture-analysis
description	Interpret WebGPU Inspector frame captures — the GPU object graph, the command list, render/compute passes, buffers, textures, shaders, validation errors, and common performance problems. Use when analyzing captures produced by the webgpu-inspector plugin's MCP tools or by saveCaptureData() / DevTools "Save Capture" .json files.

WebGPU capture analysis

A WebGPU Inspector capture is a JSON record of one or more rendered frames: the full GPU object graph plus the ordered list of WebGPU API calls. This skill explains how to read one and what to flag.

Capture shape

• objects — map of numeric id to a record: { id, type, label, descriptor, stacktrace, ... }. Types: Adapter, Device, Buffer, Texture, TextureView, Sampler, BindGroup, BindGroupLayout, PipelineLayout, RenderPipeline, ComputePipeline, ShaderModule, RenderBundle.
• commands — ordered array of { index, method, object, args, result, ... }. object is the GPU object the method was called on; args are its arguments. References to GPU objects appear as { "__id": N, "__class": ..., "__label": ... }.
• validationErrors — WebGPU validation errors raised during the capture.
• Large buffer/texture payloads are base64; the MCP tools strip them, so you see __base64Omitted markers and byte lengths instead of bytes.

Workflow

Always start with get_capture_summary — it carries object/command counts, derived stats, and a heuristic issues list. Then drill in:

• get_commands with a method filter or an offset/limit window — never fetch the whole list at once for a large capture.
• get_object for a pipeline, bind group, or texture descriptor.
• get_shader for a ShaderModule's WGSL.
• get_validation_errors for correctness problems.

Cite index (command) and id (object) values in findings so the user can locate them in the WebGPU Inspector DevTools Capture panel.

What to look for

Correctness

• Any validationErrors — always report these first; they are real bugs.
• A canvas texture used after its frame expired, or destroyed objects still referenced (the inspector reports these as validation errors).

Per-frame cost / hitching

• createRenderPipeline / createComputePipeline inside the captured frame — pipeline creation is expensive; move it to load time.
• createShaderModule inside the frame — same idea.
• Large or numerous writeBuffer / writeTexture calls every frame — consider persistent buffers, mapped writes, or uploading less.

CPU submission overhead

• High setPipeline / setBindGroup / setVertexBuffer counts relative to draw calls — sort draws by pipeline and bind group to cut state changes.
• Redundant consecutive setPipeline / setBindGroup (the summary flags these) — the bind is a no-op and can be skipped.
• Many small draw calls with the same pipeline — candidates for instancing, batching, or render bundles.

Pass structure

• Excess beginRenderPass calls — each pass has fixed cost; merge where the attachments allow.
• loadOp: "load" where "clear" would do (forces an attachment read), or storeOp: "store" on attachments whose result is never used.
• Depth/stencil attachment configuration vs. what the draws need.

Shaders (via get_shader)

• Work in the fragment stage that could move to the vertex stage.
• Dynamically uniform branching, heavy loops, or texture sampling in loops.
• Bind group layout mismatches across entry points.

Reporting

Give a prioritized list. For each finding: severity (error > warning > info), a one-line description, why it matters for this capture, and a concrete fix. Reference command indices and object ids. Distinguish confirmed bugs (validation errors) from heuristics (a flagged pattern that may be intentional) — say which is which rather than overstating.