Ownership

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).

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 pointers.

Note that such functions will not free any previously-allocated data: overwriting an output structure without first freeing members 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.

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 outputs passed from the API to callbacks (such as message strings in most callbacks) are always owned by the API and guaranteed to be valid only during the callback's execution, after which the pointers passed to the callback are no longer valid.