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

Meshoptimizer's experimental API functions are declared in 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.

The MESHOPTIMIZER_EXPERIMENTAL Macro

Experimental functions are marked with the MESHOPTIMIZER_EXPERIMENTAL macro, defined at lines 32-33 in 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, 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:

#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:

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:

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:

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:

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 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}