webgpu-debug-helper

A WebGPU debugging helper script

This script makes it easier to debug WebGPU apps.

note: this script is a work in progress.

You can use it in your own projects via a script OR, you can use it as an extension.

At the moment, if you want to use it to help debug workers, you'll need to use this script version.

What does it do?

• It makes as many errors as possible to return the line they happened on

  This is in contrast to normal WebGPU where errors are returned asynchronously and so the command that caused the error is long forgotten.

• It adds errors to command encoders and pass encoders (these throw)

  In normal WebGPU, command encoders and pass encoders often do not report errors. Rather, they record the error, mark the encoder as invalid, and then only report the error when the encoder is ended/finished. This can make it hard to find errors as they might have happened hundreds or thousands of calls ago.

  With this script, many of these types of errors will be generated immediately.

Usage:

First off, I recommend the extension as it's just easier to use. Generally you don't want to run with this script enabled. Rather, run your code as normal. When you see an error, if it's not obvious, turn on this script via the extension and check the JavaScript console. You should see messages with stacks. Click the links in the stacks to go to the code that generated the error.

Otherwise, to use the script directly:

import './webgpu-debug-helper.js';

or

import 'https://greggman.github.io/webgpu-debug-helper/dist/0.x/webgpu-debug-helper.js';

or

<script type="module" src="https://greggman.github.io/webgpu-debug-helper/dist/0.x/webgpu-debug-helper.js" crossorigin>

or from the npm package.

There is nothing else to do. The webgpu-debug-helper will wrap the WebGPU API and start generating error messages.

If you wanted to import programmatically you could do something like this

if (debug) {
  await import('./webgpu-debug-helper.js');
}

Alternative Usage

There is also a script at https://greggman.github.io/webgpu-debug-helper/show-errors/show-errors.js which you can use alternatively.

This one has the advantage that it's smaller and just wraps the API in calls to pushErrorScope, popErrorScope, pushDebugGroup and popDebugGroup. Do this allows it to provide a stack trace where errors happened.

The advantage is it's a simpler script and less likely to have bugs. Especially as the API evolves. The disadvantage the error will happen later and you'll get a stack trace but it will not stop where the error happened. Note: the main script doesn't always stop where they error happened either but it does stop for more situations where as this alternative stops at none.

Development

Clone the repo and install it locally.

npm ci
npm run start

Now open the browser to http://localhost:8080/test/timeout=0&src=true

Testing with three.js

If you have the three.js repo install along side in a folder named three.js as in

+-somefolder
  +-webgpu-dev-extension
  +-three.js

Then npm run test-threejs will attempt to each of the three.js webgpu examples and inject the helper. Ideally there should be no errors.

You can skip the first N tests with -- --skip-count=<number> (the first -- is required).

show-errors.js

show-errors/show-errors.js is also generated by the build.

show-errors.js wraps calls to pushErrorScope and popErrorScope around every method of GPUDevice and GPUQueue. It is used in the webgpu-dev-extension.

License

MIT