cyborg/src/mesh/mod.rs

//! Dynamic mesh data storage.
//!
//! Meshes are based on ECS-like archetypes. Each pool contains a set of mesh
//! "attributes," which can be either vertex attributes, indices of different
//! formats (u8, u16, u32), or in the future, fixed-size mesh chunklets too.
//! The mesh pool itself is agnostic to specific rendering implementation. It
//! has no implicit knowledge of what a vertex position, normal, or texture
//! coordinate is, or even what an index is.
//!
//! Multiple attributes can have the same layout. For example, a rudimentary
//! mesh format might use three 32-bit floating point values (`[f32; 3]`) for
//! both vertex position and vertex normals. In this case, positions and normals
//! would have different [AttrIds][AttrId] to distuingish them, and must each be
//! registered to the pool. Once an attribute is registered in a pool instance,
//! it cannot be unregistered, although the mesh pool may free GPU buffers for
//! unused attribute pools.
//!
//! Meshes are pooled by [groups][MeshGroup], so all mesh data in a group
//! shares the same memory. This allows the rendering pipeline to operate on as
//! much mesh data simultaneously as possible without rebinding buffers,
//! enabling some highly-efficient rendering techniques like bindless forward
//! rendering, bindless vertex skinning, and mesh shading.
//!
//! However, because a mesh groups' underlying buffers are so large, they cannot
//! be resized without copying all of the mesh data within to a new allocation,
//! putting a lot of pressure on the GPU's memory bus and causing massive lag
//! spikes. Instead, an entirely new group must be created to store more mesh
//! data. In practice, new groups will not be created often, again due to the
//! large size of their underlying buffers.
//!
//! When a mesh is loaded, the pool is searched for a group that has spare room
//! for all of the mesh's attributes. If one is found, the pool copies the mesh's
//! attribute data into the pool's internal staging buffer, which is later
//! copied by the GPU into the corresponding attribute pools in the selected
//! group. If no group has enough free space to store all of the attributes, a
//! new group is created.
//!
//! Staging buffers are fixed-size, so when a large amount of mesh data is loaded
//! at once and the pool can't fit it all into an available staging buffer, the
//! memory is instead copied to a CPU-side spillover buffer, and GPU transfer is
//! deferred to a future staging pass. Because of this, meshes are not guaranteed
//! to be available for drawing on the frame that they are loaded.
//!
//! TODO: mesh coherency
//! TODO: make spillover buffers GPU-transferrable on iGPUs

use slab::Slab;
use std::sync::Arc;
use smallvec::SmallVec;
use std::collections::HashMap;

pub mod attr;
pub mod group;
pub mod staging;

use attr::*;
use group::*;
use staging::*;

/// An error that can be returned when allocating a mesh.
pub enum PoolError {
    TooBig,
    NoMoreRoom,
    InvalidIndex,
    AttrTaken,
    AttrUnregistered,
    MismatchedId,
    MismatchedLayout,
}

/// The number of attributes a mesh can have before they're moved to the heap.
pub const MAX_MESH_INLINE_ATTRIBUTES: usize = 16;

/// The data and layout of a single mesh attribute.
pub struct AttrBuffer {
    pub id: AttrId,
    pub layout: AttrLayout,
    pub count: usize,
    pub data: Vec<u8>,
}

/// A mesh and all of its attributes.
///
/// An attribute ID can be used multiple times in a mesh, corresponding to
/// multiple allocations within an [AttrPool].
pub struct MeshBuffer {
    pub attributes: SmallVec<[AttrBuffer; MAX_MESH_INLINE_ATTRIBUTES]>,
}

/// A handle to an allocated mesh.
pub struct MeshHandle {
    pub(crate) group: usize,
    pub(crate) sub: usize,
}

/// The top-level mesh data pool.
pub struct MeshPool {
    staging: StagingPool,
    attr_store: Arc<AttrStore>,
    groups: Vec<MeshGroup>,
}

impl MeshPool {
    pub fn new(attr_store: Arc<AttrStore>) -> Self {
        Self {
            staging: StagingPool::new(1_000_000),
            attr_store,
            groups: Default::default(),
        }
    }

    pub fn load(&mut self, buf: &MeshBuffer) -> Result<MeshHandle, PoolError> {
        for group in self.groups.iter_mut() {
            match group.load(buf) {
                Ok((handle, copies)) => {
                    self.staging.queue_copies(copies);
                    return Ok(handle);
                }
                Err(PoolError::NoMoreRoom) => {}
                Err(e) => return Err(e),
            }
        }

        let group_index = self.groups.len();
        self.groups.push(MeshGroup::new(group_index, self.attr_store.clone()));
        let group = self.groups.get_mut(group_index).unwrap();

        let (handle, copies) = group.load(buf)?;
        self.staging.queue_copies(copies);
        Ok(handle)
    }
}