Magnum::MaterialTools namespace new in Git master

Material tools.

Tools for converting, optimizing, filtering and merging materials.

This library is built if MAGNUM_WITH_MATERIALTOOLS is enabled when building Magnum. To use this library with CMake, request the MaterialTools component of the Magnum package and link to the Magnum::MaterialTools target:

find_package(Magnum REQUIRED MaterialTools)

# ...
target_link_libraries(your-app PRIVATE Magnum::MaterialTools)

See Downloading and building and Usage with CMake for more information.

Enums

enum MergeConflicts: UnsignedInt { Fail, KeepFirstIfSameType, KeepFirstIgnoreType } new in Git master
Material merge conflict resolution.
enum class PhongToPbrMetallicRoughnessFlag { KeepOriginalAttributes = 1 << 0, DropUnconvertableAttributes = 1 << 1, FailOnUnconvertableAttributes = (1 << 2)|DropUnconvertableAttributes } new in Git master
Phong to PBR metallic/roughness conversion flag.

Typedefs

using PhongToPbrMetallicRoughnessFlags = Containers::EnumSet<PhongToPbrMetallicRoughnessFlag> new in Git master
Phong to PBR conversion flags.

Functions

auto copy(const Trade::MaterialData& material) -> Trade::MaterialData new in Git master
Make an owned copy of the material.
auto copy(Trade::MaterialData&& material) -> Trade::MaterialData new in Git master
Make a material with owned data.
auto filterAttributes(const Trade::MaterialData& material, Containers::BitArrayView attributesToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) -> Trade::MaterialData new in Git master
Filter material attributes.
auto filterLayers(const Trade::MaterialData& material, Containers::BitArrayView layersToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) -> Trade::MaterialData new in Git master
Filter material layers.
auto filterAttributesLayers(const Trade::MaterialData& material, Containers::BitArrayView attributesToKeep, Containers::BitArrayView layersToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) -> Trade::MaterialData new in Git master
Filter material attributes and layers.
auto merge(const Trade::MaterialData& first, const Trade::MaterialData& second, MergeConflicts conflicts = MergeConflicts::Fail) -> Containers::Optional<Trade::MaterialData> new in Git master
Merge two materials.
auto phongToPbrMetallicRoughness(const Trade::MaterialData& material, PhongToPbrMetallicRoughnessFlags flags = {}) -> Containers::Optional<Trade::MaterialData> new in Git master
Convert a Phong material to PBR metallic/roughness.

Enum documentation

enum Magnum::MaterialTools::MergeConflicts: UnsignedInt new in Git master
#include <Magnum/MaterialTools/Merge.h>

Material merge conflict resolution.

Enumerators
Fail

Print a message to Error and return Containers::NullOpt in case both materials contain an attribute of the same name in the same layer index. Neither its type nor its value is checked, so this fails also in case the values are the same.
KeepFirstIfSameType

Keep the value from the first material in case both materials contain an attribute of the same name in the same layer index and both attributes have the same type. Print a message to Error and return Containers::NullOpt if they have a different type, for example in case of custom attributes.

If you want to keep the value from the second material instead, call merge() with this option and the materials swapped.
KeepFirstIgnoreType

Keep the value from the first material in case both materials contain an attribute of the same name in the same layer index, regardless of their type. With this option the operation always succeeds.

If you want to keep the value from the second material instead, call merge() with this option and the materials swapped.

enum class Magnum::MaterialTools::PhongToPbrMetallicRoughnessFlag new in Git master
#include <Magnum/MaterialTools/PhongToPbrMetallicRoughness.h>

Phong to PBR metallic/roughness conversion flag.

Enumerators
KeepOriginalAttributes

Keep original attributes instead of removing all that were converted.
DropUnconvertableAttributes

Drop attributes that can't be converted instead of keeping them in the output. If FailOnUnconvertableAttributes is specified as well, it has a priority.
FailOnUnconvertableAttributes

Fail if any attributes can't be converted instead of keeping them in the output. Has a priority over DropUnconvertableAttributes.

Typedef documentation

Function documentation

Trade::MaterialData Magnum::MaterialTools::copy(const Trade::MaterialData& material) new in Git master
#include <Magnum/MaterialTools/Copy.h>

Make an owned copy of the material.

Allocates a copy of Trade::MaterialData::attributeData() and layerData() and returns a new material with those. All other properties such as material types or importer state are passed through unchanged. The resulting Trade::MaterialData::attributeDataFlags() and layerDataFlags() are always Trade::DataFlag::Owned and Trade::DataFlag::Mutable.

Trade::MaterialData Magnum::MaterialTools::copy(Trade::MaterialData&& material) new in Git master
#include <Magnum/MaterialTools/Copy.h>

Make a material with owned data.

If either Trade::MaterialData::attributeDataFlags() or layerDataFlags() are not Trade::DataFlag::Owned and Trade::DataFlag::Mutable, allocates a copy of Trade::MaterialData::attributeData() or layerData(), otherwise transfers their ownership. The resulting data are always owned and mutable.

Trade::MaterialData Magnum::MaterialTools::filterAttributes(const Trade::MaterialData& material, Containers::BitArrayView attributesToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) new in Git master
#include <Magnum/MaterialTools/Filter.h>

Filter material attributes.

Returns a material with only the attributes for which the corresponding bit in attributesToKeep was set. Attributes in additional layers are referenced by bit ranges corresponding to Trade::MaterialData::attributeDataOffset() for a particular layer. The output layer ranges are then recalculated based on how many attributes are left in those. Empty layers are kept, Trade::MaterialData::types() are ANDed with typesToKeep.

The size of attributesToKeep is expected to be equal to the number of attributes in all layers (i.e., size of the Trade::MaterialData::attributeData() array).

Trade::MaterialData Magnum::MaterialTools::filterLayers(const Trade::MaterialData& material, Containers::BitArrayView layersToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) new in Git master
#include <Magnum/MaterialTools/Filter.h>

Filter material layers.

Returns a material with only the layers for which the corresponding bit in layersToKeep was set. The only exception is the base layer, which is left empty if removed. Attributes in other layers are kept untouched, Trade::MaterialData::types() are ANDed with typesToKeep.

The size of layerCount is expected to be equal to Trade::MaterialData::layerCount().

Trade::MaterialData Magnum::MaterialTools::filterAttributesLayers(const Trade::MaterialData& material, Containers::BitArrayView attributesToKeep, Containers::BitArrayView layersToKeep, Trade::MaterialTypes typesToKeep = ~Trade::MaterialTypes{}) new in Git master
#include <Magnum/MaterialTools/Filter.h>

Filter material attributes and layers.

Performs what filterAttributes() and filterLayers() do, but in a single step. Bits in attributesToKeep that correspond to layers that are removed are ignored.

Containers::Optional<Trade::MaterialData> Magnum::MaterialTools::merge(const Trade::MaterialData& first, const Trade::MaterialData& second, MergeConflicts conflicts = MergeConflicts::Fail) new in Git master
#include <Magnum/MaterialTools/Merge.h>

Merge two materials.

Takes attributes from second and inserts them to layers of the same index in first. If second has more layers than first, the additional layers are added at the end of first. Trade::MaterialTypes from first and second are merged together. If both materials contain an attribute of the same name in the same layer index, conflict resolution is performed according to the conflicts option.

As the input materials have the attributes sorted already, the operation is done in an $ \mathcal{O}(m + n) $ execution time and memory complexity, with $ m $ and $ n $ being count of all attributes and layers in first and second, respectively.

Containers::Optional<Trade::MaterialData> Magnum::MaterialTools::phongToPbrMetallicRoughness(const Trade::MaterialData& material, PhongToPbrMetallicRoughnessFlags flags = {}) new in Git master
#include <Magnum/MaterialTools/PhongToPbrMetallicRoughness.h>

Convert a Phong material to PBR metallic/roughness.

Performs conversion of the following attributes. If the target attribute is already present, it's passed through unchanged. The original attribute is removed, unless PhongToPbrMetallicRoughnessFlag::KeepOriginalAttributes is set.

The following attributes currently aren't converted. If they are present in the input material, a message is printed to Warning. The attributes are passed through unchanged unless PhongToPbrMetallicRoughnessFlag::DropUnconvertableAttributes is set; if FailOnUnconvertableAttributes is set instead, a message is printed to Error and the function returns Containers::NullOpt.

All other attributes (including ones common for Phong and PBR such as Trade::MaterialAttribute::NormalTexture) are passed through unchanged. The resulting material has Trade::MaterialType::PbrMetallicRoughness set and Trade::MaterialType::Phong removed.