Struct InstanceDesc3D 

pub struct InstanceDesc3D {
    pub pos_attr: Pos3DATTR,
    pub rot_attr: Rot3DATTR,
    pub scale_attr: Scale3DATTR,
    pub col_attr: ColATTR,
    pub cus_attrs: Vec<CustomATTR>,
}

Descriptor for preparing 3D instance data before uploading it to the GPU.

An instance buffer packs per-instance attributes (position, rotation, scale, colour, and custom attributes) into a single interleaved GPU buffer. This type collects attribute data on the CPU side and interleaves them when ship is called.

Attribute layout

Attributes appear in this fixed order within the interleaved stride:

1. pos — 3 × f32 (12 bytes)
2. rot — 4 × f32 quaternion (16 bytes)
3. scale — 3 × f32 (12 bytes)
4. col — 4 × f32 RGBA (16 bytes)
5. custom attributes, in insertion order

Any of these may be omitted (left empty). The stride shrinks accordingly.

Example

let mut desc = InstanceDesc3D::empty();

for i in 0..100 {
    desc.pos_attr.push([i as f32 * 2.0, 0.0, 0.0]);
    desc.col_attr.push([1.0, 0.0, 0.0, 1.0]);
}

// desc.ship() transfers the interleaved data to a GPU buffer.

Fields

pos_attr: Pos3DATTR

rot_attr: Rot3DATTR

scale_attr: Scale3DATTR

col_attr: ColATTR

cus_attrs: Vec<CustomATTR>

Implementations

impl InstanceDesc3D

pub fn empty() -> Self

Creates an empty descriptor with no attributes.

Push per-instance data into the individual attribute fields before calling ship.

pub fn from_positions(positions: &[Vector3<f32>]) -> Self

Builds a descriptor from an array of 3D positions.

All other attribute fields remain empty.

pub fn from_transforms(transforms: &[Matrix4<f32>]) -> Self

Decomposes a slice of 4×4 transformation matrices into position, rotation (quaternion), and scale attributes.

This is a convenience constructor for users who already have transform matrices. It assumes no shear and extracts a unit quaternion from the upper-left 3×3 sub-matrix.

Panics

May produce degenerate quaternions when a scale component is zero.

pub fn attach_custom_attr(&mut self, attr: CustomATTR) -> &mut Self

Appends a custom (user-defined) attribute.

Custom attribute names must not collide with the reserved names iPos, iRot, iScale, or iColor, and must be unique among themselves.

Returns &mut self for chaining.

pub fn ship(&self) -> OpticResult<InstanceBuffer>

Interleaves all non-empty attributes and uploads them to a new GPU buffer.

Returns an InstanceBuffer ready for use in instanced draws.

Errors

• Returns an error if all attributes are empty (no data to upload).
• Returns an error if non-empty attributes have mismatched element counts.
• Returns an error if custom attribute names collide with reserved names or each other.