use crate::{Epoch, Index}; use std::{cmp::Ordering, fmt, marker::PhantomData}; use wgt::Backend; #[cfg(feature = "id32")] type IdType = u32; #[cfg(not(feature = "id32"))] type IdType = u64; #[cfg(feature = "id32")] type NonZeroId = std::num::NonZeroU32; #[cfg(not(feature = "id32"))] type NonZeroId = std::num::NonZeroU64; #[cfg(feature = "id32")] type ZippedIndex = u16; #[cfg(not(feature = "id32"))] type ZippedIndex = Index; const INDEX_BITS: usize = std::mem::size_of::() * 8; const EPOCH_BITS: usize = INDEX_BITS - BACKEND_BITS; const BACKEND_BITS: usize = 3; const BACKEND_SHIFT: usize = INDEX_BITS * 2 - BACKEND_BITS; pub const EPOCH_MASK: u32 = (1 << (EPOCH_BITS)) - 1; type Dummy = hal::api::Empty; /// An identifier for a wgpu object. /// /// An `Id` value identifies a value stored in a [`Global`]'s [`Hub`]'s [`Storage`]. /// `Storage` implements [`Index`] and [`IndexMut`], accepting `Id` values as indices. /// /// ## Note on `Id` typing /// /// You might assume that an `Id` can only be used to retrieve a resource of /// type `T`, but that is not quite the case. The id types in `wgpu-core`'s /// public API ([`TextureId`], for example) can refer to resources belonging to /// any backend, but the corresponding resource types ([`Texture`], for /// example) are always parameterized by a specific backend `A`. /// /// So the `T` in `Id` is usually a resource type like `Texture`, /// where [`Empty`] is the `wgpu_hal` dummy back end. These empty types are /// never actually used, beyond just making sure you access each `Storage` with /// the right kind of identifier. The members of [`Hub`] pair up each /// `X` type with the resource type `X`, for some specific backend /// `A`. /// /// [`Global`]: crate::hub::Global /// [`Hub`]: crate::hub::Hub /// [`Hub`]: crate::hub::Hub /// [`Storage`]: crate::hub::Storage /// [`Texture`]: crate::resource::Texture /// [`Index`]: std::ops::Index /// [`IndexMut`]: std::ops::IndexMut /// [`Registry`]: crate::hub::Registry /// [`Empty`]: hal::api::Empty #[repr(transparent)] #[cfg_attr(feature = "trace", derive(serde::Serialize), serde(into = "SerialId"))] #[cfg_attr( feature = "replay", derive(serde::Deserialize), serde(from = "SerialId") )] #[cfg_attr( all(feature = "serde", not(feature = "trace")), derive(serde::Serialize) )] #[cfg_attr( all(feature = "serde", not(feature = "replay")), derive(serde::Deserialize) )] pub struct Id(NonZeroId, PhantomData); // This type represents Id in a more readable (and editable) way. #[allow(dead_code)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] enum SerialId { // The only variant forces RON to not ignore "Id" Id(Index, Epoch, Backend), } #[cfg(feature = "trace")] impl From> for SerialId { fn from(id: Id) -> Self { let (index, epoch, backend) = id.unzip(); Self::Id(index, epoch, backend) } } #[cfg(feature = "replay")] impl From for Id { fn from(id: SerialId) -> Self { match id { SerialId::Id(index, epoch, backend) => TypedId::zip(index, epoch, backend), } } } impl Id { /// # Safety /// /// The raw id must be valid for the type. pub unsafe fn from_raw(raw: NonZeroId) -> Self { Self(raw, PhantomData) } #[allow(dead_code)] pub(crate) fn dummy(index: u32) -> Valid { Valid(Id::zip(index, 1, Backend::Empty)) } pub fn backend(self) -> Backend { match self.0.get() >> (BACKEND_SHIFT) as u8 { 0 => Backend::Empty, 1 => Backend::Vulkan, 2 => Backend::Metal, 3 => Backend::Dx12, 4 => Backend::Dx11, 5 => Backend::Gl, _ => unreachable!(), } } } impl Copy for Id {} impl Clone for Id { fn clone(&self) -> Self { Self(self.0, PhantomData) } } impl fmt::Debug for Id { fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result { self.unzip().fmt(formatter) } } impl std::hash::Hash for Id { fn hash(&self, state: &mut H) { self.0.hash(state); } } impl PartialEq for Id { fn eq(&self, other: &Self) -> bool { self.0 == other.0 } } impl Eq for Id {} impl PartialOrd for Id { fn partial_cmp(&self, other: &Self) -> Option { self.0.partial_cmp(&other.0) } } impl Ord for Id { fn cmp(&self, other: &Self) -> Ordering { self.0.cmp(&other.0) } } /// An internal ID that has been checked to point to /// a valid object in the storages. #[repr(transparent)] #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)] #[cfg_attr(feature = "trace", derive(serde::Serialize))] #[cfg_attr(feature = "replay", derive(serde::Deserialize))] pub(crate) struct Valid(pub I); /// Trait carrying methods for direct `Id` access. /// /// Most `wgpu-core` clients should not use this trait. Unusual clients that /// need to construct `Id` values directly, or access their components, like the /// WGPU recording player, may use this trait to do so. pub trait TypedId: Copy { fn zip(index: Index, epoch: Epoch, backend: Backend) -> Self; fn unzip(self) -> (Index, Epoch, Backend); fn into_raw(self) -> NonZeroId; } #[allow(trivial_numeric_casts)] impl TypedId for Id { fn zip(index: Index, epoch: Epoch, backend: Backend) -> Self { assert_eq!(0, epoch >> EPOCH_BITS); assert_eq!(0, (index as IdType) >> INDEX_BITS); let v = index as IdType | ((epoch as IdType) << INDEX_BITS) | ((backend as IdType) << BACKEND_SHIFT); Id(NonZeroId::new(v).unwrap(), PhantomData) } fn unzip(self) -> (Index, Epoch, Backend) { ( (self.0.get() as ZippedIndex) as Index, (((self.0.get() >> INDEX_BITS) as ZippedIndex) & (EPOCH_MASK as ZippedIndex)) as Index, self.backend(), ) } fn into_raw(self) -> NonZeroId { self.0 } } pub type AdapterId = Id>; pub type SurfaceId = Id; // Device pub type DeviceId = Id>; pub type QueueId = DeviceId; // Resource pub type BufferId = Id>; pub type StagingBufferId = Id>; pub type TextureViewId = Id>; pub type TextureId = Id>; pub type SamplerId = Id>; // Binding model pub type BindGroupLayoutId = Id>; pub type PipelineLayoutId = Id>; pub type BindGroupId = Id>; // Pipeline pub type ShaderModuleId = Id>; pub type RenderPipelineId = Id>; pub type ComputePipelineId = Id>; // Command pub type CommandEncoderId = CommandBufferId; pub type CommandBufferId = Id>; pub type RenderPassEncoderId = *mut crate::command::RenderPass; pub type ComputePassEncoderId = *mut crate::command::ComputePass; pub type RenderBundleEncoderId = *mut crate::command::RenderBundleEncoder; pub type RenderBundleId = Id>; pub type QuerySetId = Id>; #[test] fn test_id_backend() { for &b in &[ Backend::Empty, Backend::Vulkan, Backend::Metal, Backend::Dx12, Backend::Dx11, Backend::Gl, ] { let id: Id<()> = Id::zip(1, 0, b); let (_id, _epoch, backend) = id.unzip(); assert_eq!(id.backend(), b); assert_eq!(backend, b); } } #[test] fn test_id() { let last_index = ((1u64 << INDEX_BITS) - 1) as Index; let indexes = [1, last_index / 2 - 1, last_index / 2 + 1, last_index]; let epochs = [1, EPOCH_MASK / 2 - 1, EPOCH_MASK / 2 + 1, EPOCH_MASK]; let backends = [ Backend::Empty, Backend::Vulkan, Backend::Metal, Backend::Dx12, Backend::Dx11, Backend::Gl, ]; for &i in &indexes { for &e in &epochs { for &b in &backends { let id: Id<()> = Id::zip(i, e, b); let (index, epoch, backend) = id.unzip(); assert_eq!(index, i); assert_eq!(epoch, e); assert_eq!(backend, b); } } } }