Material Data rework

doc/changelog.dox

@@ -72,6 +72,21 @@ See also:
 
 -   Added @ref SceneGraph::Object::move()
 
+@subsubsection changelog-latest-new-trade Trade library
+
+-   A new, redesigned @ref Trade::MaterialData class allowing to store custom
+    material attributes as well as more material types together in a single
+    instance; plus new @ref Trade::FlatMaterialData,
+    @ref Trade::PbrMetallicRoughnessMaterialData,
+    @ref Trade::PbrSpecularGlossinessMaterialData and
+    @ref Trade::PbrClearCoatMaterialData convenience accessor APIs similar to
+    @ref Trade::PhongMaterialData. See [mosra/magnum#459](https://github.com/mosra/magnum/pull/459).
+-   Added @ref Trade::PhongMaterialData::hasSpecularTexture(),
+    @ref Trade::PhongMaterialData::specularTextureSwizzle(),
+    @ref Trade::PhongMaterialData::normalTextureScale() and
+    @ref Trade::PhongMaterialData::normalTextureSwizzle() to make new features
+    added for PBR materials recognizable also in classic Phong workflows.
+
 @subsection changelog-latest-changes Changes and improvements
 
 @subsubsection changelog-latest-changes-gl GL library
@@ -84,10 +99,23 @@ See also:
 
 -   Added a `--bounds` option to @ref magnum-sceneconverter "magnum-sceneconverter",
     showing data ranges of known attributes
+-   @ref magnum-sceneconverter "magnum-sceneconverter" now lists also materials
+    and textures in `--info`
 
 @subsubsection changelog-latest-changes-trade Trade library
 
 -   Recognizing TIFF file header magic in @ref Trade::AnyImageImporter "AnyImageImporter"
+-   Added @ref Trade::PhongMaterialData::hasCommonTextureTransformation(),
+    @ref Trade::PhongMaterialData::ambientTextureMatrix(),
+    @ref Trade::PhongMaterialData::diffuseTextureMatrix(),
+    @ref Trade::PhongMaterialData::specularTextureMatrix() and
+    @ref Trade::PhongMaterialData::normalTextureMatrix() exposing also
+    per-texture coordinate transformation, similarly to per-texture coordinate
+    sets added in 2020.06
+-   Added @ref Trade::PhongMaterialData::hasCommonTextureCoordinates() and
+    @ref Trade::PhongMaterialData::commonTextureCoordinates() exposing a
+    common texture coordinate set as a complement to a per-texture property
+    added in 2020.06
 
 @subsection changelog-latest-buildsystem Build system
 
@@ -111,6 +139,41 @@ See also:
     coordinates), @ref MeshTools::compile() should be using only the first set
     but it wasn't.
 
+@subsection changelog-latest-deprecated Deprecated APIs
+
+-   @cpp Trade::AbstractMaterialData @ce as well as its containing header
+    `Magnum/Trade/AbstractMaterialData.h` is now a deprecated alias to the new
+    and more flexible @ref Trade::MaterialData.
+-   @cpp Trade::PhongMaterialData::ambientCoordinateSet() @ce,
+    @cpp diffuseCoordinateSet() @ce, @cpp specularCoordinateSet() @ce and
+    @cpp normalCoordinateSet() @ce are deprecated in favor of more consistently
+    named @ref Trade::PhongMaterialData::ambientTextureCoordinates(),
+    @ref Trade::PhongMaterialData::diffuseTextureCoordinates() "diffuseTextureCoordinates()",
+    @ref Trade::PhongMaterialData::specularTextureCoordinates() "specularTextureCoordinates()"
+    and @ref Trade::PhongMaterialData::normalTextureCoordinates() "normalTextureCoordinates()"
+-   @ref Trade::PhongMaterialData constructor is deprecated as the designated
+    way is to populate the @ref Trade::MaterialData class directly instead.
+-   @cpp Trade::PhongMaterialData::textureMatrix() @ce is deprecated in favor
+    of @ref Trade::PhongMaterialData::hasCommonTextureTransformation() and
+    @ref Trade::PhongMaterialData::commonTextureMatrix(), which do proper
+    checking and fallback in case a per-texture transformation is present
+-   @cpp Trade::MaterialData::type() @ce (coming from the original
+    `AbstractMaterialData` class) is deprecated in favor of
+    @ref Trade::MaterialData::types(), as a material data can now contain
+    attributes for multiple different material types at once
+-   @cpp Trade::MaterialData::flags() @ce (coming from the original
+    `AbstractMaterialData` class), @cpp Trade::PhongMaterialData::flags() @ce
+    and related enum (sets) are deprecated. The flags are no longer stored
+    directly but rather generated on-the-fly from attribute data, which makes
+    them less efficient than calling @ref Trade::MaterialData::hasAttribute()
+    etc.
+-   @ref Trade::AbstractImporter::material() now returns
+    @ref Corrade::Containers::Optional instead of a @ref Corrade::Containers::Pointer,
+    as the new @ref Trade::MaterialData class isn't polymorphic anymore. If
+    @ref MAGNUM_BUILD_DEPRECATED is enabled, the returned type acts as a
+    @ref Corrade::Containers::Optional but has (deprecated) implicit conversion
+    to a @ref Corrade::Containers::Pointer to avoid breaking user code.
+
 @subsection changelog-latest-compatibility Potential compatibility breakages, removed APIs
 
 -   Removed remaining APIs deprecated in version 2018.10, in particular:
@@ -144,11 +207,12 @@ See also:
     -   @ref Trade::CameraData constructor not taking an explicit type enum,
         use @ref Trade::CameraData::CameraData(CameraType, Rad, Float, Float, Float, const void*)
         instead
-    -   @ref Trade::AbstractMaterialData constructor taking just two parameters
-        and @ref Trade::PhongMaterialData constructor taking three parameters,
-        use @ref Trade::AbstractMaterialData::AbstractMaterialData(MaterialType, Flags, MaterialAlphaMode, Float, const void*)
-        and @ref Trade::PhongMaterialData::PhongMaterialData(Flags, MaterialAlphaMode, Float, Float, const void*)
-        instead
+    -   @cpp Trade::AbstractMaterialData @ce constructor taking just two
+        parameters and @ref Trade::PhongMaterialData constructor taking three
+        parameters, use either the (also deprecated)
+        @cpp Trade::AbstractMaterialData::AbstractMaterialData(MaterialType, Flags, MaterialAlphaMode, Float, const void*) @ce
+        and @cpp Trade::PhongMaterialData::PhongMaterialData(Flags, MaterialAlphaMode, Float, Float, const void*) @ce
+        constructors or directly the new @ref Trade::MaterialData class
 -   All includes of @ref Corrade/Containers/PointerStl.h and
     @ref Corrade/Containers/ArrayViewStl.h that were added in 2019.01 for
     preserving backwards compatibility after the move from @ref std::unique_ptr
@@ -162,6 +226,21 @@ See also:
     afterwards. This can cause compilation breakages in case the type
     constructor has the parent parameter non-optional, pass the parent
     explicitly in that case.
+-   Mutable access to @ref Trade::PhongMaterialData color and texture
+    information, deprecated in 2020.06, is now removed, as it's impossible to
+    implement through the redesigned @ref Trade::MaterialData APIs. However
+    these APIs were mainly used to populate the contents in asset importers, so
+    this shouldn't cause any breakages in user code.
+-   @ref Trade::MaterialData::flags() now calculates the output on-the-fly
+    based on what attributes are present. This means that arbitrary extra bits
+    passed to the constructor from @cpp AbstractMaterialData @ce subclasses are
+    now discarded, and thus subclasses have to override the
+    @ref Trade::MaterialData::flags() "flags()" function to keep the same
+    behavior.
+-   @ref Trade::MaterialData, which the deprecated
+    @cpp Trade::AbstractMaterialData @ce aliases to, doesn't have a
+    @cpp virtual @ce destructor as subclasses with extra data members aren't a
+    desired use case anymore.
 
 @section changelog-2020-06 2020.06
 
@@ -821,6 +900,10 @@ Released 2020-06-27, tagged as
     deprecated on the 3D variant, use separate
     @ref Shaders::MeshVisualizer3D::setTransformationMatrix() and
     @ref Shaders::MeshVisualizer3D::setProjectionMatrix() instead
+-   Mutable access to @ref Trade::PhongMaterialData color and texture
+    information is deprecated. This was mainly used to populate the contents
+    in asset importers, but the class was redesigned and this is no longer
+    needed.
 -   The unprefixed and alien-looking @cpp FLOAT_EQUALITY_PRECISION @ce,
     @cpp DOUBLE_EQUALITY_PRECISION @ce and @cpp LONG_DOUBLE_EQUALITY_PRECISION @ce
     macros are no longer used by any code and thus deprecated in favor of using
@@ -2461,10 +2544,10 @@ Released 2018-10-23, tagged as
 -   `Shaders::VertexColor::Color` is deprecated, use the direct
     @ref Shaders::VertexColor::Color3 or @ref Shaders::VertexColor::Color4
     alternatives instead
--   @ref Trade::AbstractMaterialData constructor taking just two parameters
+-   @cpp Trade::AbstractMaterialData @ce constructor taking just two parameters
     and @ref Trade::PhongMaterialData constructor taking three parameters are
-    deprecated, use @ref Trade::AbstractMaterialData::AbstractMaterialData(MaterialType, Flags, MaterialAlphaMode, Float, const void*)
-    and @ref Trade::PhongMaterialData::PhongMaterialData(Flags, MaterialAlphaMode, Float, Float, const void*)
+    deprecated, use @cpp Trade::AbstractMaterialData::AbstractMaterialData(MaterialType, Flags, MaterialAlphaMode, Float, const void*) @ce
+    and @cpp Trade::PhongMaterialData::PhongMaterialData(Flags, MaterialAlphaMode, Float, Float, const void*) @ce
     instead
 -   @ref Trade::CameraData constructor not taking an explicit type enum is
     deprecated, use @ref Trade::CameraData::CameraData(CameraType, Rad, Float, Float, Float, const void*)