|
| 1 | +--- |
| 2 | +title: Debugging and Profiling with PIX |
| 3 | +image: |
| 4 | +description: Learn how to use PIX to debug and profile your Babylon.js application. |
| 5 | +keywords: PIX, debugging, profiling, performance, GPU |
| 6 | +further-reading: |
| 7 | +video-overview: |
| 8 | +video-content: |
| 9 | +--- |
| 10 | + |
| 11 | +## Debugging and Profiling with PIX |
| 12 | + |
| 13 | +[PIX](https://devblogs.microsoft.com/pix/) is a performance tuning and debugging tool from Microsoft for DirectX-based applications on Windows. It allows you to capture and analyze GPU workloads, inspect draw calls, profile frame timing, and debug shaders. When used with Babylon.js running on a WebGPU-enabled browser such as Chrome, PIX provides deep visibility into the rendering pipeline, helping you identify performance bottlenecks, verify that GPU resources are being used efficiently, and diagnose visual artifacts at the API level. |
| 14 | + |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +## Prerequisites |
| 20 | + |
| 21 | +<Alert severity="info" title="Version Note" description="These instructions were tested with PIX 2601.15 and Chrome 145. Steps and appearance may vary slightly with different versions of PIX or Chrome."/> |
| 22 | + |
| 23 | +Install PIX 2601.15: |
| 24 | +https://devblogs.microsoft.com/pix/download/ |
| 25 | + |
| 26 | +Download the WinPixEventRuntime NuGet package, unzip `winpixeventruntime.*.nupkg`, and copy the `bin\x64\*.dll` files into your `<Chrome Installation Directory>` (usually `C:\Program Files\Google\Chrome\Application\`): |
| 27 | +https://www.nuget.org/packages/WinPixEventRuntime |
| 28 | + |
| 29 | +## Setting Up the Environment |
| 30 | + |
| 31 | +Enable developer settings in the NVIDIA Control Panel: |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +Allow access to GPU counters: |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +Enable Developer Mode in Windows Settings: |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +## Launching the Process |
| 44 | + |
| 45 | + |
| 46 | + |
| 47 | +**Executable Path:** `<Chrome Installation Directory>/chrome.exe` |
| 48 | + |
| 49 | +**Working Directory:** `<Chrome Installation Directory>` |
| 50 | + |
| 51 | +**Command Line Args:** `--incognito --disable-gpu-sandbox --disable-gpu-watchdog --disable-direct-composition --enable-dawn-features=emit_hlsl_debug_symbols,disable_symbol_renaming https://playground.babylonjs.com/?inspectorv2=true&engine=webgpu#DR9MT2#35` |
| 52 | + |
| 53 | +<Alert severity="info" title="WebGPU Engine" description="The URL includes the query parameter engine=webgpu, which forces the Babylon.js Playground to use the WebGPU engine instead of the default WebGL. This is required for PIX to capture DirectX-level GPU activity."/> |
| 54 | + |
| 55 | +| Chrome option used to launch | Description | |
| 56 | +| --- | --- | |
| 57 | +| `--incognito` | Launches Chrome in incognito mode so that extensions and cached state do not interfere with the capture. | |
| 58 | +| `--disable-gpu-sandbox` | Disables the GPU process sandbox, allowing PIX to inject into and communicate with the GPU process. | |
| 59 | +| `--disable-gpu-watchdog` | Prevents Chrome from killing the GPU process when a frame takes too long, which is common while PIX is capturing or single-stepping through draw calls. | |
| 60 | +| `--disable-direct-composition` | Disables Windows DirectComposition, forcing Chrome to use a swap chain that PIX can intercept for frame capture. | |
| 61 | +| `--enable-dawn-features=emit_hlsl_debug_symbols,disable_symbol_renaming` | Enables Dawn (Chrome's WebGPU implementation) features: **emit_hlsl_debug_symbols** includes debug information in the generated HLSL shaders, and **disable_symbol_renaming** preserves original variable and function names so they are readable in PIX's shader debugger. | |
| 62 | + |
| 63 | +## GPU Capture |
| 64 | + |
| 65 | +A GPU capture records a single frame of rendering activity, letting you inspect every draw call, resource binding, and pipeline state in detail. After launching Chrome through PIX, click the **GPU Capture** button (camera icon) on the PIX toolbar to capture the current frame. Once the capture completes, PIX opens an analysis view where you can step through each API call, examine textures and buffers at any point in the frame, and debug shaders directly. |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +## Timing Capture |
| 70 | + |
| 71 | +A timing capture profiles GPU and CPU activity over a span of multiple frames, giving you a timeline view of how work is distributed. Unlike a GPU capture, a timing capture requires you to manually attach to the correct Chrome process. Launch the process as described above, then use **Attach to Process**: |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | +Select the Chrome process whose command line contains `--type=gpu-process`. |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +Once attached, click the **Timing Capture** button (stopwatch icon) on the PIX toolbar to begin recording, let the scene run for the desired duration, then click the button again to stop. The resulting timeline shows GPU queue utilization, command list execution, and hardware counter data, making it straightforward to identify bottlenecks such as GPU-bound passes, excessive state changes, or pipeline stalls. |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | +## Additional Resources |
| 84 | + |
| 85 | +This article covers how to set up PIX for use with Babylon.js and WebGPU. For a deeper understanding of PIX itself — including how to navigate captures, interpret timeline data, and debug shaders — the following resources from Microsoft are a great starting point. |
| 86 | + |
| 87 | +Analyzing frames with GPU captures |
| 88 | +https://learn.microsoft.com/en-us/windows/win32/direct3dtools/pix/articles/gpu-captures/pix-gpu-captures |
| 89 | + |
| 90 | +Timing Captures - The Timeline layout |
| 91 | +https://learn.microsoft.com/en-us/windows/win32/direct3dtools/pix/articles/timing-captures/layouts/pix-timing-captures-timeline-layout |
| 92 | + |
| 93 | +Videos showing how to use the PIX on Windows tool for performance tuning and debugging DirectX 12 games |
| 94 | +https://www.youtube.com/playlist?list=PLeHvwXyqearWuPPxh6T03iwX-McPG5LkB |
0 commit comments