spirv_std/
vector.rs

1//! Traits related to vectors.
2
3use crate::sealed::Sealed;
4use crate::{Scalar, ScalarOrVector};
5use core::num::NonZeroUsize;
6use glam::{Vec3Swizzles, Vec4Swizzles};
7
8/// Abstract trait representing a SPIR-V vector type.
9///
10/// To implement this trait, your struct must be marked with:
11/// ```no_run
12/// #[cfg_attr(target_arch = "spirv", rust_gpu::vector::v1)]
13/// # struct Bla(f32, f32);
14/// ```
15///
16/// This places these additional constraints on your type, checked by the spirv codegen:
17/// * must be a struct
18/// * members must be a spirv [`Scalar`] type, which includes:
19///   * Floating-point type: f32, f64
20///   * Integer type: u8, u16, u32, u64, i8, i16, i32, i64
21///   * Boolean type: bool
22/// * all members must be of the same primitive type
23/// * must have 2, 3 or 4 vector components / members
24/// * type must derive Copy, Clone, Default
25///
26/// The spirv codegen backend will then emit your type as an `OpTypeVector` instead of an `OpTypeStruct`. The layout of
27/// your type is unaffected, the size, alignment and member offsets will follow standard rustc layout rules. This hint
28/// does nothing on other target platforms.
29///
30/// See the SPIRV spec on [Types](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#_types) and the
31/// "Data rules" in the [Universal Validation Rules](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#_universal_validation_rules).
32///
33/// # Example
34/// ```no_run
35/// #[derive(Copy, Clone, Default)]
36/// #[cfg_attr(target_arch = "spirv", rust_gpu::vector::v1)]
37/// struct MyColor {
38///     r: f32,
39///     b: f32,
40///     g: f32,
41/// }
42/// ```
43///
44///
45/// # Safety
46/// * Must only be implemented on types that the spirv codegen emits as valid `OpTypeVector`. This includes all structs
47///   marked with `#[rust_gpu::vector::v1]`, like [`glam`]'s non-SIMD "scalar" vector types.
48/// * `VectorOrScalar::DIM == N`, since const equality is behind rustc feature `associated_const_equality`
49// Note(@firestar99) I would like to have these two generics be associated types instead. Doesn't make much sense for
50// a vector type to implement this interface multiple times with different Scalar types or N, after all.
51// While it's possible with `T: Scalar`, it's not with `const N: usize`, since some impl blocks in `image::params` need
52// to be conditional on a specific N value. And you can only express that with const generics, but not with associated
53// constants due to lack of const generics support in rustc.
54pub unsafe trait Vector<T: Scalar, const N: usize>: ScalarOrVector<Scalar = T> {}
55
56macro_rules! impl_vector {
57    ($($ty:ty: [$scalar:ty; $n:literal];)+) => {
58        $(
59            impl Sealed for $ty {}
60            unsafe impl ScalarOrVector for $ty {
61                type Scalar = $scalar;
62                const N: NonZeroUsize = NonZeroUsize::new($n).unwrap();
63            }
64            unsafe impl Vector<$scalar, $n> for $ty {}
65        )+
66    };
67}
68
69impl_vector! {
70    glam::Vec2: [f32; 2];
71    glam::Vec3: [f32; 3];
72    glam::Vec3A: [f32; 3];
73    glam::Vec4: [f32; 4];
74    glam::DVec2: [f64; 2];
75    glam::DVec3: [f64; 3];
76    glam::DVec4: [f64; 4];
77    glam::UVec2: [u32; 2];
78    glam::UVec3: [u32; 3];
79    glam::UVec4: [u32; 4];
80    glam::IVec2: [i32; 2];
81    glam::IVec3: [i32; 3];
82    glam::IVec4: [i32; 4];
83    glam::BVec2: [bool; 2];
84    glam::BVec3: [bool; 3];
85    glam::BVec4: [bool; 4];
86}
87
88/// Trait that implements slicing of a vector into a scalar or vector of lower dimensions, by
89/// ignoring the higher dimensions
90pub trait VectorTruncateInto<T> {
91    /// Slices the vector into a lower dimensional type by ignoring the higher components
92    fn truncate_into(self) -> T;
93}
94
95macro_rules! vec_trunc_impl {
96    ($a:ty, $b:ty, $self:ident $(.$($e:tt)*)?) => {
97        impl VectorTruncateInto<$a> for $b {
98            fn truncate_into($self) -> $a {
99                $self $(. $($e)*)?
100            }
101        }
102    };
103}
104macro_rules! vec_trunc_impls {
105    ($s:ty, $v2:ty, $v3:ty, $v4:ty) => {
106        vec_trunc_impl! {$s, $s, self}
107        vec_trunc_impl! {$s, $v2, self.x}
108        vec_trunc_impl! {$s, $v3, self.x}
109        vec_trunc_impl! {$s, $v4, self.x}
110
111        vec_trunc_impl! {$v2, $v2, self}
112        vec_trunc_impl! {$v2, $v3, self.xy()}
113        vec_trunc_impl! {$v2, $v4, self.xy()}
114
115        vec_trunc_impl! {$v3, $v3, self}
116        vec_trunc_impl! {$v3, $v4, self.xyz()}
117
118        vec_trunc_impl! {$v4, $v4, self}
119    };
120}
121
122vec_trunc_impls! { f32, glam::Vec2, glam::Vec3, glam::Vec4 }
123vec_trunc_impls! { f64, glam::DVec2, glam::DVec3, glam::DVec4 }
124vec_trunc_impls! { i32, glam::IVec2, glam::IVec3, glam::IVec4 }
125vec_trunc_impls! { u32, glam::UVec2, glam::UVec3, glam::UVec4 }
spirv_std/vector.rs

spirv_std/
vector.rs
