meshoptimizer-rs
A pure-Rust port of meshoptimizer 1.3. Its output is
byte-identical to the C++ library: index order, error values and encoded bytes match. It needs no
C++ toolchain and supports no_std with alloc.
[]
= "0.2.5"
The minimum Rust version is 1.88. The library name is meshoptimizer_rs.
Usage
Coming from the meshopt crate? See docs/MIGRATING_FROM_MESHOPT.md.
Every operation takes a &mut Workspace and returns Result<_, meshoptimizer_rs::Error>. Most
have an allocating form, a caller-buffer _into form and, where it applies, an _in_place form.
Simplify and optimize a mesh
Simplify to a quarter of the triangles, reorder triangles for the vertex cache and overdraw, then reorder vertices for fetch.
use ;
To account for attributes such as normals, call simplify_with_attributes with an Attributes
view and one weight per component, for example
Attributes::from_interleaved(&normals, vertex_count, 3, 3, 0)? and &[0.5; 3]. Interleaved
positions use Positions::from_interleaved; stride and offset are in f32 elements.
For repeated fetch-remap calls, reuse FetchIndices::new(indices, positions.len()) with
optimize_vertex_fetch_remap_with_indices or its _into form to avoid repeated index validation.
Meshlets and bounds
use ;
build_meshlets_scan, build_meshlets_flex and build_meshlets_spatial cover the other upstream
builders. compute_cluster_bounds computes bounds for index-list clusters.
Reuse BoundsPositions for repeated bounds queries over the same positions.
Cluster LOD DAG
With the clusterlod feature, build_dag_into builds the cluster DAG and its per-level node
forest into buffers you own. Allocate each DagBuffers slice, for example with
vec![Default::default(); capacity]. The returned DagCounts gives the length of each filled
prefix, such as indices[..counts.indices].
use ;
Only the returned prefixes are output. If a call fails, including with BufferTooSmall, discard
the output, restore the original positions (border dilation may have moved them) and retry with
larger buffers. Caller buffers don't count toward Workspace limits.
With parallel as well, parallel::build_dags_batch_into(&mut inputs, Limits::default()) builds
several meshes at once. Each DagBuildInput holds the config, mesh, node_width and
destination arguments above. It returns one Result<DagCounts, Error> per input, in input
order, and each item has its own limits.
Vertex and index compression
The codec module implements the codecs used by EXT_meshopt_compression, plus index sequence
and meshlet codecs and the Oct, Quat, Exp and Color filters. VertexEncoding and IndexEncoding
set the format version and level per call. decode_buffer_view decodes a glTF bufferView using the
mode and filter names from its JSON.
use ;
use ;
Workspace and limits
Keep one Workspace per thread and reuse it: it keeps scratch memory between calls. Its Limits
cap the bytes the crate allocates and the work units a call may spend; the defaults are 1 GiB and
2^34. Set them with Workspace::new(Limits { max_bytes: 64 << 20, max_work: 1 << 30 }). A call
over a limit returns Error::LimitExceeded, and Workspace::usage reports the last call's bytes
and work.
Call workspace.set_retention(Retention::Lean) for lower peak memory in long simplify chains at some time cost.
Features
| Feature | Default | Enables |
|---|---|---|
std |
yes | std::error::Error for Error. |
simd |
yes | SIMD vertex, filter and meshlet decoding for SSE2/SSSE3/SSE4.1, NEON and wasm simd128. |
parallel |
no | Rayon batch APIs in the parallel module; enables std. |
clusterlod |
no | The clusterlod module, a port of upstream demo/clusterlod.h. |
experimental |
no | Upstream experimental functions, including normal generation and remeshing. |
For no_std, set default-features = false; an allocator is required. Without simd the crate
contains no unsafe code. Cargo feature unification applies: if another dependency enables
simd, it is on for your build too.
Correctness and performance
Default output is byte-identical to meshoptimizer 1.3 at commit
4c203430ca565cb59a468a91922c76c208169536, whose src tree equals tag v1.3. Fixtures,
differential sweeps, fuzzing and WASM runs check this on recorded inputs; they don't prove it for
every input. SIMD decoding matches the scalar bytes. See
docs/VERIFICATION.md
and UPSTREAM.md. Timings against C++ 1.3 and the meshopt crate are in
docs/PERFORMANCE.md,
with links to the parity records. Development phases and planned work are in
docs/ROADMAP.md.
Known exceptions
Intervals and method are in docs/PERFORMANCE.md.
- Overdraw optimization is about 1.47–1.60× C++ 1.3 (scalar) on the largest real meshes measured.
- Allocating vertex decode,
vertex-v1-streaming-s4: 1.529–2.118× in 0.2.0; 1.000× and 1.058× when re-run for 0.2.2. The caller-buffer form,decode_vertex_buffer_into, is about 1.04×. - Allocating index decode maxima:
index-2-v0-streaming-s41.508–3.625×,index-2-v1-streaming-s42.189–2.465×. - Allocating EXT view maxima:
view-1-streaming-s41.343–1.636×;varied-view-3-streaming-s321.619–2.590× (unresolved); the filtered-view maximum is near 1.64×. partition_clusterswith Cargo defaults: mean 1.450×, maximum 1.778×.- Older records keep a sparse allocating vertex-fetch maximum failure and inconclusive overdraw and sloppy-simplification maxima.
- A malformed meshlet tail is accepted by scalar upstream and by this crate, but rejected by upstream SSE.
- AVX2, AVX-512 and 32-bit ARM SIMD are not implemented; index and sequence decoding is scalar.
Licence and acknowledgements
MIT; see LICENSE. meshoptimizer is written by Arseny Kapoulkine. This independent port keeps upstream's licence notice and credits its algorithms; it is not affiliated with or endorsed by the upstream project. UPSTREAM.md records provenance and intentional API differences.