Expand description
Allocating resource ids, and tracking the resources they refer to.
The wgpu_core
API uses identifiers of type Id<R>
to refer to
resources of type R
. For example, id::DeviceId
is an alias for
Id<markers::Device>
, and id::BufferId
is an alias for
Id<markers::Buffer>
. Id
implements Copy
, Hash
, Eq
, Ord
, and
of course Debug
.
Each Id
contains not only an index for the resource it denotes but
also a Backend indicating which wgpu
backend it belongs to. You
can use the gfx_select
macro to dynamically dispatch on an id’s
backend to a function specialized at compile time for a specific
backend. See that macro’s documentation for details.
Id
s also incorporate a generation number, for additional validation.
The resources to which identifiers refer are freed explicitly. Attempting to use an identifier for a resource that has been freed elicits an error result.
§Assigning ids to resources
The users of wgpu_core
generally want resource ids to be assigned
in one of two ways:
-
Users like
wgpu
wantwgpu_core
to assign ids to resources itself. For example,wgpu
expects to callGlobal::device_create_buffer
and have the return value indicate the newly created buffer’s id. -
Users like
player
and Firefox want to allocate ids themselves, and passGlobal::device_create_buffer
and friends the id to assign the new resource.
To accommodate either pattern, wgpu_core
methods that create
resources all expect an id_in
argument that the caller can use to
specify the id, and they all return the id used. For example, the
declaration of Global::device_create_buffer
looks like this:
impl Global {
/* ... */
pub fn device_create_buffer<A: HalApi>(
&self,
device_id: id::DeviceId,
desc: &resource::BufferDescriptor,
id_in: Input<G>,
) -> (id::BufferId, Option<resource::CreateBufferError>) {
/* ... */
}
/* ... */
}
Users that want to assign resource ids themselves pass in the id they
want as the id_in
argument, whereas users that want wgpu_core
itself to choose ids always pass ()
. In either case, the id
ultimately assigned is returned as the first element of the tuple.
Producing true identifiers from id_in
values is the job of an
crate::identity::IdentityManager
or ids will be received from outside through Option<Id>
arguments.
§Id allocation and streaming
Perhaps surprisingly, allowing users to assign resource ids themselves enables major performance improvements in some applications.
The wgpu_core
API is designed for use by Firefox’s WebGPU
implementation. For security, web content and GPU use must be kept
segregated in separate processes, with all interaction between them
mediated by an inter-process communication protocol. As web content uses
the WebGPU API, the content process sends messages to the GPU process,
which interacts with the platform’s GPU APIs on content’s behalf,
occasionally sending results back.
In a classic Rust API, a resource allocation function takes parameters
describing the resource to create, and if creation succeeds, it returns
the resource id in a Result::Ok
value. However, this design is a poor
fit for the split-process design described above: content must wait for
the reply to its buffer-creation message (say) before it can know which
id it can use in the next message that uses that buffer. On a common
usage pattern, the classic Rust design imposes the latency of a full
cross-process round trip.
We can avoid incurring these round-trip latencies simply by letting the content process assign resource ids itself. With this approach, content can choose an id for the new buffer, send a message to create the buffer, and then immediately send the next message operating on that buffer, since it already knows its id. Allowing content and GPU process activity to be pipelined greatly improves throughput.
To help propagate errors correctly in this style of usage, when resource creation fails, the id supplied for that resource is marked to indicate as much, allowing subsequent operations using that id to be properly flagged as errors as well.
Structs§
- All the resources for a particular backend in a
crate::global::Global
.