encase

The ArrayLength type is a helper designed to be used with the #[derive(ShaderType)] macro to solve limitations with the WGSL arrayLength() function.

In WGSL, arrayLength() can be unreliable because it might return a minimum of 1 due to minBindingSize calculations, or it might include padding at the end of a buffer as extra elements.

When you include ArrayLength as a field in a struct using #[derive(ShaderType)]:

• On Write: It automatically writes the actual length of the contained runtime-sized array as an u32 to the buffer.
• On Read: It reads that u32 value (representing the length) and ensures that a maximum of that many elements are read from the buffer, preventing the consumption of trailing padding as array elements.

ArrayLength is treated as a 4-byte u32 in the shader.

#[derive(ShaderType)]
struct MyStruct {
    len: ArrayLength,
    data: Vec<MyElement>, // This is the runtime-sized array
}

To prepare Rust structs for use in GPU buffers (like WGSL), derive the ShaderType trait. This allows the encase crate to calculate the correct memory layout, alignment, and size required by shaders.

Field Attributes

You can use the #[shader(...)] attribute on struct fields to control layout:

• #[shader(align(X))]: Sets the alignment to a power-of-2 u32 literal (e.g., #[shader(align(16))]).
• #[shader(size(X))]: Sets the size to a u32 literal.
• #[shader(size(runtime))]: Must be attached to the last field of a struct to denote a runtime-sized array.

Note on Generics

Attributes like align and size only work on fields whose types do not contain generic type parameters.

Examples

Simple Struct:

#[derive(ShaderType)]
struct AffineTransform2D {
    matrix: test_impl::Mat2x2f,
    translate: test_impl::Vec2f,
}

Struct with Runtime-Sized Array: Use the ArrayLength type to explicitly handle the length of the runtime-sized array.

#[derive(ShaderType)]
struct Positions {
    length: ArrayLength,
    #[shader(size(runtime))]
    positions: Vec<test_impl::Vec2f>
}

Complex Generic Struct:

#[derive(ShaderType)]
struct Complex< 
    'a, 
    'b: 'a, 
    E: 'a + ShaderType + ShaderSize, 
    T: 'b + ShaderType + ShaderSize, 
    const N: usize 
> {
    array: [&'a mut E; N],
    #[shader(size(runtime))]
    rts_array: &'a mut Vec<&'b T>,
}

The encase_derive crate provides the ShaderType derive macro to automatically implement traits required for mapping Rust structs to WGSL (WebGPU Shading Language) memory layouts. This ensures that your Rust data structures match the expected alignment and padding rules of GPU buffers.

You can use the #[shader(...)] attribute on struct fields to override default alignment or size behaviors.

Supported Attributes

• #[shader(align(N))]: Overrides the alignment of a field to N bytes. N must be a power of two.
• #[shader(size(N))]: Overrides the size of a field to N bytes. This is a static size.
• #[shader(size(runtime))]: Marks the last field of a struct as having a runtime-sized array. This is required if you want to use the ArrayLength type within the struct to represent the length of this array in the shader.

Requirements

• The struct must have named fields.
• Only the last field can be marked with size(runtime).
• If using ArrayLength for a field, the struct must also contain a field marked size(runtime).

```rust
#[derive(encase::ShaderType)]
struct MyUniform {
    #[shader(align(16))]
    data: f32,
    #[shader(size(runtime))]
    elements: encase::ArrayLength,
}

To make a collection (like Vec<T>) work as a runtime-sized array within a ShaderType struct, you must implement the ShaderType trait using the impl_rts_array! macro. This macro handles the complex logic of calculating strides, padding, and performing length-aware reads/writes.

Requirements

The type being implemented must:

1. Implement Length (to provide the current size).
2. Optionally implement Truncate (if the collection needs to be resized during reading).

Macro Syntax

impl_rts_array!($type; [generics]; using [capabilities])

• $type: The type you are implementing for (e.g., Vec<T>).
• $generics: (Optional) Any generic parameters.
• using: (Optional) Specifies which capabilities to bridge from the underlying type:
  • len: Maps the collection's length method to the Length trait.
  • truncate: Maps the collection's truncation method to the Truncate trait.

Examples

For Vec<T> (supports resizing):

impl_rts_array!(Vec<T>; using len truncate);

For LinkedList<T> (read-only length):

impl_rts_array!(LinkedList<T>; using len);

// Example for a Vec of custom elements
impl_rts_array!(Vec<MyElement>; using len truncate);

When packing multiple different data types into a single buffer, use DynamicStorageBuffer::new_with_alignment to ensure each entry starts at a specific alignment boundary (e.g., 64 bytes).

use encase::{ShaderType, DynamicStorageBuffer};

let mut byte_buffer: Vec<u8> = Vec::new();

// Create a buffer with a 64-byte alignment requirement
let mut buffer = DynamicStorageBuffer::new_with_alignment(&mut byte_buffer, 64);

// write() returns the offset where the data was written
let offsets = [
    buffer.write(&[5.; 10]).unwrap(),
    buffer.write(&vec![3u32; 20]).unwrap(),
    buffer.write(&test_impl::Vec3f::ONE).unwrap(),
];

// offsets will be [0, 64, 192]

use encase::{ShaderType, DynamicStorageBuffer};

let mut byte_buffer: Vec<u8> = Vec::new();

let mut buffer = DynamicStorageBuffer::new_with_alignment(&mut byte_buffer, 64);
let offsets = [
    buffer.write(&[5.; 10]).unwrap(),
    buffer.write(&vec![3u32; 20]).unwrap(),
    buffer.write(&test_impl::Vec3f::ONE).unwrap(),
];

// write byte_buffer to GPU

assert_eq!(offsets, [0, 64, 192]);

For data containing arrays whose length is determined at runtime, use the ArrayLength type and the #[shader(size(runtime))] attribute within your ShaderType struct. This works with StorageBuffer to handle the layout of variable-length data.

use encase::{ShaderType, ArrayLength, StorageBuffer};

#[derive(ShaderType)]
struct Positions {
    length: ArrayLength,
    #[shader(size(runtime))]
    positions: Vec<test_impl::Vec2f>
}

let mut positions = Positions {
    length: ArrayLength,
    positions: Vec::from([
        test_impl::Vec2f::from([4.5, 3.4]),
        test_impl::Vec2f::from([1.5, 7.4]),
        test_impl::Vec2f::from([4.3, 1.9]),
    ]),
};

let mut byte_buffer: Vec<u8> = Vec::new();
let mut buffer = StorageBuffer::new(&mut byte_buffer);
buffer.write(&positions).unwrap();

// To read back after GPU modification:
// byte_buffer[0] = 2; // e.g. changing length on GPU
// buffer.read(&mut positions).unwrap();

use encase::{ShaderType, ArrayLength, StorageBuffer};

#[derive(ShaderType)]
struct Positions {
    length: ArrayLength,
    #[shader(size(runtime))]
    positions: Vec<test_impl::Vec2f>
}

let mut positions = Positions {
    length: ArrayLength,
    positions: Vec::from([
        test_impl::Vec2f::from([4.5, 3.4]),
        test_impl::Vec2f::from([1.5, 7.4]),
        test_impl::Vec2f::from([4.3, 1.9]),
    ])
};

let mut byte_buffer: Vec<u8> = Vec::new();

let mut buffer = StorageBuffer::new(&mut byte_buffer);
buffer.write(&positions).unwrap();

// write byte_buffer to GPU

// change length on GPU side
byte_buffer[0] = 2;

// read byte_buffer from GPU

let mut buffer = StorageBuffer::new(&mut byte_buffer);
buffer.read(&mut positions).unwrap();

assert_eq!(positions.positions.len(), 2);