#[repr(C)]pub struct Padded<T, const N: usize> { /* private fields */ }Expand description
A newtype wrapper around T, with N bytes of trailing padding.
In Vulkan, the layout of buffer contents is not necessarily as one would expect from the type
signature in the shader code. For example, the extended layout or std140 layout in GLSL,
which is used for uniform buffers by default, requires that array elements are aligned to 16
bytes at minimum. That means that even if the array contains a scalar type like u32 for
example, it must be aligned to 16 bytes. We can not enforce that with primitive Rust types
alone. In such cases, we can use Padded to enforce correct alignment on the Rust side.
See also the shader module documentation for more information about layout in shaders.
Examples
Aligning struct members
Consider this GLSL code:
layout(binding = 0) uniform MyData {
int x;
vec3 y;
vec4 z;
};
By default, the alignment rules require that y and z are placed at an offset that is an
integer multiple of 16. However, x is only 4 bytes, which means that there must be 12 bytes
of padding between x and y. Furthermore, y is only 12 bytes, which means that there must
be 4 bytes of padding between y and z.
We can model this in Rust using Padded:
#[derive(BufferContents)]
#[repr(C)]
struct MyData {
x: Padded<i32, 12>,
y: Padded<[f32; 3], 4>,
z: [f32; 4],
}
let data = MyData {
x: Padded(42),
y: Padded([1.0, 2.0, 3.0]),
z: [10.0; 4],
};But note that this layout is extremely suboptimal. What you should do instead is reorder your fields such that you don’t need any padding:
layout(binding = 0) uniform MyData {
vec3 y;
int x;
vec4 z;
};
#[derive(BufferContents)]
#[repr(C)]
struct MyData {
y: [f32; 3],
x: i32,
z: [f32; 4],
}This way, the fields are aligned naturally. But reordering fields is not always an option: the
notable case being when your structure only contains vec3s and vec4s, or vec3s and
vec2s, so that there are no scalar fields to fill the gaps with.
Aligning array elements
If you need an array of vec3s, then that necessitates that each array element has 4 bytes of
trailing padding. The same goes for a matrix with 3 rows, each column will have to have 4 bytes
of trailing padding (assuming its column-major).
We can model those using Padded too:
layout(binding = 0) uniform MyData {
vec3 x[10];
mat3 y;
};
#[derive(BufferContents)]
#[repr(C)]
struct MyData {
x: [Padded<[f32; 3], 4>; 10],
y: [Padded<[f32; 3], 4>; 3],
}Another example would be if you have an array of scalars or vec2s inside a uniform block:
layout(binding = 0) uniform MyData {
int x[10];
vec2 y[10];
};
By default, arrays inside uniform blocks must have their elements aligned to 16 bytes at minimum, which would look like this in Rust:
#[derive(BufferContents)]
#[repr(C)]
struct MyData {
x: [Padded<i32, 12>; 10],
y: [Padded<[f32; 2], 8>; 10],
}But note again, that this layout is suboptimal. You can instead use a buffer block instead of the uniform block, if memory usage could become an issue:
layout(binding = 0) buffer MyData {
int x[10];
vec2 y[10];
};
#[derive(BufferContents)]
#[repr(C)]
struct MyData {
x: [i32; 10],
y: [[f32; 2]; 10],
}You may also want to consider using the uniform_buffer_standard_layout feature.
Trait Implementations§
source§impl<T, const N: usize> BufferContents for Padded<T, N>where
T: BufferContents,
impl<T, const N: usize> BufferContents for Padded<T, N>where T: BufferContents,
source§const LAYOUT: BufferContentsLayout = _
const LAYOUT: BufferContentsLayout = _
source§impl<T, const N: usize> Ord for Padded<T, N>where
T: Ord,
impl<T, const N: usize> Ord for Padded<T, N>where T: Ord,
source§impl<T, const N: usize> PartialEq for Padded<T, N>where
T: PartialEq,
impl<T, const N: usize> PartialEq for Padded<T, N>where T: PartialEq,
source§impl<T, const N: usize> PartialOrd for Padded<T, N>where
T: PartialOrd,
impl<T, const N: usize> PartialOrd for Padded<T, N>where T: PartialOrd,
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self and other) and is used by the <=
operator. Read more