[Feature] Default buffer properties to DEVICE_LOCAL for static geometry

[vmarcella]

Overview

Buffer defaults bias toward CPU-visible memory (adds COPY_DST), even for static vertex buffers that are uploaded once and never modified. This results in suboptimal memory placement on discrete GPUs and unnecessary overhead. Static geometry should default to DEVICE_LOCAL memory, with CPU-visible properties reserved for buffers that require CPU updates (uniform streams, dynamic meshes).

Current State

Properties::default() returns CPU_VISIBLE:

// crates/lambda-rs/src/render/buffer.rs
impl Default for Properties {
 fn default() -> Self {
 Properties::CPU_VISIBLE
 }
}

Additionally, build_from_mesh hardcodes CPU_VISIBLE for vertex buffers created from meshes:

// crates/lambda-rs/src/render/buffer.rs
pub fn build_from_mesh(
 mesh: &Mesh,
 gpu: &Gpu,
) -> Result<Buffer, &'static str> {
 let builder = Self::new();
 return builder
 .with_length(std::mem::size_of_val(mesh.vertices()))
 .with_usage(Usage::VERTEX)
 .with_properties(Properties::CPU_VISIBLE)
 .with_buffer_type(BufferType::Vertex)
 .build(gpu, mesh.vertices().to_vec());
}

This means static meshes that are loaded once and never modified are placed in CPU-visible memory, which on discrete GPUs means system RAM accessed over PCIe rather than fast VRAM.

Scope

Goals:

• Default Properties to DEVICE_LOCAL for optimal GPU performance
• Update build_from_mesh to use DEVICE_LOCAL
• Provide clear guidance on when to use CPU_VISIBLE vs DEVICE_LOCAL

Non-Goals:

• Automatic memory tier selection based on update frequency
• Staging buffer abstraction for uploads (future work)

Proposed API

// crates/lambda-rs/src/render/buffer.rs
impl Default for Properties {
 fn default() -> Self {
 Properties::DEVICE_LOCAL // Changed from CPU_VISIBLE
 }
}

// build_from_mesh updated to use DEVICE_LOCAL
pub fn build_from_mesh(
 mesh: &Mesh,
 gpu: &Gpu,
) -> Result<Buffer, &'static str> {
 let builder = Self::new();
 return builder
 .with_length(std::mem::size_of_val(mesh.vertices()))
 .with_usage(Usage::VERTEX)
 .with_properties(Properties::DEVICE_LOCAL) // Changed from CPU_VISIBLE
 .with_buffer_type(BufferType::Vertex)
 .build(gpu, mesh.vertices().to_vec());
}

Usage guidance:

// Static geometry (loaded once, never updated) - use default DEVICE_LOCAL
let static_mesh_buffer = BufferBuilder::new()
 .with_usage(Usage::VERTEX)
 .build(&gpu, vertices)?;

// Dynamic geometry (updated per-frame) - explicit CPU_VISIBLE
let dynamic_buffer = BufferBuilder::new()
 .with_usage(Usage::VERTEX)
 .with_properties(Properties::CPU_VISIBLE)
 .build(&gpu, initial_vertices)?;

// Uniform buffers (updated frequently) - explicit CPU_VISIBLE
let uniform_buffer = BufferBuilder::new()
 .with_usage(Usage::UNIFORM)
 .with_properties(Properties::CPU_VISIBLE)
 .build(&gpu, uniform_data)?;

Acceptance Criteria

• Properties::default() returns DEVICE_LOCAL
• build_from_mesh uses DEVICE_LOCAL
• Documentation updated explaining DEVICE_LOCAL vs CPU_VISIBLE tradeoffs
• Examples using uniform buffers explicitly specify CPU_VISIBLE
• Migration guide for users relying on implicit CPU_VISIBLE
• Unit tests updated to reflect new defaults

Affected Crates

lambda-rs

Notes

• This is a breaking change for users who rely on implicit CPU_VISIBLE for buffers they update from the CPU
• Migration: add explicit .with_properties(Properties::CPU_VISIBLE) for dynamic buffers
• Future work: staging buffer helper for efficient DEVICE_LOCAL uploads