li_wgpu_core/
id.rs

1use crate::{Epoch, Index};
2use std::{cmp::Ordering, fmt, marker::PhantomData};
3use wgt::Backend;
4
5#[cfg(feature = "id32")]
6type IdType = u32;
7#[cfg(not(feature = "id32"))]
8type IdType = u64;
9#[cfg(feature = "id32")]
10type NonZeroId = std::num::NonZeroU32;
11#[cfg(not(feature = "id32"))]
12type NonZeroId = std::num::NonZeroU64;
13#[cfg(feature = "id32")]
14type ZippedIndex = u16;
15#[cfg(not(feature = "id32"))]
16type ZippedIndex = Index;
17
18const INDEX_BITS: usize = std::mem::size_of::<ZippedIndex>() * 8;
19const EPOCH_BITS: usize = INDEX_BITS - BACKEND_BITS;
20const BACKEND_BITS: usize = 3;
21const BACKEND_SHIFT: usize = INDEX_BITS * 2 - BACKEND_BITS;
22pub const EPOCH_MASK: u32 = (1 << (EPOCH_BITS)) - 1;
23type Dummy = hal::api::Empty;
24
25/// An identifier for a wgpu object.
26///
27/// An `Id<T>` value identifies a value stored in a [`Global`]'s [`Hub`]'s [`Storage`].
28/// `Storage` implements [`Index`] and [`IndexMut`], accepting `Id` values as indices.
29///
30/// ## Note on `Id` typing
31///
32/// You might assume that an `Id<T>` can only be used to retrieve a resource of
33/// type `T`, but that is not quite the case. The id types in `wgpu-core`'s
34/// public API ([`TextureId`], for example) can refer to resources belonging to
35/// any backend, but the corresponding resource types ([`Texture<A>`], for
36/// example) are always parameterized by a specific backend `A`.
37///
38/// So the `T` in `Id<T>` is usually a resource type like `Texture<Empty>`,
39/// where [`Empty`] is the `wgpu_hal` dummy back end. These empty types are
40/// never actually used, beyond just making sure you access each `Storage` with
41/// the right kind of identifier. The members of [`Hub<A>`] pair up each
42/// `X<Empty>` type with the resource type `X<A>`, for some specific backend
43/// `A`.
44///
45/// [`Global`]: crate::global::Global
46/// [`Hub`]: crate::hub::Hub
47/// [`Hub<A>`]: crate::hub::Hub
48/// [`Storage`]: crate::storage::Storage
49/// [`Texture<A>`]: crate::resource::Texture
50/// [`Index`]: std::ops::Index
51/// [`IndexMut`]: std::ops::IndexMut
52/// [`Registry`]: crate::hub::Registry
53/// [`Empty`]: hal::api::Empty
54#[repr(transparent)]
55#[cfg_attr(feature = "trace", derive(serde::Serialize), serde(into = "SerialId"))]
56#[cfg_attr(
57    feature = "replay",
58    derive(serde::Deserialize),
59    serde(from = "SerialId")
60)]
61#[cfg_attr(
62    all(feature = "serde", not(feature = "trace")),
63    derive(serde::Serialize)
64)]
65#[cfg_attr(
66    all(feature = "serde", not(feature = "replay")),
67    derive(serde::Deserialize)
68)]
69pub struct Id<T>(NonZeroId, PhantomData<T>);
70
71// This type represents Id in a more readable (and editable) way.
72#[allow(dead_code)]
73#[cfg_attr(feature = "trace", derive(serde::Serialize))]
74#[cfg_attr(feature = "replay", derive(serde::Deserialize))]
75enum SerialId {
76    // The only variant forces RON to not ignore "Id"
77    Id(Index, Epoch, Backend),
78}
79#[cfg(feature = "trace")]
80impl<T> From<Id<T>> for SerialId {
81    fn from(id: Id<T>) -> Self {
82        let (index, epoch, backend) = id.unzip();
83        Self::Id(index, epoch, backend)
84    }
85}
86#[cfg(feature = "replay")]
87impl<T> From<SerialId> for Id<T> {
88    fn from(id: SerialId) -> Self {
89        match id {
90            SerialId::Id(index, epoch, backend) => TypedId::zip(index, epoch, backend),
91        }
92    }
93}
94
95impl<T> Id<T> {
96    /// # Safety
97    ///
98    /// The raw id must be valid for the type.
99    pub unsafe fn from_raw(raw: NonZeroId) -> Self {
100        Self(raw, PhantomData)
101    }
102
103    #[allow(dead_code)]
104    pub(crate) fn dummy(index: u32) -> Valid<Self> {
105        Valid(Id::zip(index, 1, Backend::Empty))
106    }
107
108    pub fn backend(self) -> Backend {
109        match self.0.get() >> (BACKEND_SHIFT) as u8 {
110            0 => Backend::Empty,
111            1 => Backend::Vulkan,
112            2 => Backend::Metal,
113            3 => Backend::Dx12,
114            4 => Backend::Dx11,
115            5 => Backend::Gl,
116            _ => unreachable!(),
117        }
118    }
119}
120
121impl<T> Copy for Id<T> {}
122
123impl<T> Clone for Id<T> {
124    fn clone(&self) -> Self {
125        *self
126    }
127}
128
129impl<T> fmt::Debug for Id<T> {
130    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
131        let (index, epoch, backend) = self.unzip();
132        formatter
133            .debug_struct("Id")
134            .field("index", &index)
135            .field("epoch", &epoch)
136            .field("backend", &backend)
137            .finish()
138    }
139}
140
141impl<T> std::hash::Hash for Id<T> {
142    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
143        self.0.hash(state);
144    }
145}
146
147impl<T> PartialEq for Id<T> {
148    fn eq(&self, other: &Self) -> bool {
149        self.0 == other.0
150    }
151}
152
153impl<T> Eq for Id<T> {}
154
155impl<T> PartialOrd for Id<T> {
156    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
157        self.0.partial_cmp(&other.0)
158    }
159}
160
161impl<T> Ord for Id<T> {
162    fn cmp(&self, other: &Self) -> Ordering {
163        self.0.cmp(&other.0)
164    }
165}
166
167/// An internal ID that has been checked to point to
168/// a valid object in the storages.
169#[repr(transparent)]
170#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
171#[cfg_attr(feature = "trace", derive(serde::Serialize))]
172#[cfg_attr(feature = "replay", derive(serde::Deserialize))]
173pub(crate) struct Valid<I>(pub I);
174
175/// Trait carrying methods for direct `Id` access.
176///
177/// Most `wgpu-core` clients should not use this trait. Unusual clients that
178/// need to construct `Id` values directly, or access their components, like the
179/// WGPU recording player, may use this trait to do so.
180pub trait TypedId: Copy {
181    fn zip(index: Index, epoch: Epoch, backend: Backend) -> Self;
182    fn unzip(self) -> (Index, Epoch, Backend);
183    fn into_raw(self) -> NonZeroId;
184}
185
186#[allow(trivial_numeric_casts)]
187impl<T> TypedId for Id<T> {
188    fn zip(index: Index, epoch: Epoch, backend: Backend) -> Self {
189        assert_eq!(0, epoch >> EPOCH_BITS);
190        assert_eq!(0, (index as IdType) >> INDEX_BITS);
191        let v = index as IdType
192            | ((epoch as IdType) << INDEX_BITS)
193            | ((backend as IdType) << BACKEND_SHIFT);
194        Id(NonZeroId::new(v).unwrap(), PhantomData)
195    }
196
197    fn unzip(self) -> (Index, Epoch, Backend) {
198        (
199            (self.0.get() as ZippedIndex) as Index,
200            (((self.0.get() >> INDEX_BITS) as ZippedIndex) & (EPOCH_MASK as ZippedIndex)) as Index,
201            self.backend(),
202        )
203    }
204
205    fn into_raw(self) -> NonZeroId {
206        self.0
207    }
208}
209
210pub type AdapterId = Id<crate::instance::Adapter<Dummy>>;
211pub type SurfaceId = Id<crate::instance::Surface>;
212// Device
213pub type DeviceId = Id<crate::device::Device<Dummy>>;
214pub type QueueId = DeviceId;
215// Resource
216pub type BufferId = Id<crate::resource::Buffer<Dummy>>;
217pub type StagingBufferId = Id<crate::resource::StagingBuffer<Dummy>>;
218pub type TextureViewId = Id<crate::resource::TextureView<Dummy>>;
219pub type TextureId = Id<crate::resource::Texture<Dummy>>;
220pub type SamplerId = Id<crate::resource::Sampler<Dummy>>;
221// Binding model
222pub type BindGroupLayoutId = Id<crate::binding_model::BindGroupLayout<Dummy>>;
223pub type PipelineLayoutId = Id<crate::binding_model::PipelineLayout<Dummy>>;
224pub type BindGroupId = Id<crate::binding_model::BindGroup<Dummy>>;
225// Pipeline
226pub type ShaderModuleId = Id<crate::pipeline::ShaderModule<Dummy>>;
227pub type RenderPipelineId = Id<crate::pipeline::RenderPipeline<Dummy>>;
228pub type ComputePipelineId = Id<crate::pipeline::ComputePipeline<Dummy>>;
229// Command
230pub type CommandEncoderId = CommandBufferId;
231pub type CommandBufferId = Id<crate::command::CommandBuffer<Dummy>>;
232pub type RenderPassEncoderId = *mut crate::command::RenderPass;
233pub type ComputePassEncoderId = *mut crate::command::ComputePass;
234pub type RenderBundleEncoderId = *mut crate::command::RenderBundleEncoder;
235pub type RenderBundleId = Id<crate::command::RenderBundle<Dummy>>;
236pub type QuerySetId = Id<crate::resource::QuerySet<Dummy>>;
237
238#[test]
239fn test_id_backend() {
240    for &b in &[
241        Backend::Empty,
242        Backend::Vulkan,
243        Backend::Metal,
244        Backend::Dx12,
245        Backend::Dx11,
246        Backend::Gl,
247    ] {
248        let id: Id<()> = Id::zip(1, 0, b);
249        let (_id, _epoch, backend) = id.unzip();
250        assert_eq!(id.backend(), b);
251        assert_eq!(backend, b);
252    }
253}
254
255#[test]
256fn test_id() {
257    let last_index = ((1u64 << INDEX_BITS) - 1) as Index;
258    let indexes = [1, last_index / 2 - 1, last_index / 2 + 1, last_index];
259    let epochs = [1, EPOCH_MASK / 2 - 1, EPOCH_MASK / 2 + 1, EPOCH_MASK];
260    let backends = [
261        Backend::Empty,
262        Backend::Vulkan,
263        Backend::Metal,
264        Backend::Dx12,
265        Backend::Dx11,
266        Backend::Gl,
267    ];
268    for &i in &indexes {
269        for &e in &epochs {
270            for &b in &backends {
271                let id: Id<()> = Id::zip(i, e, b);
272                let (index, epoch, backend) = id.unzip();
273                assert_eq!(index, i);
274                assert_eq!(epoch, e);
275                assert_eq!(backend, b);
276            }
277        }
278    }
279}
li_wgpu_core/id.rs

li_wgpu_core/
id.rs
