Skip to content

Explainer: command encoding #1637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvark merged 1 commit into from
Apr 15, 2021
Merged

Explainer: command encoding #1637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions explainer/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,13 +378,18 @@ provide information for debugging tools (error messages, native profilers like X
Every WebGPU object creation descriptor has a member `label` which sets the initial value of the
attribute.

Additionally, parts of command buffers can be labeled with debug markers and debug groups.
See [[#command-encoding-debug]].

For both debugging (dev tools messages) and telemetry, implementations can choose to report some
kind of "stack trace" in their error messages, taking advantage of object debug labels.
For example:

```
<myQueue>.submit failed:
- commands[0] (<mainColorPass>) was invalid:
- in the debug group <environment>:
- in the debug group <tree 123>:
- in setIndexBuffer, indexBuffer (<mesh3.indices>) was invalid:
- in createBuffer, desc.usage was invalid (0x89)
```
Expand Down Expand Up @@ -787,6 +792,31 @@ Some alternatives are mentioned in issue [#747](https://github.com/gpuweb/gpuweb

## Command Encoding and Submission ## {#command-encoding}

Many operations in WebGPU are purely GPU-side operations that don't use data from the CPU.
These operations are not issued directly; instead, they are encoded into `GPUCommandBuffer`s
via the builder-like `GPUCommandEncoder` interface, then later sent to the GPU with
`gpuQueue.submit()`.
This design is used by the underlying native APIs as well. It provides several benefits:

- Command buffer encoding is independent of other state, allowing encoding (and command buffer
validation) work to utilize multiple CPU threads.
- Provides a larger chunk of work at once, allowing the GPU driver to do more global
optimization, especially in how it schedules work across the GPU hardware.

### Debug Markers and Debug Groups ### {#command-encoding-debug}

For error messages and debugging tools, it is possible to label work inside a command buffer.
(See [[#errors-errorscopes-labels]].)

- `insertDebugMarker(markerLabel)` marks a point in a stream of commands.
- `pushDebugGroup(groupLabel)`/`popDebugGroup()` nestably demarcate sub-streams of commands.
This can be used e.g. to label which part of a command buffer corresponds to different objects
or parts of a scene.

### Passes ### {#command-encoding-passes}

Issue: Briefly explain passes?


## Pipelines ## {#pipelines}

Expand Down
2 changes: 1 addition & 1 deletion spec/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5338,7 +5338,7 @@ must be well nested.

: <dfn>insertDebugMarker(markerLabel)</dfn>
::
Marks the end of a labeled group of commands for the {{GPUCommandEncoder}}.
Marks a point in a stream of commands with a label string.

<div algorithm=GPUCommandEncoder.insertDebugMarker>
**Called on:** {{GPUCommandEncoder}} |this|.
Expand Down