This repository was archived by the owner on May 6, 2025. It is now read-only.
Repository navigation
Expand file tree
/
Copy pathdoc.go
More file actions
52 lines (51 loc) · 2.81 KB
/
Copy pathdoc.go
File metadata and controls
52 lines (51 loc) · 2.81 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// # API stability
//
// WebGPU, webgpu.h, and wgpu are still in development and change regularly. Our
// bindings works with specific versions of webgpu.h and wgpu only, and will
// regularly be updated to track changes, which means our API might change as well.
//
// # Error handling
//
// Error handling in WebGPU, webgpu.h and wgpu is still in flux and incomplete,
// making it impossible to handle some errors cleanly, as they will panic in
// Rust and cause SIGABRT. The errors that _can_ be handled fall into one of the
// following categories:
//
// Failure to acquire an adapter or device will return a Go error.
//
// By default, all validation errors, out-of-memory errors, and internal errors
// will panic in Go.
//
// Using [Device.PushErrorScope] and [Device.PopErrorScope], validation errors,
// out-of-memory errors, and internal errors can be caught and turned into Go
// errors. This allows, for example, to handle fallible memory allocations.
//
// The alternative to explicit use of error scopes would've been to return Go
// errors from most functions in this package. However, the vast majority of
// validation errors are programmer mistakes, which should panic, not return
// errors. Similarly, a lot of out of memory situations are fatal. Furthermore,
// instead of checking the error for every function call, it often suffices to
// check them for a sequence of function calls, for example to check that
// rendering a full frame succeeded. This can be accomplished much easier with
// error scopes. Finally, fine-grained use of error scopes may lead to
// unnecessary synchronisation between the CPU and GPU.
//
// Some functions are internally implemented using callbacks, such as
// [Surface.CurrentTexture]. Errors that occur in such functions do not use
// error scopes and are instead passed to the callbacks, and we turn them into
// Go errors.
//
// Device loss will invoke a callback. WebGPU intends that most API continues to
// work, by becoming no-ops, after a device has been lost, so that device loss
// can be handled reliably via the callback. This hasn't been fully implemented
// yet, and handling device loss reliably is error-prone, no pun intended.
//
// Due to a combination of the designs of webgpu.h and wgpu, some errors related
// to resources that do not belong to a device cannot be handled, as they cause
// panics inside Rust. This applies to surface creation and configuration, for
// example.
package wgpu
// https://github.com/gfx-rs/wgpu/issues/5132 - Mark the device as lost when hal produces a device lost error
// https://github.com/gfx-rs/wgpu/issues/1624 - Figure out how to deal with device loss
// https://github.com/gpuweb/gpuweb/issues/1629 - Make lost devices appear to function as much as possible
// https://github.com/gfx-rs/wgpu-native/issues/113 - When will panics become errors that can be handled?