[][src]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 is advantageous, for reasons of 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 soak::{RawTable, Columns};

#[derive(Copy, Clone, 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.offset(i as isize);
        let velocity = &mut *velocities.offset(i as isize);
        position.0 += velocity.0;
        position.1 += velocity.1;
    }
}

Re-exports

pub use soak_derive::Columns;

Structs

Field

A handle to a field of in struct S of type F.

RawTable

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

Traits

Columns

Layout metadata required to use a struct in a RawTable.