meshoptimizer-rs 0.2.6

Rust port of meshoptimizer 1.3 with byte-identical output. Covers mesh simplification, meshlets, cluster LOD, vertex/index compression analysis, remeshing and optional parallel batch APIs and audited SIMD codecs.
Documentation
//! A Rust port of [meshoptimizer](https://github.com/zeux/meshoptimizer) 1.3.
//!
//! Every ported function produces byte-identical output to meshoptimizer 1.3
//! (scalar build). Differential runs against the C++ library, seeded sweeps,
//! fuzzing and a wasm32 identity check prove this on the recorded inputs.
//!
//! The crate is safe Rust except for one module, `codec::simd`, which holds the SIMD kernels for vertex decoding, EXT filters and meshlet decoding. Every `unsafe` block there has a written safety argument, and every SIMD path must produce the same bytes as the scalar safe-Rust path, which is the reference and the fallback. Build with `default-features = false` (adding `std` if needed) to compile no `unsafe` code; output is identical. Cargo feature unification applies: if any other crate in the dependency graph enables `simd`, the module is compiled for the whole graph. Simplification, optimization, index decoding and all encoders contain no `unsafe` in either configuration. See the [safety audit](https://github.com/Tavrin/meshoptimizer-rs/blob/main/src/codec/simd/SAFETY.md).
//!
//! The crate needs no C++ toolchain.
//! It supports `no_std` with `alloc`. Invalid input returns a typed [`Error`]
//! instead of undefined behaviour. A reusable [`Workspace`] holds scratch
//! memory, makes every allocation fallible and enforces per-call memory and
//! work [`Limits`].
//!
//! This is an independent project. It is not affiliated with meshoptimizer or
//! its author. Coverage, measured performance and the parity records are in the
//! [README](https://github.com/Tavrin/meshoptimizer-rs#readme).
//!
//! Coverage includes vertex processing, simplification, meshlets and codecs
//! (phases 0.1–0.4), analyzers, opacity maps, tangents, normals and remeshing
//! (phase 0.5), optional parallel batches (phase 0.6), and SIMD codecs (phase 0.7).
//! Cluster-LOD requires `clusterlod`; batches require `parallel` and `std`.
//! Normal generation and remeshing require `experimental`.
//!
//! # Simplify a mesh
//!
//! ```
//! use meshoptimizer_rs::{simplify, Positions, SimplifyOptions, SimplifySettings, Workspace};
//!
//! let positions = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]];
//! let indices = [0, 1, 2, 2, 1, 3];
//! let mut workspace = Workspace::default();
//!
//! let settings = SimplifySettings {
//!     target_index_count: 3,
//!     target_error: 0.01,
//!     options: SimplifyOptions::EMPTY,
//! };
//! let lod = simplify(&indices, Positions::from_packed(&positions), settings, &mut workspace)?;
//! println!("{} indices, relative error {}", lod.indices.len(), lod.error);
//! # Ok::<(), meshoptimizer_rs::Error>(())
//! ```
//!
//! # Optimize for the vertex cache, then for overdraw
//!
//! ```
//! use meshoptimizer_rs::{optimize_overdraw, optimize_vertex_cache, Positions, Workspace};
//!
//! let positions = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]];
//! let indices = [0, 1, 2, 2, 1, 3];
//! let mut workspace = Workspace::default();
//!
//! let cached = optimize_vertex_cache(&indices, positions.len(), &mut workspace)?;
//! let ordered = optimize_overdraw(&cached, Positions::from_packed(&positions), 1.05, &mut workspace)?;
//! assert_eq!(ordered.len(), indices.len());
//! # Ok::<(), meshoptimizer_rs::Error>(())
//! ```
//!
//! # Build meshlets
//!
//! ```
//! use meshoptimizer_rs::{build_meshlets, MeshletSettings, Positions, Workspace};
//!
//! let positions = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]];
//! let indices = [0, 1, 2, 2, 1, 3];
//! let mut workspace = Workspace::default();
//!
//! // 64 vertices and 124 triangles per meshlet; cone weight 0.25.
//! let built = build_meshlets(
//!     &indices,
//!     Positions::from_packed(&positions),
//!     MeshletSettings::default(),
//!     0.25,
//!     &mut workspace,
//! )?;
//! for meshlet in &built.meshlets {
//!     let start = meshlet.vertex_offset as usize;
//!     let vertices = &built.vertices[start..start + meshlet.vertex_count as usize];
//!     println!("{} triangles over vertices {:?}", meshlet.triangle_count, vertices);
//! }
//! # Ok::<(), meshoptimizer_rs::Error>(())
//! ```
//!
//! # Compress vertex and index buffers
//!
//! The [`codec`] module reads and writes the `EXT_meshopt_compression` formats.
//! Buffers are little-endian bytes. The format version and level are set per
//! call instead of through global setters.
//!
//! ```
//! use meshoptimizer_rs::codec::{
//!     decode_index_buffer, decode_vertex_buffer, encode_index_buffer, encode_vertex_buffer,
//!     IndexEncoding, VertexEncoding,
//! };
//! use meshoptimizer_rs::Workspace;
//!
//! let positions: [[f32; 3]; 4] = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]];
//! let indices = [0, 1, 2, 2, 1, 3];
//! let mut workspace = Workspace::default();
//!
//! let vertex_bytes: Vec<u8> = positions.iter().flatten().flat_map(|v| v.to_le_bytes()).collect();
//! let packed = encode_vertex_buffer(&vertex_bytes, 4, 12, VertexEncoding::DEFAULT, &mut workspace)?;
//! assert_eq!(decode_vertex_buffer(4, 12, &packed, &mut workspace)?, vertex_bytes);
//!
//! let packed = encode_index_buffer(&indices, IndexEncoding::DEFAULT, &mut workspace)?;
//! let decoded = decode_index_buffer(indices.len(), 4, &packed, &mut workspace)?; // u32 bytes
//! assert_eq!(decoded.len(), indices.len() * 4);
//! # Ok::<(), meshoptimizer_rs::Error>(())
//! ```
//!
//! # Features
//!
//! - `std` (default): implements `std::error::Error` for [`Error`]. Disable
//!   default features for `no_std`; an allocator is still required.
//! - `clusterlod`: the cluster-LOD builder from upstream's `demo/clusterlod.h`.
//!   It reproduces the pinned demo exactly; it is not a stable upstream API.
//! - `experimental`: upstream functions and options marked experimental.
//! - `parallel`: ordered Rayon batch APIs for independent meshes and buffer
//!   views; enables `std`. See the `parallel` module for limits and error semantics.
#![deny(unsafe_code)]
#![cfg_attr(not(feature = "simd"), forbid(unsafe_code))]
#![deny(
    unsafe_op_in_unsafe_fn,
    clippy::undocumented_unsafe_blocks,
    clippy::multiple_unsafe_ops_per_block,
    clippy::missing_safety_doc
)]
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(missing_docs)]

extern crate alloc;

/// Compiles and runs every `rust` block in the README as a doctest.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;

mod budget;

mod analyze;
mod cache;
pub mod codec;
mod error;
mod input;
mod math;
#[cfg(feature = "experimental")]
mod normal;
mod opacity;
mod overdraw;
mod quantize;
mod remap;

mod raster;
#[cfg(feature = "experimental")]
mod remesh;
mod simplify;
mod strip;
mod tangent;
mod workspace;
pub use simplify::{
    simplify, simplify_into, simplify_points, simplify_points_into, simplify_prune,
    simplify_prune_into, simplify_scale, simplify_sloppy, simplify_sloppy_into,
    simplify_with_attributes, simplify_with_attributes_into, simplify_with_update, SimplifiedMesh,
    SimplifyOptions, SimplifyResult, SimplifySettings,
};

pub use analyze::{
    analyze_vertex_cache, analyze_vertex_fetch, VertexCacheStatistics, VertexFetchStatistics,
};
pub use cache::{
    optimize_vertex_cache, optimize_vertex_cache_fifo, optimize_vertex_cache_fifo_in_place,
    optimize_vertex_cache_fifo_into, optimize_vertex_cache_in_place, optimize_vertex_cache_into,
    optimize_vertex_cache_strip, optimize_vertex_cache_strip_in_place,
    optimize_vertex_cache_strip_into,
};
pub use error::Error;
pub use input::{
    validate_vertex_flags, Attributes, AttributesMut, ByteOrder, Positions, PositionsMut,
    VertexFlags,
};
pub use overdraw::{optimize_overdraw, optimize_overdraw_in_place, optimize_overdraw_into};
pub use quantize::{
    compute_position_exponent, dequantize_half, quantize_float, quantize_half, quantize_snorm,
    quantize_unorm,
};
pub use remap::*;

#[cfg(feature = "experimental")]
pub use normal::{generate_normals, generate_normals_into};
pub use opacity::{
    opacity_map_compact, opacity_map_entry_size, opacity_map_measure, opacity_map_measure_into,
    opacity_map_rasterize, opacity_map_rasterize_into, OpacityMapMeasure,
};
pub use raster::{analyze_coverage, analyze_overdraw, CoverageStatistics, OverdrawStatistics};
#[cfg(feature = "experimental")]
pub use remesh::{remesh, remesh_bound, remesh_into, REMESH_SHELL, REMESH_SOLVE};
pub use strip::{
    stripify, stripify_bound, stripify_into, unstripify, unstripify_bound, unstripify_into,
};
pub use tangent::{
    generate_tangents, generate_tangents_into, TANGENT_COMPATIBLE, TANGENT_ZERO_FALLBACK,
};
pub use workspace::{Limits, Usage, Workspace};

mod meshlet;
mod meshlet_spatial;
mod meshlet_util;
mod processing;
mod spatial;
pub use meshlet::*;
pub use meshlet_util::*;
pub use spatial::*;

mod partition;
pub use partition::*;

#[cfg(feature = "clusterlod")]
pub mod clusterlod;
#[cfg(feature = "parallel")]
pub mod parallel;
/// Explicit destructive spelling for caller-buffer fetch optimization.
/// This is the same checked operation as `optimize_vertex_fetch_into`.
pub use remap::optimize_vertex_fetch_into as optimize_vertex_fetch_in_place;
/// Explicit destructive spelling for update simplification with mutable views.
/// This is the same checked operation as `simplify_with_update`.
pub use simplify::simplify_with_update as simplify_with_update_in_place;