Crate std140

This module contains types that may be used to define Rust struct types that match the GLSL std140 memory layout.

Std140 is a standardized memory layout for GLSL shader interface blocks (e.g. uniform blocks). An interface block is a group op typed GLSL variables. For details on the layout rules for std140, please refer to the section 2.12.6.4 “Standard Uniform Block Layout” of the OpenGL ES 3.0 Specification.

This module aims to make it easy to construct and manipulate a block of std140 compatible memory as a Rust struct, such that the struct’s memory layout will match a GLSL interface block if every block member is pairwise type-compatible with the struct field in the corresponding position. Position here relates to the order in which block members and struct fields are declared, e.g.: the 1st block member must be compatible with the 1st struct field, the 2nd block member must be compatible with the 2nd struct field, etc. The struct itself has to be marked with the #[repr_std140] attribute: this ensures the rust compiler will correctly order and align the fields.

For GLSL primitive types, compatibility is defined by the following mapping from GLSL types to std140 types:

• float: float
• vec2: vec2
• vec3: vec3
• vec4: vec4
• mat2: mat2x2
• mat3: mat3x3
• mat4: mat4x4
• mat2x2: mat2x2
• mat2x3: mat2x3
• mat2x4: mat2x4
• mat3x2: mat3x2
• mat3x3: mat3x3
• mat3x4: mat3x4
• mat4x2: mat4x2
• mat4x3: mat4x3
• mat4x4: mat4x4
• int: int
• ivec2: ivec2
• ivec3: ivec3
• ivec4: ivec4
• uint: uint
• uvec2: uvec2
• uvec3: uvec3
• uvec4: uvec4
• bool: boolean
• bvec2: bvec2
• bvec3: bvec3
• bvec4: bvec4

A GLSL struct type is compatible with a field if this field’s type is a Rust struct marked with #[repr_std140] and this struct’s fields are pair-wise compatible with the GLSL struct field in the corresponding position.

A GLSL array of GLSL type T with compatible type T_c (as defined above) and length N is compatible with a field of type std140::array<T_c, N>.

Example

Given the following GLSL declaration of an (uniform) interface block:

struct PointLight {
    vec3 position;
    float intensity;
}

layout(std140) uniform Uniforms {
    mat4 transform;
    vec3 ambient_light_color;
    PointLight lights[2];
}

The following will produce a Rust struct instance with a compatible memory layout:

#[std140::repr_std140]
struct PointLight {
    position: std140::vec3,
    intensity: std140::float,
}

#[std140::repr_std140]
struct Uniforms {
    transform: std140::mat4x4,
    ambient_light_color: std140::vec3,
    lights: std140::array<PointLight, 2>
}

let instance = Uniforms {
    transform: std140::mat4x4(
        std140::vec4(1.0, 0.0, 0.0, 0.0),
        std140::vec4(0.0, 1.0, 0.0, 0.0),
        std140::vec4(0.0, 0.0, 1.0, 0.0),
        std140::vec4(0.0, 0.0, 0.0, 1.0),
    ),
    ambient_light_color: std140::vec3(0.2, 0.2, 0.2),
    lights: std140::array![
        PointLight {
            position: std140::vec3(10.0, 0.0, 10.0),
            intensity: std140::float(0.5)
        },
        PointLight {
            position: std140::vec3(0.0, 10.0, 10.0),
            intensity: std140::float(0.8)
        },
    ]
};

Note that although the field names match the block member names in this example, this is not strictly necessary: only pairwise field-type compatibility is required.

Macros

array

Initializes a std140 array.

Structs

array

Represents an std140 compatible array.

bvec2

A column vector of 2 boolean values.

bvec3

A column vector of 3 boolean values.

bvec4

A column vector of 4 boolean values.

dmat2x2

A matrix with 2 columns and 2 rows, represented by 2 dvec2 vectors.

dmat2x3

A matrix with 2 columns and 3 rows, represented by 2 dvec3 vectors.

dmat2x4

A matrix with 2 columns and 4 rows, represented by 2 dvec4 vectors.

dmat3x2

A matrix with 3 columns and 2 rows, represented by 3 dvec2 vectors.

dmat3x3

A matrix with 3 columns and 3 rows, represented by 3 dvec3 vectors.

dmat3x4

A matrix with 3 columns and 4 rows, represented by 3 dvec4 vectors.

dmat4x2

A matrix with 4 columns and 2 rows, represented by 4 dvec2 vectors.

dmat4x3

A matrix with 4 columns and 3 rows, represented by 4 dvec3 vectors.

dmat4x4

A matrix with 4 columns and 4 rows, represented by 4 dvec4 vectors.

double

A 64-bit floating point value.

dvec2

A column vector of 2 double values.

dvec3

A column vector of 3 double values.

dvec4

A column vector of 4 double values.

float

A 32-bit floating point value.

int

A 32-bit signed integer value.

ivec2

A column vector of 2 int values.

ivec3

A column vector of 3 int values.

ivec4

A column vector of 4 int values.

mat2x2

A matrix with 2 columns and 2 rows, represented by 2 vec2 vectors.

mat2x3

A matrix with 2 columns and 3 rows, represented by 2 vec3 vectors.

mat2x4

A matrix with 2 columns and 4 rows, represented by 2 vec4 vectors.

mat3x2

A matrix with 3 columns and 2 rows, represented by 3 vec2 vectors.

mat3x3

A matrix with 3 columns and 3 rows, represented by 3 vec3 vectors.

mat3x4

A matrix with 3 columns and 4 rows, represented by 3 vec4 vectors.

mat4x2

A matrix with 4 columns and 2 rows, represented by 4 vec2 vectors.

mat4x3

A matrix with 4 columns and 3 rows, represented by 4 vec3 vectors.

mat4x4

A matrix with 4 columns and 4 rows, represented by 4 vec4 vectors.

uint

A 32-bit unsigned integer value.

uvec2

A column vector of 2 uint values.

uvec3

A column vector of 3 uint values.

uvec4

A column vector of 4 uint values.

vec2

A column vector of 2 float values.

vec3

A column vector of 3 float values.

vec4

A column vector of 4 float values.

Enums

boolean

A 32-bit boolean value.

Traits

ReprStd140

Marker trait for types that can be used as fields in structs marked with #[repr_std140].

Std140ArrayElement

Marker trait for types that can be used as the element type for std140 arrays.

Std140Struct

Marker trait for struct types that were marked with #[repr_std140].

Functions

dmat2x2

Initializes a dmat2x2

dmat2x3

Initializes a dmat2x3

dmat2x4

Initializes a dmat2x4

dmat3x2

Initializes a dmat3x2

dmat3x3

Initializes a dmat3x3

dmat3x4

Initializes a dmat3x4

dmat4x2

Initializes a dmat4x2

dmat4x3

Initializes a dmat4x3

dmat4x4

Initializes a dmat4x4

mat2x2

Initializes a mat2x2

mat2x3

Initializes a mat2x3

mat2x4

Initializes a mat2x4

mat3x2

Initializes a mat3x2

mat3x3

Initializes a mat3x3

mat3x4

Initializes a mat3x4

mat4x2

Initializes a mat4x2

mat4x3

Initializes a mat4x3

mat4x4

Initializes a mat4x4

Attribute Macros

repr_std140

Attribute macro that can be applied to a struct to ensure its representation is compatible with the std140 memory layout convention.