crevice_notan

Crates.iocrevice_notan
lib.rscrevice_notan
version0.13.0
sourcesrc
created_at2022-07-10 18:16:32.861143
updated_at2023-04-24 23:00:38.534654
descriptionCreate GLSL-compatible versions of structs with explicitly-initialized padding
homepagehttps://github.com/Nazariglez/crevice_notan
repositoryhttps://github.com/Nazariglez/crevice_notan
max_upload_size
id623243
size80,594
Nazarí González (Nazariglez)

documentation

https://docs.rs/crevice

README

Crevice

Fork of crevice made to be used internally from notan because derive macros cannot be reexported.

GitHub CI Status crevice on crates.io crevice docs

Crevice creates GLSL-compatible versions of types through the power of derive macros. Generated structures provide an as_bytes method to allow safely packing data into buffers for uploading.

Generated structs also implement bytemuck::Zeroable and bytemuck::Pod for use with other libraries.

Crevice is similar to glsl-layout, but supports types from many math crates, can generate GLSL source from structs, and explicitly initializes padding to remove one source of undefined behavior.

Crevice has support for many Rust math libraries via feature flags, and most other math libraries by use of the mint crate. Crevice currently supports:

  • mint 0.5, enabled by default
  • cgmath 0.18, using the cgmath feature
  • nalgebra 0.31, using the nalgebra feature
  • glam 0.23, using the glam feature

PRs are welcome to add or update math libraries to Crevice.

If your math library is not supported, it's possible to define structs using the types from mint and convert your math library's types into mint types. This is supported by most Rust math libraries.

Your math library may require you to turn on a feature flag to get mint support. For example, cgmath requires the "mint" feature to be enabled to allow conversions to and from mint types.

Examples

Single Value

Uploading many types can be done by deriving AsStd140 and using as_std140 and as_bytes to turn the result into bytes.

uniform MAIN {
    mat3 orientation;
    vec3 position;
    float scale;
} main;
use crevice::std140::AsStd140;

#[derive(AsStd140)]
struct MainUniform {
    orientation: mint::ColumnMatrix3<f32>,
    position: mint::Point3<f32>,
    scale: f32,
}

let value = MainUniform {
    orientation: [
        [1.0, 0.0, 0.0],
        [0.0, 1.0, 0.0],
        [0.0, 0.0, 1.0],
    ].into(),
    position: [1.0, 2.0, 3.0].into(),
    scale: 4.0,
};

let value_std140 = value.as_std140();

upload_data_to_gpu(value_std140.as_bytes());

Sequential Types

More complicated data can be uploaded using the std140 Writer type.

struct PointLight {
    vec3 position;
    vec3 color;
    float brightness;
};

buffer POINT_LIGHTS {
    uint len;
    PointLight[] lights;
} point_lights;
use crevice::std140::{self, AsStd140};

#[derive(AsStd140)]
struct PointLight {
    position: mint::Point3<f32>,
    color: mint::Vector3<f32>,
    brightness: f32,
}

let lights = vec![
    PointLight {
        position: [0.0, 1.0, 0.0].into(),
        color: [1.0, 0.0, 0.0].into(),
        brightness: 0.6,
    },
    PointLight {
        position: [0.0, 4.0, 3.0].into(),
        color: [1.0, 1.0, 1.0].into(),
        brightness: 1.0,
    },
];

let target_buffer = map_gpu_buffer_for_write();
let mut writer = std140::Writer::new(target_buffer);

let light_count = lights.len() as u32;
writer.write(&light_count)?;

// Crevice will automatically insert the required padding to align the
// PointLight structure correctly. In this case, there will be 12 bytes of
// padding between the length field and the light list.

writer.write(lights.as_slice())?;

unmap_gpu_buffer();

Features

  • std (default): Enables std::io::Write-based structs.
  • cgmath: Enables support for types from cgmath.
  • nalgebra: Enables support for types from nalgebra.
  • glam: Enables support for types from glam.

Minimum Supported Rust Version (MSRV)

Crevice supports Rust 1.58.0 and newer due to use of new const fn features.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Commit count: 87

cargo fmt