# How to Use Meshoptimizer's Experimental API Functions and Understand Stability Guarantees

> Explore meshoptimizer's experimental API functions to leverage cutting-edge features. Understand stability guarantees and how they differ from stable APIs for robust development.

- Repository: [Arseny Kapoulkine/meshoptimizer](https://github.com/zeux/meshoptimizer)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Meshoptimizer's experimental API functions are declared in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h) under the `MESHOPTIMIZER_EXPERIMENTAL` macro, offering cutting-edge features without ABI stability guarantees, while stable APIs use `MESHOPTIMIZER_API` and maintain backward compatibility across releases.**

The meshoptimizer library provides high-performance geometry processing algorithms for mesh optimization. While its stable API ensures long-term compatibility, the library also exposes experimental functions that provide early access to new features. Understanding how to use these experimental API functions and their stability guarantees is essential for production applications that balance innovation with reliability.

## Understanding the Stability Model

The meshoptimizer library distinguishes between stable and experimental APIs through specific declaration macros in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h).

### The MESHOPTIMIZER_EXPERIMENTAL Macro

Experimental functions are marked with the **`MESHOPTIMIZER_EXPERIMENTAL`** macro, defined at lines 32-33 in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h). This macro annotates symbols that are exported but not yet stabilized. Unlike stable functions, these may undergo signature changes, behavioral modifications, or complete removal in future releases.

To use an experimental function, include the header and link against `meshoptimizer` as you would with stable APIs. The macro itself can be redefined by your application—for example, mapping it to `__attribute__((deprecated))` to generate compile-time warnings when experimental functions are invoked.

### ABI Stability Guarantees

According to the README (lines 927-935), the library provides two distinct stability tiers:

- **`MESHOPTIMIZER_API` functions**: Considered **stable**. Their signatures, ABI, and basic behavior remain unchanged across releases.
- **`MESHOPTIMIZER_EXPERIMENTAL` functions**: Considered **unstable**. Their signatures may change, they may be removed without deprecation, and compiled calls can exhibit different semantics in future versions.

When building a shared library, you can enforce ABI stability by enabling the CMake option **`MESH_STABLE_EXPORTS`**. This produces a shared library containing only stable APIs, hiding experimental symbols entirely (see [`CMakeLists.txt`](https://github.com/zeux/meshoptimizer/blob/main/CMakeLists.txt), lines 100-115).

## How to Use Experimental Functions

Calling experimental functions follows the standard C API pattern. Below are practical implementations of commonly used experimental features.

### Basic Setup and Macro Redefinition

Include the header and optionally redefine the experimental macro to track usage:

```cpp
#include "meshoptimizer.h"

// Optional: Generate warnings when using experimental APIs
#define MESHOPTIMIZER_EXPERIMENTAL __attribute__((deprecated))

```

### Filtering Index Buffers

The `meshopt_filterIndexBuffer` function removes unused vertices and produces a compacted index buffer. This is defined at line 114 in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h):

```cpp
unsigned int srcIndices[] = {0, 1, 2, 2, 3, 4};
float vertices[] = {
    -1, -1, 0,
     1, -1, 0,
    -1,  1, 0,
     1,  1, 0,
     0,  0, 1
};
unsigned int dstIndices[6];

size_t filtered = meshopt_filterIndexBuffer(
    dstIndices, srcIndices, 6,
    vertices, 5, sizeof(float)*3, sizeof(float)*3);

printf("Filtered index count: %zu\n", filtered);

```

### Generating Tangents

The `meshopt_generateTangents` function computes per-vertex tangent vectors for normal-mapped geometry. This experimental function is declared at line 951:

```cpp
float positions[] = { /* vertex positions */ };
float normals[]   = { /* per-vertex normals */ };
float uvs[]       = { /* texture coordinates */ };
unsigned int idx[] = {0, 1, 2, 2, 3, 0};
float tangents[vertexCount * 4]; // 4 floats per tangent (xyz + handedness)

meshopt_generateTangents(
    tangents,
    idx, 6,
    positions, vertexCount, sizeof(float)*3,
    normals,   vertexCount, sizeof(float)*3,
    uvs,       vertexCount, sizeof(float)*2,
    /*options=*/0);

```

### Measuring Opacity Map Quality

The `meshopt_opacityMapMeasure` function provides level-of-detail metrics for opacity maps. This function appears at line 895:

```cpp
unsigned char levels[256];
unsigned int sources[256];
int ommIndices[256];

size_t result = meshopt_opacityMapMeasure(
    levels, sources, ommIndices,
    srcIndices, 6,
    /*vertex UVs*/ nullptr, 0, 0,
    /*texture size*/ 512, 512,
    /*max level*/ 8,
    /*target edge*/ 0.5f);

printf("Opacity map size: %zu bytes\n", result);

```

## Building with MESH_STABLE_EXPORTS

For production deployments requiring strict ABI stability, configure the build with the `MESH_STABLE_EXPORTS` CMake option. This ensures the resulting shared library exports only functions marked with `MESHOPTIMIZER_API`, completely hiding experimental symbols from the public interface.

To enable this behavior:

```bash
cmake -DMESH_STABLE_EXPORTS=ON ..

```

This approach guarantees that downstream applications cannot accidentally link against experimental functions that might break in future updates.

## Summary

- **Experimental functions** are marked with `MESHOPTIMIZER_EXPERIMENTAL` in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h) and are **not** ABI-stable.
- **Stable functions** use `MESHOPTIMIZER_API` and guarantee persistent signatures and behavior across releases.
- You can call experimental functions identically to stable ones, but you must accept the risk of future breaking changes.
- Enable `MESH_STABLE_EXPORTS` during CMake configuration to build a shared library containing only stable APIs.
- Common experimental functions include `meshopt_filterIndexBuffer`, `meshopt_generateTangents`, and `meshopt_opacityMapMeasure`.

## Frequently Asked Questions

### What is the difference between MESHOPTIMIZER_API and MESHOPTIMIZER_EXPERIMENTAL?

`MESHOPTIMIZER_API` marks functions with guaranteed stable signatures and ABI compatibility across releases, while `MESHOPTIMIZER_EXPERIMENTAL` marks functions that may change signatures, behavior, or be removed entirely in future versions. The experimental macro is defined at lines 32-33 in [`src/meshoptimizer.h`](https://github.com/zeux/meshoptimizer/blob/main/src/meshoptimizer.h).

### Can I use experimental functions in production code?

You may use experimental functions in production if you accept the stability risks. Because these functions can change or disappear in future meshoptimizer releases, you should pin to a specific version or maintain a fork. For maximum stability, build with `MESH_STABLE_EXPORTS` to ensure only stable APIs are available.

### How do I hide experimental symbols when building meshoptimizer?

Set the CMake option `MESH_STABLE_EXPORTS=ON` when configuring the build. This produces a shared library that exports only stable APIs, hiding all functions marked with `MESHOPTIMIZER_EXPERIMENTAL`. This is documented in [`CMakeLists.txt`](https://github.com/zeux/meshoptimizer/blob/main/CMakeLists.txt) at lines 100-115.

### Will experimental functions eventually become stable?

Experimental functions may graduate to stable status if they prove widely useful and their interfaces solidify, but this is not guaranteed. Check the repository's release notes and the README's Experimental APIs section (lines 927-935) for updates on specific functions. You should treat experimental features as potentially temporary until explicitly marked with `MESHOPTIMIZER_API`.