GPU Profiling (#675)

* GPU profiling page

* lint

* tiny update

* added renderdoc section

* Update docs/user-manual/optimization/gpu-profiling.md

Co-authored-by: Will Eastcott <[email protected]>

* Update docs/user-manual/optimization/gpu-profiling.md

Co-authored-by: Will Eastcott <[email protected]>

* Apply suggestions from code review

Co-authored-by: Will Eastcott <[email protected]>

---------

Co-authored-by: Martin Valigursky <[email protected]>
Co-authored-by: Will Eastcott <[email protected]>

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

docs/user-manual/optimization/gpu-profiling.md

@@ -0,0 +1,65 @@
+---
+title: GPU Profiling
+sidebar_position: 2
+---
+
+This section explains how to use native GPU profilers to capture and analyze WebGL or WebGPU frames, enabling debugging and performance profiling of GPU operations.
+
+This is particularly challenging on the Web platform, as web applications typically run within a sandboxed environment, which inherently limits compatibility and integration with native GPU profilers. This page outlines tested options available on certain platforms.
+
+## WebGPU application on macOS with Apple Silicon
+
+* Clone WebKit:
+
+```bash
+git clone https://github.com/WebKit/WebKit.git WebKit
+```
+
+* Build MiniBrowser (this takes around 30 minutes):
+
+```bash
+cd WebKit
+Tools/Scripts/build-webkit -cmakeargs="-DENABLE_WEBGPU_BY_DEFAULT=1" --release
+```
+
+* Start the MiniBrowser, specify url to your web application:
+
+```bash
+__XPC_METAL_CAPTURE_ENABLED=1 Tools/Scripts/run-minibrowser --release --url https://playcanvas.github.io/
+```
+
+* Configure the number of frames to capture from a separate command-line interface window. This defaults to 1.
+
+```bash
+notifyutil -s com.apple.WebKit.WebGPU.CaptureFrame 2
+```
+
+* At the appropriate time, capture the frame(s):
+
+```bash
+notifyutil -p com.apple.WebKit.WebGPU.CaptureFrame
+```
+
+This generates a capture file, and the command-line window in which you started the MiniBrowser logs a path to it. For example:
+
+```bash
+Success starting GPU frame capture at path file:///var/folders/m3/cnrw6k214hxd0hq1rf7cy3w40000gn/T/com.apple.WebKit.GPU+org.webkit.MiniBrowser/8C9372EF-1254-4FC5-8CA9-730FB
+```
+
+* Double-click this file to open it in Xcode, then click the Replay button in the dialog that appears. This enables you to inspect frame draw calls, analyze resources, debug shaders, and gather performance metrics.
+
+![Xcode](/img/user-manual/optimization/gpu-profiling/xcode-webgpu.png)
+
+## WebGL application on macOS with Apple Silicon
+
+The steps above only enable capturing for WebGPU-based applications. To capture a WebGL application, you can embed a small WebGPU application on the same page and capture typically 2–3 frames. This process captures both the WebGPU application and the WebGL application since they both utilize the Metal API under the hood.
+
+For PlayCanvas applications, this process can be simplified by using the provided script. Simply attach it to any single entity in your scene:
+
+https://github.com/playcanvas/engine/blob/main/scripts/utils/mac-gpu-profiling.js
+
+## WebGL and WebGPU application on Windows
+
+Please read this article on how to use Microsoft's PIX to capture GPU frames using the Chrome browser: https://toji.dev/webgpu-profiling/pix
+
+Alternatively, read this article on how to use RenderDoc to capture GPU frames: https://edw.is/renderdoc-webgl/