Mesh Data rework

doc/changelog-old.dox

@@ -343,7 +343,7 @@ for a high-level overview.
 -   @cpp Buffer::invalidateData() @ce, @cpp Buffer::invalidateSubData() @ce and
     @cpp Renderer::resetNotificationStrategy() @ce functions are enabled on
     OpenGL ES as a no-op
--   Added @ref std::vector overload of @ref MeshTools::combineIndexArrays()
+-   Added @ref std::vector overload of @cpp MeshTools::combineIndexArrays() @ce
     for greater runtime-usage flexibility
 -   @ref Platform::Sdl2Application now defaults to non-resizable window, you
     can change the behavior using @ref Platform::Sdl2Application::Configuration::setWindowFlags()
@@ -391,9 +391,9 @@ for a high-level overview.
     which filled @cpp Mesh @ce and @cpp Buffer @ce directly are deprecated as
     they had undesired side-effects in some cases, use the data-returning
     versions instead and then configure mesh and buffer manually
--   @ref MeshTools::combineIndexedArrays() taking @ref std::tuple is
+-   @cpp MeshTools::combineIndexedArrays() @ce taking @ref std::tuple is
     deprecated, use version taking @ref std::pair instead
--   @ref MeshTools::removeDuplicates() taking also list of indices is
+-   @cpp MeshTools::removeDuplicates() @ce taking also list of indices is
     deprecated, use the function in conjunction with @ref MeshTools::duplicate().
     See function documentation for more information.
 -   Parameter-less @cpp Mesh::draw() @ce and @cpp MeshView::draw() @ce are
@@ -510,8 +510,8 @@ No dependency changes in this release.
 -   New @ref Shaders::Generic class with common definitions, so you can
     configure mesh for the generic shader and render it with any other
     compatible shader
--   Convenience @cpp hasNormals() @ce, @cpp hasTextureCoords2D() @ce functions to
-    @ref Trade::MeshData2D and @ref Trade::MeshData3D
+-   Convenience @cpp hasNormals() @ce, @cpp hasTextureCoords2D() @ce functions
+    in @cpp Trade::MeshData2D @ce and @cpp Trade::MeshData3D @ce
 -   OpenGL ES 3.0 build now shares list of vendor extensions with OpenGL ES 2.0
     build (i.e. only those extensions that aren't part of ES 3.0 are present in
     @cpp Extensions @ce)

doc/developers.dox

@@ -407,7 +407,7 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
     -   run [doxygen.py](http://mcss.mosra.cz/doxygen/) on `Doxyfile-mcss`
         and verify there are no new warnings
     -   eyeball the relevant docs and fix suspicious things
-10.  Push to a temporary branch (e.g., `next`)
+10. Push to a temporary branch (e.g., `next`)
 11. Iterate until the CIs are green
 12. Merge to `master`
 13. If possible, trigger builds of dependent projects (where they are still
@@ -488,6 +488,61 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
 8.  If possible, trigger builds of dependent projects and verify they are still
     green (or wait for the scheduled builds)
 
+@section developers-adding-attribute Checklist for adding a new mesh attribute
+
+1.  Extend @ref Trade::MeshAttribute with the new entry
+2.  Add a corresponding reserved type to @ref Shaders::Generic, if not there
+    already
+    -   Also update `src/Magnum/Shaders/generic.glsl` with the reserved ID
+3.  Update the type assertion in the @ref Trade::MeshAttributeData constructor
+    to account for the new type
+4.  Add a pair of convenience getters to @ref Trade::MeshData similar to e.g.
+    @ref Trade::MeshData::normalsInto() / @ref Trade::MeshData::normalsAsArray()
+    with a type that's the same as the one used in the @ref Shaders::Generic
+    definition, test that it does the right thing for every supported type
+5.  Update @ref Trade::operator<<(Debug&, MeshAttribute) for the new entry
+6.  Update @ref MeshTools::compile() to recognize the new attribute. If there
+    is already a builtin shader capable of using this attribute, add new test
+    to `MeshToolsCompileGLTest`.
+7.  Push to a temporary branch (e.g., `next`)
+8.  Iterate until the CIs are green
+9.  Merge to `master`
+
+@section developers-adding-vertex-format Checklist for adding a new vertex format
+
+1.  Extend @ref VertexFormat with the new entry, if it's not there already,
+    document mapping to GL, Vulkan, D3D and Metal (if exists)
+2.  Update docs of @ref Trade::MeshAttribute to mention where the format can be
+    newly used
+3.  Appropriately relax the assertion in the @ref Trade::MeshAttributeData
+    constructor
+3.  Extend `Trade::Implementation::vertexFormatFor()`, add a mapping between
+    this entry and a C++ type, optionally also
+    `isVertexFormatCompatibleWithAttribute()` if there's more than one entry
+    corresponding to a particular C++ type. If the mapping is unconventional,
+    be sure to mention it in the
+    @ref Trade::MeshAttributeData::MeshAttributeData(MeshAttribute, const Containers::StridedArrayView1D<T>&)
+    constructor docs.
+4.  Update corresponding `Trade::MeshData::*Into()` convenience getters to
+    ensure they can handle this type
+5.  Update `src/Magnum/Implementation/vertexFormatMapping.hpp` and
+    `src/Magnum/Vk/Implementation/vertexFormatMapping.hpp` with the new entry
+6.  Update @ref vertexFormatSize(), @ref vertexFormatComponentFormat(),
+    @ref vertexFormatComponentCount() and @ref isVertexFormatNormalized() to
+    handle this format
+7.  Update the @ref GL::hasVertexFormat() utility and
+    @ref GL::DynamicAttribute::DynamicAttribute(Kind, UnsignedInt, VertexFormat)
+    constructor to provide mapping of the new type to GL; add a test for the
+    new type, if it's special in some way, otherwise the all-catching loop will
+    check it
+8.  Update @ref MeshTools::compile() to recognize the new type (if anything
+    extra needs to be done, usually doesn't as everything is handled by
+    @ref GL::DynamicAttribute already); add corresponding new test(s) to
+    `MeshToolsCompileGLTest`.
+9.  Push to a temporary branch (e.g., `next`)
+10. Iterate until the CIs are green
+11. Merge to `master`
+
 @section developers-gl-extensions Checklist for adding / removing GL versions and extensions
 
 1.  Install [flextGL](https://github.com/mosra/flextgl)