class new in 2020.06
MeshOptimizerSceneConverterMeshOptimizer 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::
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::
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.