About meshoptimizer mesh compression for Unity

Use the meshoptimizer mesh compression for Unity package to decode meshoptimizer compressed index/vertex buffers efficiently in Burst-compiled C# Jobs off the main thread.

It is a port of the original meshoptimizer compression by Arseny Kapoulkine (zeux).

Important

This package is available as an experimental package, so it is not ready for production use. The features and documentation in this package might change before it is verified for release.

Installation

Tip

Click the following link to fast-track the installation: com.unity.meshopt.decompress

To install this package, follow the instructions for adding a package by name in the Unity Editor and use the name com.unity.meshopt.decompress.

Requirements

The meshoptimizer mesh compression for Unity package is compatible with Unity version of 2022.3.67f2 or later.

If you are new to meshoptimizer mesh compression for Unity, or have a question after reading the documentation, you can:

Using meshoptimizer mesh compression for Unity

Here's a pseudo-code example how to decode a meshoptmizer buffer using DecodeGltfBuffer.

async void DecodeGltfBufferExampleAsync(NativeArray<byte>.ReadOnly inputBuffer)
{

    // - The size (in bytes) and number of elements (indices/vertices)
    const int elementSize = 24;
    const int elementCount = 100;

    // - Type of buffer
    const Mode mode = Mode.Attributes; // Vertex attributes (position/normal) in this case

    // - (optional) Type of filter (in case of `Attributes` mode)
    const Filter filter = Filter.Exponential;

    // - Destination/output buffer
    //   Its size is determined by the element size and count
    var outputBuffer = new NativeArray<byte>(elementSize * elementCount, Allocator.TempJob);

    // - A NativeArray container for the return code
    //   After decoding, this first (and only) member of this array is the
    //   return code indicating if the decoding was successful (in which case
    //   it is `0`)
    var returnCode = new NativeArray<int>(1, Allocator.TempJob);

    // This creates a Job that decodes on a thread and returns
    // the JobHandle
    var jobHandle = Decode.DecodeGltfBuffer(
        returnCode,
        outputBuffer,
        elementCount,
        elementSize,
        inputBuffer,
        mode,
        filter
    );

    // This loop will wait for the job to complete.
    while (!jobHandle.IsCompleted)
    {
        await Task.Yield();
    }

    // Important! `Complete` has to be called on the jobHandle to release
    // its resources.
    jobHandle.Complete();

    // Check the returnValue for errors
    if (returnCode[0] == 0)
    {
        // You can now access the outputBuffer
    }
    else
    {
        Debug.LogError("Meshopt decoding failed");
    }

    // Make sure you finally dispose all resources
    outputBuffer.Dispose();
    returnCode.Dispose();
}

An alternative method is to decompress synchronously on the main thread via DecodeGltfBufferSync, which has a bit less boilerplate code (but is slower).

void DecodeGltfBufferExample(NativeArray<byte>.ReadOnly inputBuffer)
{

    // The information you need upfront is idendical, except you don't need a return code
    // container:
    const int elementSize = 24;
    const int elementCount = 100;
    const Mode mode = Mode.Attributes;
    const Filter filter = Filter.Exponential;
    var outputBuffer = new NativeArray<byte>(elementSize * elementCount, Allocator.TempJob);

    // This executes the decoding on the main thread and returns
    // the return code directly
    var returnCode = Decode.DecodeGltfBufferSync(
        outputBuffer,
        elementCount,
        elementSize,
        inputBuffer,
        mode,
        filter
    );

    // Check the returnValue for errors
    if (returnCode == 0)
    {
        // You can now access the outputBuffer
    }
    else
    {
        Debug.LogError("Meshopt decoding failed");
    }

    // Make sure you finally dispose all resources
    outputBuffer.Dispose();
}

meshoptimizer mesh compression for Unity workflows

A common use-case for meshoptimizer mesh decoding is loading glTF files that utilize it via the EXT_meshopt_compression extension. The glTFast package uses meshoptimizer mesh compression for Unity for this purpose. Consult it as a reference use-case.

Apple privacy manifest

To publish applications for iOS, iPadOS, tvOS, and visionOS platforms on the App Store, you must include a privacy manifest file in your application as per Apple’s privacy policy.

Note

For information on creating a privacy manifest file to include in your application, refer to Apple’s privacy manifest policy requirements.

The UnityMeshOpt.xcprivacy manifest file outlines the required information, ensuring transparency in accordance with user privacy practices. This file lists the types of data that your Unity applications, third-party SDKs, packages, and plug-ins collect, and the reasons for using certain required reason API (Apple documentation) categories. Apple also requires that certain domains be declared as tracking (Apple documentation); these domains might be blocked unless a user provides consent.

Warning

If your privacy manifest doesn’t declare the use of the required reason API by you or third-party SDKs, the App Store might reject your application. Read more about the required reason API in Apple’s documentation.

The meshoptimizer mesh compression for Unity package does not collect data or engage in any data practices requiring disclosure in a privacy manifest file.

Note

Note: The meshoptimizer mesh compression for Unity package is dependent on the following services. Refer to their manifest files for applicable data practices.

  • com.unity.burst
  • com.unity.mathematics