Magnum::Trade::MeshOptimizerSceneConverter class new in 2020.06
#include <MagnumPlugins/MeshOptimizerSceneConverter/MeshOptimizerSceneConverter.h>

MeshOptimizer converter plugin.

Integrates various algorithms from meshoptimizer.

Usage

This plugin depends on the Trade library and is built if MAGNUM_WITH_MESHOPTIMIZERSCENECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "MeshOptimizerSceneConverter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and meshoptimizer repositories and do the following. If you want to use system-installed meshoptimizer, omit the first part and point CMAKE_PREFIX_PATH to its installation dir if necessary.

set(CMAKE_POSITION_INDEPENDENT_CODE ON) # needed if building dynamic plugins
add_subdirectory(meshoptimizer EXCLUDE_FROM_ALL)

set(MAGNUM_WITH_MESHOPTIMIZERSCENECONVERTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::MeshOptimizerSceneConverter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake into your modules/ directory, request the MeshOptimizerSceneConverter component of the MagnumPlugins package and link to the MagnumPlugins::MeshOptimizerSceneConverter target:

find_package(MagnumPlugins REQUIRED MeshOptimizerSceneConverter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::MeshOptimizerSceneConverter)

See Downloading and building plugins, Plugin usage with CMake and Loading and using plugins for more information.

Behavior and limitations

The plugin by default performs the following optimizations, which can be configured further using plugin-specific options:

Vertex cache optimization, performed when optimizeVertexCache is enabled
Overdraw optimization, performed when optimizeOverdraw is enabled
Vertex fetch optimization, performed when optimizeVertexFetch is enabled

The optimizations can be done either in-place using convertInPlace(MeshData&), in which case the input is required to be an indexed triangle mesh with mutable contiguous index buffer of a non-implementation-specific index type and, in case of optimizeVertexFetch, also mutable vertex data. Alternatively, the operation can be performed using convert(const MeshData&), which accepts also triangle strips and fans or non-contiguous index buffers of non-implementation-specific index types, returning always an indexed triangle mesh without requiring the input to be mutable.

The output has the same index type as input and all attributes are preserved, including custom attributes and attributes with implementation-specific vertex formats, except for optimizeOverdraw, which needs a position attribute in a known type. Attributes with zero or negative stride are allowed on input but the output will always have an interleaved layout with positive strides.

When SceneConverterFlag::Verbose is enabled, the plugin prints the output from meshoptimizer's efficiency analyzers before and after the operation. SceneConverterFlag::Quiet is recognized as well and causes all conversion warnings to be suppressed.

Mesh simplification

By default the plugin performs only the above non-destructive operations. Mesh simplification can be enabled using either the simplify or simplifySloppy configuration option together with specifying desired simplifyTargetIndexCountThreshold — the default value of 1.0 will leave the mesh unchanged, set it to for example 0.25 to reduce the mesh to a fourth of its size.

The simplification process is done in convert(const MeshData&) and returns a copy of the mesh with a subset of original vertices and a reduced index buffer, meaning the original vertex positions are used, with no interpolation to new locations. It only requires the mesh to have a position attribute, mesh connectivity and face seams are figured out from the index buffer. As with all other operations, all original attributes are preserved.

The simplification can result in the whole mesh being removed if either the simplifyTargetError is set too high or the input consists of just degenerate triangles. By default a mesh with zero vertices is returned in that case, enable the simplifyFailEmpty option to make the process fail in that case instead.

Plugin-specific configuration

It's possible to tune various output options through configuration(). See below for all options and their default values:

[configuration]
# Vertex cache optimization, operates on the index buffer only
optimizeVertexCache=true

# Overdraw optimization, operates on the index buffer and additionally
# requires the mesh to provide (read-only) per-vertex positions
optimizeOverdraw=true
optimizeOverdrawThreshold=1.05

# Vertex fetch optimization, operates on both index and vertex buffer
optimizeVertexFetch=true

# Mesh simplification, disabled by default as it's a destructive operation.
# The simplifySloppy option is a variant without preserving original mesh
# topology, enable either one or the other.
simplify=false
simplifySloppy=false
simplifyTargetIndexCountThreshold=1.0
simplifyTargetError=1.0e-2
# Do not move vertices that are located on the topological border (vertices
# on triangle edges that don't have a paired triangle). Useful for
# simplifying portions of a larger mesh. Available since meshoptimizer 0.18,
# ignored on older versions.
simplifyLockBorder=false
# Fail the process if the simplification results in an empty mesh. Useful to
# ensure the target error isn't set too high. By default a zero-vertex mesh
# gets returned in that case. Has no effect for input meshes that are already
# empty, those are passed through always.
simplifyFailEmpty=false

# Used by mesh efficiency analyzers when verbose output is enabled. Defaults
# the same as in the meshoptimizer demo app.
analyzeCacheSize=16
analyzeWarpSize=0
analyzePrimitiveGroupSize=0

See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.

Base classes

class AbstractSceneConverter new in 2020.06: Base for scene converter plugins.

Constructors, destructors, conversion operators

MeshOptimizerSceneConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit: Plugin manager constructor.