Objects in webgpu.h are refcounted via the AddRef and Release functions. The refcount only changes when these methods are called explicitly (not, for example, in wgpuCommandEncoderFinish or wgpuQueueSubmit).

Applications are not required to maintain refs to WebGPU objects which are internally used by other WebGPU objects (CommandBuffer→BindGroup, BindGroup→TextureView, TextureView→Texture, etc.); webgpu.h implementations must maintain internal references, as needed, to be internally memory safe. These internal references do not make it safe to use objects that have ever reached an external refcount of 0.

Memory for variable-sized outputs from the API (message strings, capability arrays, etc.) is managed in different ways depending on whether they are returned values or callback arguments.

Returned with Ownership

Objects returned directly from the API (e.g. WGPUBuffer from wgpuDeviceCreateBuffer and WGPUTexture via WGPUSurfaceTexture from wgpuSurfaceGetCurrentTexture) start with one application-owned ref. The application must Release this ref before losing the pointer. (The returned object may also have other refs, either API-owned refs or existing application-owned refs, but this should not be relied upon.)

Variable-sized outputs returned from the API (e.g. the strings in WGPUAdapterInfo, from wgpuAdapterGetInfo) are application-owned. The application must call the appropriate FreeMembers function (e.g. wgpuAdapterInfoFreeMembers) before losing the member pointers. FreeMembers functions do not traverse the struct chain and must be called separately on each struct (that has a FreeMembers function) in the chain.

Note that such functions will not free any previously-allocated data: overwriting an output structure without first releasing ownership will leak the allocations; e.g.:

Overwriting the strings in WGPUAdapterInfo with wgpuAdapterGetInfo without first calling wgpuAdapterInfoFreeMembers.
Overwriting the texture in WGPUSurfaceTexture with wgpuSurfaceGetCurrentTexture without first calling wgpuTextureRelease.

Note also that some structs with FreeMembers functions may be used as both inputs and outputs. In this case FreeMembers must only be used if the member allocations were made by the webgpu.h implementation (as an output), not if they were made by the application (as an input).

Callback Arguments

Output arguments passed from the API to application callbacks include objects and message strings, which are passed to most callbacks.

Passed with Ownership

Usually, object arguments passed to callbacks start with one application-owned ref, which the application must free before losing the pointer.

Passed without Ownership

A.k.a. "pass by reference".

Sometimes, object arguments passed to callbacks are non-owning (such as the WGPUDevice in WGPUDeviceLostCallback) - the application doesn't need to free them.

Variable-sized and struct-chained outputs passed from the API to callbacks (such as message strings in most callbacks) are always owned by the API and passed without ownership. They are guaranteed to be valid only during the callback's execution, after which the pointers passed to the callback are no longer valid.

Implementation-Allocated Struct Chain

Some callback arguments contain chained structs. These are allocated by the implementation. They:

May be chained in any order.
May contain chain members not known to the application (e.g. implementation-specific extensions or extensions added in a later version of webgpu.h).

Applications must handle these cases gracefully, by traversing the struct chain and ignoring any structs in the chain that have WGPUChainedStruct::sType values other than the ones they're interested in.

Implementations may consider injecting bogus structs into such chains, e.g. {.sType=0xDEADBEEF} in debug builds, to help developers catch invalid assumptions in their applications.