meshoptimizer

https://meshoptimizer.org
Admin
A library providing algorithms to optimize meshes for GPU rendering efficiency, including vertex...
Tokens:21,581
Snippets:190
Trust Score:7.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implement basic mesh shader in GLSL

Source: https://meshoptimizer.org/

Example of a mesh shader for the VK_EXT_mesh_shader extension, showing vertex and triangle output setup.

```GLSL
layout(binding = 0) readonly buffer Meshlets { Meshlet meshlets[]; };
layout(binding = 1) readonly buffer MeshletVertices { uint meshlet_vertices[]; };
layout(binding = 2) readonly buffer MeshletTriangles { uint8_t meshlet_triangles[]; };

void main() {
    Meshlet meshlet = meshlets[gl_WorkGroupID.x];
    SetMeshOutputsEXT(meshlet.vertex_count, meshlet.triangle_count);

    for (uint i = gl_LocalInvocationIndex; i < meshlet.vertex_count; i += gl_WorkGroupSize.x) {
        uint index = meshlet_vertices[meshlet.vertex_offset + i];
        gl_MeshVerticesEXT[i].gl_Position = world_view_projection * vec4(vertex_positions[index], 1);
    }

    for (uint i = gl_LocalInvocationIndex; i < meshlet.triangle_count; i += gl_WorkGroupSize.x) {
        uint offset = meshlet.triangle_offset + i * 3;
        gl_PrimitiveTriangleIndicesEXT[i] = uvec3(
            meshlet_triangles[offset], meshlet_triangles[offset + 1], meshlet_triangles[offset + 2]);
    }
}
```

--------------------------------

### Build LOD

Source: https://meshoptimizer.org/demo/clusterlod.h

Entry point for building the LOD structure.

```cpp
size_t clodBuild(clodConfig config, clodMesh mesh, void* output_context, clodOutput output_callback)
{
	using namespace clod;
```

--------------------------------

### Default Configuration

Source: https://meshoptimizer.org/demo/clusterlod.h

Provides default settings for standard and ray-tracing LOD builds.

```cpp
clodConfig clodDefaultConfig(size_t max_triangles)
{
	assert(max_triangles >= 4 && max_triangles <= 256);

	clodConfig config = {};
	config.max_vertices = max_triangles;
	config.min_triangles = max_triangles / 3;
	config.max_triangles = max_triangles;

#if MESHOPTIMIZER_VERSION < 1000
	config.min_triangles &= ~3; // account for 4b alignment
#endif

	config.partition_spatial = true;
	config.partition_size = 16;

	config.cluster_spatial = false;
	config.cluster_split_factor = 2.0f;

	config.optimize_clusters = true;
	config.optimize_clusters_level = 1;

	config.simplify_ratio = 0.5f;
	config.simplify_threshold = 0.85f;
	config.simplify_error_merge_previous = 1.0f;
	config.simplify_error_factor_sloppy = 2.0f;
	config.simplify_permissive = true;
	config.simplify_fallback_permissive = false; // note: by default we run in permissive mode, but it's also possible to disable that and use it only as a fallback
	config.simplify_fallback_sloppy = true;

	return config;
}
```

```cpp
clodConfig clodDefaultConfigRT(size_t max_triangles)
{
	clodConfig config = clodDefaultConfig(max_triangles);

	// for ray tracing, we may want smaller clusters when that improves BVH quality further; for maximum ray tracing performance this could be reduced even further
	config.min_triangles = max_triangles / 4;

	// by default, we use larger max_vertices for RT; the vertex count is not important for ray tracing performance, and this helps improve cluster utilization
	config.max_vertices = std::min(size_t(256), max_triangles * 2);

	config.cluster_spatial = true;
	config.cluster_fill_weight = 0.5f;

	return config;
}
```

--------------------------------

### Clone meshoptimizer repository

Source: https://meshoptimizer.org/

Use git to download the latest version of the library.

```bash
git clone -b v1.2 https://github.com/zeux/meshoptimizer.git
```

--------------------------------

### Build gltfpack with Texture Compression

Source: https://meshoptimizer.org/gltf

Builds gltfpack from source using CMake, enabling texture compression by specifying paths to basis_universal and libwebp. Ensure these libraries are cloned into the specified directories before running the commands.

```bash
git clone -b gltfpack https://github.com/zeux/basis_universal
git clone https://github.com/webmproject/libwebp
cmake . -DMESHOPT_BUILD_GLTFPACK=ON -DMESHOPT_GLTFPACK_BASISU_PATH=basis_universal -DMESHOPT_GLTFPACK_LIBWEBP_PATH=libwebp -DCMAKE_BUILD_TYPE=Release
cmake --build . --target gltfpack --config Release

```

--------------------------------

### Optimize glTF file

Source: https://meshoptimizer.org/gltf

Convert a glTF file to an optimized GLB file using the gltfpack command-line tool. Run without arguments for a list of options.

```bash
gltfpack -i scene.gltf -o scene.glb

```

--------------------------------

### Partition clusters with meshopt_partitionClusters

Source: https://meshoptimizer.org/

Organize geometry clusters into larger partitions to improve workload distribution and processing efficiency.

```cpp
const size_t partition_size = 24;

std::vector<unsigned int> cluster_partitions(cluster_count);
size_t partition_count = meshopt_partitionClusters(&cluster_partitions[0], &cluster_indices[0], total_index_count,
    &cluster_index_counts[0], cluster_count, &vertices[0].x, vertex_count, sizeof(Vertex), partition_size);
```

--------------------------------

### C++ Template Wrapper for clodBuild

Source: https://meshoptimizer.org/demo/clusterlod.h

A C++ template wrapper to simplify using clodBuild with callable objects.

```cpp
template <typename Output>
size_t clodBuild(clodConfig config, clodMesh mesh, Output output)
{
	struct Call
	{
		static int output(void* output_context, clodGroup group, const clodCluster* clusters, size_t cluster_count)
		{
			return (*static_cast<Output*>(output_context))(group, clusters, cluster_count);
		}
	};

	return clodBuild(config, mesh, &output, &Call::output);
}
```

--------------------------------

### Generate Raytracing-Optimized Meshlets

Source: https://meshoptimizer.org/

Uses meshopt_buildMeshletsSpatial to create clusters optimized for raytracing via surface area heuristics. Ensure buffers are sized correctly using meshopt_buildMeshletsBound before calling.

```cpp
const size_t max_vertices = 64;
const size_t min_triangles = 16;
const size_t max_triangles = 64;
const float fill_weight = 0.5f;

size_t max_meshlets = meshopt_buildMeshletsBound(indices.size(), max_vertices, min_triangles); // note: use min_triangles to compute worst case bound
std::vector<meshopt_Meshlet> meshlets(max_meshlets);
std::vector<unsigned int> meshlet_vertices(indices.size());
std::vector<unsigned char> meshlet_triangles(indices.size()); // note: in v0.25 or prior, use indices.size() + max_meshlets * 3

size_t meshlet_count = meshopt_buildMeshletsSpatial(meshlets.data(), meshlet_vertices.data(), meshlet_triangles.data(), indices.data(),
    indices.size(), &vertices[0].x, vertices.size(), sizeof(Vertex), max_vertices, min_triangles, max_triangles, fill_weight);
```

--------------------------------

### Configure custom allocator

Source: https://meshoptimizer.org/

Sets custom allocation and deallocation functions for the library. Ensure the provided functions handle out-of-memory scenarios appropriately, such as by throwing or aborting.

```cpp
meshopt_setAllocator(malloc, free);
```

--------------------------------

### Generate vertex remap table

Source: https://meshoptimizer.org/

Create a remap table based on binary equivalence of input vertices to prepare for indexing.

```cpp
size_t index_count = face_count * 3;
size_t unindexed_vertex_count = face_count * 3;
std::vector<unsigned int> remap(unindexed_vertex_count); // temporary remap table
size_t vertex_count = meshopt_generateVertexRemap(&remap[0], NULL, index_count,
    &unindexed_vertices[0], unindexed_vertex_count, sizeof(Vertex));
```

--------------------------------

### Remap vertex and index buffers

Source: https://meshoptimizer.org/

Allocate target buffers and generate them using the previously created remap table.

```cpp
meshopt_remapIndexBuffer(indices, NULL, index_count, &remap[0]);
meshopt_remapVertexBuffer(vertices, &unindexed_vertices[0], unindexed_vertex_count, sizeof(Vertex), &remap[0]);
```

--------------------------------

### Preprocess point clouds with spatial sorting

Source: https://meshoptimizer.org/

Sort point cloud data spatially before quantization and compression to improve efficiency.

```cpp
std::vector<unsigned int> remap(point_count);
meshopt_spatialSortRemap(&remap[0], positions, point_count, sizeof(vec3));

// for each attribute stream
meshopt_remapVertexBuffer(positions, positions, point_count, sizeof(vec3), &remap[0]);
```

--------------------------------

### Measure Opacity Micromap Levels

Source: https://meshoptimizer.org/

Computes subdivision levels and per-triangle OMM indices based on texel footprint for opacity micromap generation.

```cpp
const int states = 4; // 2-state or 4-state OMMs (used after measure)
const int max_level = 6; // max subdivision level
const float target_edge = 3.0f; // target 3x3px area for each microtriangle

std::vector<unsigned char> levels(indices.size() / 3);
std::vector<unsigned int> sources(indices.size() / 3);
std::vector<int> omm_indices(indices.size() / 3);
size_t omm_count = meshopt_opacityMapMeasure(&levels[0], &sources[0], &omm_indices[0], &indices[0], indices.size(),
    &vertices[0].u, vertices.size(), sizeof(Vertex), texture_width, texture_height, max_level, target_edge);
```

--------------------------------

### Load compressed glTF with meshopt_decoder

Source: https://meshoptimizer.org/gltf

When using compressed glTF files, load the meshopt_decoder.mjs module to provide the WebAssembly decoder. This is required for GLTF loaders that support the EXT_meshopt_compression extension.

```javascript
import { MeshoptDecoder } from './meshopt_decoder.mjs';

...

var loader = new GLTFLoader();
loader.setMeshoptDecoder(MeshoptDecoder);
loader.load('pirate.glb', function (gltf) { scene.add(gltf.scene); });

```

--------------------------------

### Cluster point clouds with meshopt_spatialClusterPoints

Source: https://meshoptimizer.org/

Use this algorithm to split point clouds into fixed-size clusters for parallel processing or shader-based rendering.

```cpp
const size_t cluster_size = 256;

std::vector<unsigned int> index(vertices.size());
meshopt_spatialClusterPoints(&index[0], &vertices[0].px, vertices.size(), sizeof(Vertex), cluster_size);
```

--------------------------------

### Simplify a mesh with meshopt_simplify

Source: https://meshoptimizer.org/

Reduces the number of triangles in a mesh by generating a new index buffer that references existing vertices.

```cpp
float threshold = 0.2f;
size_t target_index_count = size_t(index_count * threshold);
float target_error = 1e-2f;

std::vector<unsigned int> lod(index_count);
float lod_error = 0.f;
lod.resize(meshopt_simplify(&lod[0], indices, index_count, &vertices[0].x, vertex_count, sizeof(Vertex),
    target_index_count, target_error, /* options= */ 0, &lod_error));
```

--------------------------------

### Define ClusterLOD Configuration

Source: https://meshoptimizer.org/demo/clusterlod.h

The clodConfig structure defines parameters for cluster generation, partitioning, and simplification strategies.

```cpp
struct clodConfig
{
	// configuration of each cluster; maps to meshopt_buildMeshlets* parameters
	size_t max_vertices;
	size_t min_triangles;
	size_t max_triangles;

	// partitioning setup; maps to meshopt_partitionClusters parameters (plus optional partition sorting)
	// note: partition size is the target size, not maximum; actual partitions may be up to 1/3 larger (e.g. target 24 results in maximum 32)
	bool partition_spatial;
	bool partition_sort;
	size_t partition_size;

	// clusterization setup; maps to meshopt_buildMeshletsSpatial / meshopt_buildMeshletsFlex
	bool cluster_spatial;
	float cluster_fill_weight;
	float cluster_split_factor;

	// every level aims to reduce the number of triangles by ratio, and considers clusters that don't reach the threshold stuck
	float simplify_ratio;
	float simplify_threshold;

	// to compute the error of simplified clusters, we use the formula that combines previous accumulated error as follows:
	// max(previous_error * simplify_error_merge_previous, current_error) + current_error * simplify_error_merge_additive
	float simplify_error_merge_previous;
	float simplify_error_merge_additive;

	// amplify the error of clusters that go through sloppy simplification to account for appearance degradation
	float simplify_error_factor_sloppy;

	// limit error by edge length, aiming to remove subpixel triangles even if the attribute error is high
	float simplify_error_edge_limit;

	// use permissive simplification instead of regular simplification (make sure to use attribute_protect_mask if this is set!)
	bool simplify_permissive;

	// use permissive or sloppy simplification but only if regular simplification gets stuck
	bool simplify_fallback_permissive;
	bool simplify_fallback_sloppy;

	// use regularization during simplification to make triangle density more uniform, at some cost to overall triangle count; recommended for deformable objects
	bool simplify_regularize;

	// should clodCluster::bounds be computed based on the geometry of each cluster
	bool optimize_bounds;

	// should clodCluster::indices be optimized for locality; helps with rasterization performance and ray tracing performance in fast-build modes
	bool optimize_clusters;
	int optimize_clusters_level;
};
```

--------------------------------

### Simplify mesh with attributes

Source: https://meshoptimizer.org/

Uses meshopt_simplifyWithAttributes to perform simplification while considering attribute weights for vertex data.

```cpp
const float nrm_weight = 0.5f;
const float attr_weights[3] = {nrm_weight, nrm_weight, nrm_weight};

std::vector<unsigned int> lod(index_count);
float lod_error = 0.f;
lod.resize(meshopt_simplifyWithAttributes(&lod[0], indices, index_count, &vertices[0].x, vertex_count, sizeof(Vertex),
    &vertices[0].nx, sizeof(Vertex), attr_weights, 3, /* vertex_lock= */ NULL,
    target_index_count, target_error, /* options= */ 0, &lod_error));
```

--------------------------------

### Generate shadow index buffer

Source: https://meshoptimizer.org/

Creates a shadow index buffer from existing mesh data. Ensure the vertex structure offset and size parameters match your specific vertex layout.

```cpp
std::vector<unsigned int> shadow_indices(index_count);
// note: this assumes Vertex starts with float3 positions and should be adjusted accordingly for quantized positions
meshopt_generateShadowIndexBuffer(&shadow_indices[0], indices, index_count, &vertices[0].x, vertex_count, sizeof(float) * 3, sizeof(Vertex));
```

--------------------------------

### Simplify mesh with vertex updates

Source: https://meshoptimizer.org/

Uses meshopt_simplifyWithUpdate to generate a simplified index buffer while updating vertex positions and attributes in place.

```cpp
float result_error = 0.f;
indices.resize(meshopt_simplifyWithUpdate(&indices[0], indices.size(), &vertices[0].px, vertices.size(), sizeof(Vertex),
    &vertices[0].nx, sizeof(Vertex), attr_weights, 3, /* vertex_lock= */ NULL,
    target_index_count, target_error, /* options= */ 0, &result_error));
```

--------------------------------

### Generate tessellation index buffer

Source: https://meshoptimizer.org/

Generates a 12-vertex patch index buffer for hardware tessellation and displacement mapping.

```cpp
std::vector<unsigned int> tess(indices.size() * 4);
meshopt_generateTessellationIndexBuffer(&tess[0], &indices[0], indices.size(), &vertices[0].x, vertices.size(), sizeof(Vertex));
```

--------------------------------

### Convert triangle list to triangle strip

Source: https://meshoptimizer.org/

Converts a vertex cache optimized triangle list into a triangle strip using meshopt_stripify.

```cpp
std::vector<unsigned int> strip(meshopt_stripifyBound(index_count));
unsigned int restart_index = ~0u;
size_t strip_size = meshopt_stripify(&strip[0], indices, index_count, vertex_count, restart_index);
```

--------------------------------

### Simplify Point Cloud

Source: https://meshoptimizer.org/

Reduces a point cloud to a target number of points, optionally incorporating color weights to preserve visual features.

```cpp
const float color_weight = 1;
std::vector<unsigned int> indices(target_count);
indices.resize(meshopt_simplifyPoints(&indices[0], &points[0].x, points.size(), sizeof(Point),
    &points[0].r, sizeof(Point), color_weight, target_count));
```

--------------------------------

### Calculate Opacity Micromap Entry Sizes

Source: https://meshoptimizer.org/

Determines the required storage size for each OMM entry based on subdivision levels and state format.

```cpp
std::vector<unsigned int> offsets(omm_count);
size_t data_size = 0;

for (size_t i = 0; i < omm_count; ++i)
{
    offsets[i] = unsigned(data_size);
    data_size += meshopt_opacityMapEntrySize(levels[i], states);
}
```

--------------------------------

### Clusterize Mesh

Source: https://meshoptimizer.org/demo/clusterlod.h

Builds meshlets from input geometry and optimizes them based on configuration settings.

```cpp
static std::vector<Cluster> clusterize(const clodConfig& config, const clodMesh& mesh, const unsigned int* indices, size_t index_count)
{
	size_t max_meshlets = meshopt_buildMeshletsBound(index_count, config.max_vertices, config.min_triangles);

	std::vector<meshopt_Meshlet> meshlets(max_meshlets);
	std::vector<unsigned int> meshlet_vertices(index_count);

#if MESHOPTIMIZER_VERSION < 1000
	std::vector<unsigned char> meshlet_triangles(index_count + max_meshlets * 3); // account for 4b alignment
#else
	std::vector<unsigned char> meshlet_triangles(index_count);
#endif

	if (config.cluster_spatial)
		meshlets.resize(meshopt_buildMeshletsSpatial(meshlets.data(), meshlet_vertices.data(), meshlet_triangles.data(), indices, index_count,
		    mesh.vertex_positions, mesh.vertex_count, mesh.vertex_positions_stride,
		    config.max_vertices, config.min_triangles, config.max_triangles, config.cluster_fill_weight));
	else
		meshlets.resize(meshopt_buildMeshletsFlex(meshlets.data(), meshlet_vertices.data(), meshlet_triangles.data(), indices, index_count,
		    mesh.vertex_positions, mesh.vertex_count, mesh.vertex_positions_stride,
		    config.max_vertices, config.min_triangles, config.max_triangles, 0.f, config.cluster_split_factor));

	std::vector<Cluster> clusters(meshlets.size());

	for (size_t i = 0; i < meshlets.size(); ++i)
	{
		const meshopt_Meshlet& meshlet = meshlets[i];

#if MESHOPTIMIZER_VERSION < 1010
		if (config.optimize_clusters)
			meshopt_optimizeMeshlet(&meshlet_vertices[meshlet.vertex_offset], &meshlet_triangles[meshlet.triangle_offset], meshlet.triangle_count, meshlet.vertex_count);
#else
		if (config.optimize_clusters)
			meshopt_optimizeMeshletLevel(&meshlet_vertices[meshlet.vertex_offset], meshlet.vertex_count, &meshlet_triangles[meshlet.triangle_offset], meshlet.triangle_count, config.optimize_clusters_level);
#endif

		clusters[i].vertices = meshlet.vertex_count;

		// note: we discard meshlet-local indices; they can be recovered by the caller using clodLocalIndices
		clusters[i].indices.resize(meshlet.triangle_count * 3);
		for (size_t j = 0; j < meshlet.triangle_count * 3; ++j)
			clusters[i].indices[j] = meshlet_vertices[meshlet.vertex_offset + meshlet_triangles[meshlet.triangle_offset + j]];

		clusters[i].group = -1;
		clusters[i].refined = -1;
	}

	return clusters;
}
```

--------------------------------

### Split Vertices for Tangent Mismatches

Source: https://meshoptimizer.org/

Handles UV mirroring by splitting vertices that require different tangent spaces, ensuring correct normal mapping results.

```cpp
// seed each vertex with one of its corner tangents; the loop below fixes any mismatches
for (size_t i = 0; i < indices.size(); ++i)
    vertices[indices[i]].tangent = tangents[i];

std::vector<unsigned int> splits(vertices.size(), ~0u);

for (size_t i = 0; i < indices.size(); ++i)
{
    // walk the chain of split copies looking for a vertex whose tangent matches
    unsigned int v = indices[i];
    while (v != ~0u && vertices[v].tangent != tangents[i])
        v = splits[v];

    // no match in chain: append a new split copy with the target tangent and chain it
    if (v == ~0u)
    {
        v = unsigned(vertices.size());
        vertices.push_back(vertices[indices[i]]);
        vertices[v].tangent = tangents[i];
        splits.push_back(splits[indices[i]]);
        splits[indices[i]] = v;
    }

    indices[i] = v;
}
```

--------------------------------

### clodBuild

Source: https://meshoptimizer.org/demo/clusterlod.h

Builds a cluster LOD hierarchy, invoking a callback function as new clusters and groups are generated.

```APIDOC
## clodBuild

### Description
Builds a cluster LOD hierarchy, calling output callbacks as new clusters and groups are generated. Returns the total number of clusters produced.

### Parameters
- **config** (clodConfig) - Configuration settings for the build process.
- **mesh** (clodMesh) - The input mesh data.
- **output_context** (void*) - User-defined context pointer passed to the callback.
- **output_callback** (clodOutput) - Callback function invoked for each generated group.
```

--------------------------------

### Generate Vertex Remap for Multiple Streams

Source: https://meshoptimizer.org/

Use meshopt_generateVertexRemapMulti when working with multiple vertex streams instead of a single interleaved buffer.

```cpp
meshopt_Stream streams[] = {
    {&unindexed_pos[0], sizeof(float) * 3, sizeof(float) * 3},
    {&unindexed_nrm[0], sizeof(float) * 3, sizeof(float) * 3},
    {&unindexed_uv[0], sizeof(float) * 2, sizeof(float) * 2},
};

std::vector<unsigned int> remap(index_count);
size_t vertex_count = meshopt_generateVertexRemapMulti(&remap[0], NULL, index_count, index_count, streams, sizeof(streams) / sizeof(streams[0]));
```

--------------------------------

### Generate custom vertex remap

Source: https://meshoptimizer.org/

Use a custom comparison function to handle floating point drift when generating remap tables.

```cpp
size_t vertex_count = meshopt_generateVertexRemapCustom(&remap[0], NULL, index_count,
    &unindexed_vertices[0].px, unindexed_vertex_count, sizeof(Vertex),
    [&](unsigned int lhs, unsigned int rhs) -> bool {
        const Vertex& lv = unindexed_vertices[lhs];
        const Vertex& rv = unindexed_vertices[rhs];

        return fabsf(lv.tx - rv.tx) < 1e-3f && fabsf(lv.ty - rv.ty) < 1e-3f;
    });
```

--------------------------------

### Cluster LOD API Functions

Source: https://meshoptimizer.org/demo/clusterlod.h

Functions for configuring, building, and processing cluster LOD hierarchies.

```cpp
#ifdef __cplusplus
extern "C"
{
#endif

// default configuration optimized for rasterization / raytracing
clodConfig clodDefaultConfig(size_t max_triangles);
clodConfig clodDefaultConfigRT(size_t max_triangles);

// build cluster LOD hierarchy, calling output callbacks as new clusters and groups are generated
// returns the total number of clusters produced
size_t clodBuild(clodConfig config, clodMesh mesh, void* output_context, clodOutput output_callback);

// extract meshlet-local indices from cluster indices produced by clodBuild
// fills triangles[] and vertices[] such that vertices[triangles[i]] == indices[i]
// returns number of unique vertices (which will be equal to clodCluster::vertex_count)
size_t clodLocalIndices(unsigned int* vertices, unsigned char* triangles, const unsigned int* indices, size_t index_count);

// upper bound on the number of nodes clodBuildHierarchy can produce
// level_count is the number of levels in the group DAG (max(clodGroup::depth) + 1)
size_t clodBuildHierarchyBound(size_t group_count, size_t node_width, size_t level_count);

// build a spatial hierarchy over the groups produced by clodBuild for accelerating cluster visibility
// level_count is the number of levels in the group DAG (max(clodGroup::depth) + 1)
// the result is a forest with one tree per DAG level:
// - nodes 0..level_count-1 are the roots of per-level trees, each covering groups with clodGroup::depth == level
// - remaining nodes are the tree nodes; each internal node has up to node_width children, and each leaf node refers to a single group
size_t clodBuildHierarchy(clodNode* nodes, const clodGroup* groups, size_t group_count, size_t node_width, size_t level_count);

#ifdef __cplusplus
} // extern "C"
#endif
```

--------------------------------

### Mesh Simplification Wrapper

Source: https://meshoptimizer.org/demo/clusterlod.h

Main simplification function that handles attribute-based simplification and optional fallback logic.

```cpp
static std::vector<unsigned int> simplify(const clodConfig& config, const clodMesh& mesh, const std::vector<unsigned int>& indices, const std::vector<unsigned char>& locks, size_t target_count, float* error)
{
	if (target_count > indices.size())
		return indices;

	std::vector<unsigned int> lod(indices.size());

	unsigned int options = meshopt_SimplifySparse | meshopt_SimplifyErrorAbsolute | (config.simplify_permissive ? meshopt_SimplifyPermissive : 0) | (config.simplify_regularize ? meshopt_SimplifyRegularize : 0);

	lod.resize(meshopt_simplifyWithAttributes(&lod[0], &indices[0], indices.size(),
	    mesh.vertex_positions, mesh.vertex_count, mesh.vertex_positions_stride,
	    mesh.vertex_attributes, mesh.vertex_attributes_stride, mesh.attribute_weights, mesh.attribute_count,
	    &locks[0], target_count, FLT_MAX, options, error));

	if (lod.size() > target_count && config.simplify_fallback_permissive && !config.simplify_permissive)
		lod.resize(meshopt_simplifyWithAttributes(&lod[0], &indices[0], indices.size(),
	    mesh.vertex_positions, mesh.vertex_count, mesh.vertex_positions_stride,
	    mesh.vertex_attributes, mesh.vertex_attributes_stride, mesh.attribute_weights, mesh.attribute_count,
	    &locks[0], target_count, FLT_MAX, options | meshopt_SimplifyPermissive, error));
```

--------------------------------

### Internal Implementation Helpers

Source: https://meshoptimizer.org/demo/clusterlod.h

Internal structures and helper functions used when CLUSTERLOD_IMPLEMENTATION is defined.

```cpp
namespace clod
{

struct Cluster
{
	size_t vertices;
	std::vector<unsigned int> indices;

	int group;
	int refined;

	clodBounds bounds;
};

static clodBounds boundsCompute(const clodMesh& mesh, const std::vector<unsigned int>& indices, float error)
{
	meshopt_Bounds bounds = meshopt_computeClusterBounds(&indices[0], indices.size(), mesh.vertex_positions, mesh.vertex_count, mesh.vertex_positions_stride);

	clodBounds result;
	result.center[0] = bounds.center[0];
	result.center[1] = bounds.center[1];
	result.center[2] = bounds.center[2];
	result.radius = bounds.radius;
	result.error = error;
	return result;
}

static clodBounds boundsMerge(const clodBounds* bounds, size_t count, size_t stride)
{
	meshopt_Bounds merged = meshopt_computeSphereBounds(&bounds[0].center[0], count, stride, &bounds[0].radius, stride);

	clodBounds result = {};
	result.center[0] = merged.center[0];
	result.center[1] = merged.center[1];
	result.center[2] = merged.center[2];
	result.radius = merged.radius;
```

--------------------------------

### Generate Provoking Index Buffer

Source: https://meshoptimizer.org/

Creates a special index buffer and reorder table to encode primitive IDs for visibility buffer rendering.

```cpp
std::vector<unsigned int> provoke(indices.size());
std::vector<unsigned int> reorder(vertices.size() + indices.size() / 3);
reorder.resize(meshopt_generateProvokingIndexBuffer(&provoke[0], &reorder[0], &indices[0], indices.size(), vertices.size()));
```

--------------------------------

### Quantize a position using half precision floats

Source: https://meshoptimizer.org/

Converts single-precision floating point coordinates to half-precision format using meshopt_quantizeHalf.

```cpp
unsigned short px = meshopt_quantizeHalf(v.x);
unsigned short py = meshopt_quantizeHalf(v.y);
unsigned short pz = meshopt_quantizeHalf(v.z);
```

--------------------------------

### meshopt_partitionClusters

Source: https://meshoptimizer.org/

Organizes clusters into larger groups (partitions) to improve processing efficiency and workload distribution.

```APIDOC
## meshopt_partitionClusters

### Description
Partitions clusters into groups of similar size while prioritizing topological and spatial locality.

### Signature
`size_t meshopt_partitionClusters(unsigned int* destination, const unsigned int* cluster_indices, size_t total_index_count, const unsigned int* cluster_index_counts, size_t cluster_count, const float* vertices, size_t vertex_count, size_t vertex_stride, size_t partition_size)`

### Parameters
- **destination** (unsigned int*) - Array to store the partition ID for each cluster.
- **cluster_indices** (const unsigned int*) - Array of indices for all clusters.
- **total_index_count** (size_t) - Total number of indices across all clusters.
- **cluster_index_counts** (const unsigned int*) - Array containing the index count for each cluster.
- **cluster_count** (size_t) - Total number of clusters.
- **vertices** (const float*) - Pointer to vertex positions (optional, can be NULL).
- **vertex_count** (size_t) - Total number of vertices.
- **vertex_stride** (size_t) - Stride between consecutive vertices in bytes.
- **partition_size** (size_t) - Target number of clusters per partition.
```

--------------------------------

### Optimize shadow index buffer

Source: https://meshoptimizer.org/

Improves vertex cache efficiency for the generated shadow index buffer. This should be performed after the shadow index buffer has been generated.

```cpp
meshopt_optimizeVertexCache(&shadow_indices[0], &shadow_indices[0], index_count, vertex_count);
```

--------------------------------

### Quantize a normal using 10-10-10 SNORM encoding

Source: https://meshoptimizer.org/

Uses meshopt_quantizeSnorm to pack normal vector components into a single unsigned integer.

```cpp
unsigned int normal =
    ((meshopt_quantizeSnorm(v.nx, 10) & 1023) << 20) |
    ((meshopt_quantizeSnorm(v.ny, 10) & 1023) << 10) |
     (meshopt_quantizeSnorm(v.nz, 10) & 1023);
```

--------------------------------

### Generate meshlet bounds

Source: https://meshoptimizer.org/

Compute bounding volumes for a meshlet to enable runtime cluster culling.

```C++
meshopt_Bounds bounds = meshopt_computeMeshletBounds(&meshlet_vertices[m.vertex_offset], &meshlet_triangles[m.triangle_offset],
    m.triangle_count, &vertices[0].x, vertices.size(), sizeof(Vertex));
```

--------------------------------

### Define Input Mesh Data

Source: https://meshoptimizer.org/demo/clusterlod.h

The clodMesh structure holds the input geometry data, including indices, vertex positions, and attribute information.

```cpp
struct clodMesh
{
	// input triangle indices
	const unsigned int* indices;
	size_t index_count;

	// total vertex count
	size_t vertex_count;

	// input vertex positions; must be 3 floats per vertex
	const float* vertex_positions;
	size_t vertex_positions_stride;

	// input vertex attributes; used for attribute-aware simplification and permissive simplification
	const float* vertex_attributes;
	size_t vertex_attributes_stride;

	// input vertex locks; allows to preserve additional seams (when not using attribute_protect_mask) or lock vertices via meshopt_SimplifyVertex_* flags
	const unsigned char* vertex_lock;

	// attribute weights for attribute-aware simplification; maps to meshopt_simplifyWithAttributes parameters
	const float* attribute_weights;
	size_t attribute_count;

	// attribute mask to flag attribute discontinuities for permissive simplification; mask (1<<K) corresponds to attribute K
	unsigned int attribute_protect_mask;
};
```

--------------------------------

### Generate Meshlet Data

Source: https://meshoptimizer.org/

Calculates the memory bounds and generates meshlet data from index and vertex buffers.

```cpp
const size_t max_vertices = 64;
const size_t max_triangles = 126; // note: in v0.25 or prior, max_triangles needs to be divisible by 4
const float cone_weight = 0.0f;

size_t max_meshlets = meshopt_buildMeshletsBound(indices.size(), max_vertices, max_triangles);
std::vector<meshopt_Meshlet> meshlets(max_meshlets);
std::vector<unsigned int> meshlet_vertices(indices.size());
std::vector<unsigned char> meshlet_triangles(indices.size()); // note: in v0.25 or prior, use indices.size() + max_meshlets * 3

size_t meshlet_count = meshopt_buildMeshlets(meshlets.data(), meshlet_vertices.data(), meshlet_triangles.data(), indices.data(),
    indices.size(), &vertices[0].x, vertices.size(), sizeof(Vertex), max_vertices, max_triangles, cone_weight);
```

--------------------------------

### Generate adjacency index buffer

Source: https://meshoptimizer.org/

Creates an index buffer for triangle-with-adjacency topology, useful for geometry shaders.

```cpp
std::vector<unsigned int> adjacency(indices.size() * 2);
meshopt_generateAdjacencyIndexBuffer(&adjacency[0], &indices[0], indices.size(), &vertices[0].x, vertices.size(), sizeof(Vertex));
```

--------------------------------

### Perform Permissive Simplification

Source: https://meshoptimizer.org/

Uses meshopt_simplifyWithAttributes with the meshopt_SimplifyPermissive option to allow collapsing vertices across attribute discontinuities.

```cpp
std::vector<unsigned int> lod(index_count);
float lod_error = 0.f;
lod.resize(meshopt_simplifyWithAttributes(&lod[0], indices, index_count, &vertices[0].x, vertex_count, sizeof(Vertex),
    &vertices[0].nx, sizeof(Vertex), attr_weights, 3, /* vertex_lock= */ NULL,
    target_index_count, target_error, /* options= */ meshopt_SimplifyPermissive, &lod_error));
```

--------------------------------

### clodBuildHierarchy

Source: https://meshoptimizer.org/demo/clusterlod.h

Builds a spatial hierarchy over the groups produced by clodBuild to accelerate cluster visibility.

```APIDOC
## clodBuildHierarchy

### Description
Builds a spatial hierarchy over the groups produced by clodBuild for accelerating cluster visibility. The result is a forest with one tree per DAG level.

### Parameters
- **nodes** (clodNode*) - Pointer to the array where nodes will be stored.
- **groups** (const clodGroup*) - Array of groups produced by clodBuild.
- **group_count** (size_t) - Number of groups.
- **node_width** (size_t) - Maximum number of children per internal node.
- **level_count** (size_t) - Number of levels in the group DAG.
```

--------------------------------

### Simplify Cluster LOD

Source: https://meshoptimizer.org/demo/clusterlod.h

Handles fallback simplification for clusters and applies edge length limits to reduce subpixel triangles.

```cpp
	if (lod.size() > target_count && config.simplify_fallback_sloppy)
	{
		simplifyFallback(lod, mesh, indices, locks, target_count, error);
		*error *= config.simplify_error_factor_sloppy; // scale error up to account for appearance degradation
	}

	// optionally limit error by edge length, aiming to remove subpixel triangles even if the attribute error is high
	if (config.simplify_error_edge_limit > 0)
	{
		float max_edge_sq = 0;

		for (size_t i = 0; i < indices.size(); i += 3)
		{
			unsigned int a = indices[i + 0], b = indices[i + 1], c = indices[i + 2];
			assert(a < mesh.vertex_count && b < mesh.vertex_count && c < mesh.vertex_count);

			const float* va = &mesh.vertex_positions[a * (mesh.vertex_positions_stride / sizeof(float))];
			const float* vb = &mesh.vertex_positions[b * (mesh.vertex_positions_stride / sizeof(float))];
			const float* vc = &mesh.vertex_positions[c * (mesh.vertex_positions_stride / sizeof(float))];

			// compute squared edge lengths
			float eab = (va[0] - vb[0]) * (va[0] - vb[0]) + (va[1] - vb[1]) * (va[1] - vb[1]) + (va[2] - vb[2]) * (va[2] - vb[2]);
			float eac = (va[0] - vc[0]) * (va[0] - vc[0]) + (va[1] - vc[1]) * (va[1] - vc[1]) + (va[2] - vc[2]) * (va[2] - vc[2]);
			float ebc = (vb[0] - vc[0]) * (vb[0] - vc[0]) + (vb[1] - vc[1]) * (vb[1] - vc[1]) + (vb[2] - vc[2]) * (vb[2] - vc[2]);

			float emax = std::max(std::max(eab, eac), ebc);
			float emin = std::min(std::min(eab, eac), ebc);

			// we prefer using min edge length to reduce the number of triangles <1px thick, but need some stopgap for thin and long triangles like wires
			max_edge_sq = std::max(max_edge_sq, std::max(emin, emax / 4));
		}

		// adjust the error to limit it for dense clusters based on edge lengths
		*error = std::min(*error, sqrtf(max_edge_sq) * config.simplify_error_edge_limit);
	}

	return lod;
}
```

--------------------------------

### Build Cluster LOD Hierarchy

Source: https://meshoptimizer.org/demo/clusterlod.h

Constructs the hierarchy by iteratively grouping nodes spatially until a single root is formed for each level.

```cpp
size_t clodBuildHierarchy(clodNode* nodes, const clodGroup* groups, size_t group_count, size_t node_width, size_t level_count)
{
	using namespace clod;

	// reserve space for per-level roots
	size_t offset = level_count;

	std::vector<clodNode> row(group_count);
	std::vector<unsigned int> order(group_count);

	for (size_t level = 0; level < level_count; ++level)
	{
		// start each tree hierarchy from the groups of that level as leaves
		row.clear();
		for (size_t i = 0; i < group_count; ++i)
			if (groups[i].depth == int(level))
			{
				clodNode node = {};
				node.bounds = groups[i].simplified;
				node.group = int(i);
				row.push_back(node);
			}

		// build the tree going up one level at a time, using spatial grouping of centers as a proxy for locality
		while (row.size() > 1)
		{
			size_t count = row.size();
			meshopt_spatialClusterPoints(order.data(), row[0].bounds.center, count, sizeof(clodNode), node_width);

			for (size_t i = 0; i < count; ++i)
				nodes[offset + i] = row[order[i]];

			row.clear();
			for (size_t i = 0; i < count; i += node_width)
			{
				// spatialClusterPoints guarantees that each cluster except for last one is full
				size_t children = std::min(node_width, count - i);
				row.push_back(mergeNodes(nodes, offset + i, children));
			}

			offset += count;
		}

		// the root of the current level goes into the fixed section at the beginning
		assert(row.size() == 1);
		nodes[level] = row[0];
	}

	assert(offset <= clodBuildHierarchyBound(group_count, node_width, level_count));
	return offset;
}
```

--------------------------------

### Generate Tangent Vectors with meshopt_generateTangents

Source: https://meshoptimizer.org/

Computes normalized tangent vectors and orientation signs for mesh corners based on positions, normals, and texture coordinates.

```cpp
std::vector<vec4> tangents(indices.size());
meshopt_generateTangents(&tangents[0].x, &indices[0], indices.size(),
    &vertices[0].px, vertices.size(), sizeof(Vertex), &vertices[0].nx, sizeof(Vertex), &vertices[0].tx, sizeof(Vertex));
```

--------------------------------

### Sloppy Simplification Fallback

Source: https://meshoptimizer.org/demo/clusterlod.h

Provides a fallback simplification path by deindexing the mesh subset.

```cpp
struct SloppyVertex
{
	float x, y, z;
	unsigned int id;
};

static void simplifyFallback(std::vector<unsigned int>& lod, const clodMesh& mesh, const std::vector<unsigned int>& indices, const std::vector<unsigned char>& locks, size_t target_count, float* error)
{
	std::vector<SloppyVertex> subset(indices.size());
	std::vector<unsigned char> subset_locks(indices.size());

	lod.resize(indices.size());

	size_t positions_stride = mesh.vertex_positions_stride / sizeof(float);

	// deindex the mesh subset to avoid calling simplifySloppy on the entire vertex buffer (which is prohibitively expensive without sparsity)
	for (size_t i = 0; i < indices.size(); ++i)
	{
		unsigned int v = indices[i];
		assert(v < mesh.vertex_count);

		subset[i].x = mesh.vertex_positions[v * positions_stride + 0];
		subset[i].y = mesh.vertex_positions[v * positions_stride + 1];
		subset[i].z = mesh.vertex_positions[v * positions_stride + 2];
		subset[i].id = v;

		subset_locks[i] = locks[v];
		lod[i] = unsigned(i);
	}

	lod.resize(meshopt_simplifySloppy(&lod[0], &lod[0], lod.size(), &subset[0].x, subset.size(), sizeof(SloppyVertex), subset_locks.data(), target_count, FLT_MAX, error));

	// convert error to absolute
	*error *= meshopt_simplifyScale(&subset[0].x, subset.size(), sizeof(SloppyVertex));

	// restore original vertex indices
	for (size_t i = 0; i < lod.size(); ++i)
		lod[i] = subset[lod[i]].id;
}
```

--------------------------------

### Compact Opacity Micromap Data

Source: https://meshoptimizer.org/

Reduces redundant OMM entries and updates the data size after rasterization.

```cpp
omm_count = meshopt_opacityMapCompact(&data[0], data_size, &levels[0], &offsets[0], omm_count, &omm_indices[0], indices.size() / 3, states);
data_size = (omm_count == 0) ? 0 : offsets[omm_count - 1] + meshopt_opacityMapEntrySize(levels[omm_count - 1], states);
```

--------------------------------

### Spatial Partition Sorting

Source: https://meshoptimizer.org/demo/clusterlod.h

Sorts partitions spatially to optimize cluster distribution.

```cpp
		// sort partitions spatially; the output is a remap table from old index (partition id) to new index
		partition_remap.resize(partition_count);
		meshopt_spatialSortRemap(partition_remap.data(), partition_point.data(), partition_count, sizeof(float) * 3);
	}

	// distribute clusters into partitions, applying spatial order if requested
	for (size_t i = 0; i < pending.size(); ++i)
		partitions[partition_remap.empty() ? cluster_part[i] : partition_remap[cluster_part[i]]].push_back(pending[i]);

	return partitions;
}
```

--------------------------------

### Partition Clusters

Source: https://meshoptimizer.org/demo/clusterlod.h

Partitions a set of clusters into groups based on spatial or index-based criteria.

```cpp
static std::vector<std::vector<int> > partition(const clodConfig& config, const clodMesh& mesh, const std::vector<Cluster>& clusters, const std::vector<int>& pending, const std::vector<unsigned int>& remap)
{
	if (pending.size() <= config.partition_size)
		return {pending};

	std::vector<unsigned int> cluster_indices;
	std::vector<unsigned int> cluster_counts(pending.size());

	// copy cluster index data into a flat array for partitioning
	size_t total_index_count = 0;
	for (size_t i = 0; i < pending.size(); ++i)
		total_index_count += clusters[pending[i]].indices.size();

	cluster_indices.reserve(total_index_count);

	for (size_t i = 0; i < pending.size(); ++i)
	{
		const Cluster& cluster = clusters[pending[i]];

		cluster_counts[i] = unsigned(cluster.indices.size());

		for (size_t j = 0; j < cluster.indices.size(); ++j)
			cluster_indices.push_back(remap[cluster.indices[j]]);
	}

	// partition clusters into groups; the output is a partition id per cluster
	std::vector<unsigned int> cluster_part(pending.size());
	size_t partition_count = meshopt_partitionClusters(&cluster_part[0], &cluster_indices[0], cluster_indices.size(), &cluster_counts[0], cluster_counts.size(),
	    config.partition_spatial ? mesh.vertex_positions : NULL, remap.size(), mesh.vertex_positions_stride, config.partition_size);

	// preallocate partitions for worst case
	std::vector<std::vector<int> > partitions(partition_count);
	for (size_t i = 0; i < partition_count; ++i)
		partitions[i].reserve(config.partition_size + config.partition_size / 3);

	std::vector<unsigned int> partition_remap;

	if (config.partition_sort)
	{
		// compute partition points for sorting; any representative point will do, we use last cluster center for simplicity
		std::vector<float> partition_point(partition_count * 3);
		for (size_t i = 0; i < pending.size(); ++i)
			memcpy(&partition_point[cluster_part[i] * 3], clusters[pending[i]].bounds.center, sizeof(float) * 3);
```

--------------------------------

### Encode Vertex Data

Source: https://meshoptimizer.org/

Allocates a buffer based on the worst-case bound and encodes vertex data into a compressed format.

```cpp
std::vector<unsigned char> vbuf(meshopt_encodeVertexBufferBound(vertex_count, sizeof(Vertex)));
vbuf.resize(meshopt_encodeVertexBuffer(&vbuf[0], vbuf.size(), vertices, vertex_count, sizeof(Vertex)));
```

--------------------------------

### meshopt_spatialClusterPoints

Source: https://meshoptimizer.org/

Splits a point cloud into fixed-size clusters to facilitate parallel processing and maintain spatial locality.

```APIDOC
## meshopt_spatialClusterPoints

### Description
Splits a point cloud into fixed size clusters. The resulting index buffer organizes points into chunks of `cluster_size`.

### Signature
`size_t meshopt_spatialClusterPoints(unsigned int* destination, const float* vertices, size_t vertex_count, size_t vertex_stride, size_t cluster_size)`

### Parameters
- **destination** (unsigned int*) - Pointer to an array of size `vertex_count` to store the resulting indices.
- **vertices** (const float*) - Pointer to the first vertex position component.
- **vertex_count** (size_t) - Total number of vertices.
- **vertex_stride** (size_t) - Stride between consecutive vertices in bytes.
- **cluster_size** (size_t) - Target number of points per cluster.
```
Tokens:
Raw