Errors are surfaced in several ways.
Most errors only result from incorrect use of the API and should not need to be handled at runtime. However, a few (WGPUErrorType_OutOfMemory, WGPUErrorType_Internal) are potentially useful to handle.
These behave the same way as in the WebGPU JavaScript API specification. They are receivable via wgpuDevicePopErrorScope() and WGPUDeviceDescriptor::uncapturedErrorCallbackInfo.
These errors include:
These behave similarly to the Promise-returning JavaScript APIs. Instead of there being two callbacks like in JavaScript (one for resolve and one for reject), there is a single callback which receives a status code, and depending on the status, either a valid result with an empty message string ({NULL, 0}
), or an invalid result with a non-empty message string.
These errors include:
webgpu.h
. See specific documentation to determine how each error is exposed.Generally these will return some kind of failure status (like WGPUStatus_Error) or NULL
, and produce an Implementation-Defined Logging message.
Entry points may also specify that they produce "implementation-defined logging". These messages are logged in an implementation defined way (e.g. to an implementation-specific callback, or to a logging runtime). They are intended to be intended to be read by humans, useful primarily for development and crash reporting.
A struct-chaining error happens when the WGPUSType of a struct in a struct chain is not valid for that chain.
Struct chains which are used in device-timeline validation/operations (e.g. WGPUBufferDescriptor in wgpuDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error.
Operations which take out-struct-chains (e.g. WGPULimits, in wgpuAdapterGetLimits and wgpuDeviceGetLimits, but not in WGPUDeviceDescriptor) handle struct-chaining errors as follows: