Crate soak

Soak

Soak is a library for transforming data from an Array-of-Structs layout to a Struct-of-Arrays layout.

The natural way to work with a collection of objects in Rust is to represent them as structs, often placed in a [Vec]. This lays out each individual object’s fields together in memory:

[field 1, field 2][field 1, field 2][field 1, field 2]...

Often it improves performance to interleave the objects’ fields, so that individual fields are grouped together instead:

[field 1, field 1, field 1][field 2, field 2, field 2]...

The primary tools provided by Soak are the Columns trait, which records a struct’s layout; and the RawTable type, the eponymous struct of arrays. They can be used together like this:

use core::ptr;
use dioptre::Fields;
use soak::{RawTable, Columns};

#[derive(Fields, Columns)]
struct GameObject {
    position: (f32, f32),
    velocity: (f32, f32),
    health: f32,
}

unsafe fn process(table: &mut RawTable<GameObject>) {
    let positions = table.ptr(GameObject::position);
    let velocities = table.ptr(GameObject::velocity);
    let healths = table.ptr(GameObject::health);

    for i in 0..table.capacity() {
        let position = &mut *positions.add(i);
        let velocity = &mut *velocities.add(i);
        position.0 += velocity.0;
        position.1 += velocity.1;
    }
}

Structs

RawTable

A raw allocation containing parallel arrays of T’s fields.

Traits

Columns

Metadata required to use a struct in a RawTable.

Derive Macros

Columns