Trade: deprecate AbstractImporter interfaces for MeshDataXD.

For backwards compatibility these will delegate to the new MeshData
interfaces for 3D (and nothing for 2D, because so far there were no 2D
scene importers).

doc/changelog.dox

@@ -139,6 +139,13 @@ See also:
 
 @subsection changelog-latest-deprecated Deprecated APIs
 
+-   @cpp Trade::AbstractImporter::mesh2D() @ce,
+    @cpp Trade::AbstractImporter::mesh3D() @ce and related APIs are
+    deprecated in favor of @ref Trade::AbstractImporter::mesh() and the new
+    @ref Trade::MeshData API. For backwards compatibility, importers
+    implementing the new API have it exposed through @cpp mesh3D() @ce as well,
+    returning a subset of @ref Trade::MeshData functionality supported by the
+    old @cpp Trade::MeshData3D @ce APIs
 -   @cpp Platform::GlfwApplication::Configuration::setCursorMode() @ce and
     related enum & getter are deprecated in favor of the new extended and more
     flexible @ref Platform::GlfwApplication::setCursor(). The setting didn't

src/Magnum/Trade/AbstractImporter.cpp

@@ -444,32 +444,41 @@ Containers::Optional<MeshData> AbstractImporter::doMesh(UnsignedInt) {
     CORRADE_ASSERT(false, "Trade::AbstractImporter::mesh(): not implemented", {});
 }
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 UnsignedInt AbstractImporter::mesh2DCount() const {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh2DCount(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     return doMesh2DCount();
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
 UnsignedInt AbstractImporter::doMesh2DCount() const { return 0; }
 
 Int AbstractImporter::mesh2DForName(const std::string& name) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh2DForName(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     return doMesh2DForName(name);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
 Int AbstractImporter::doMesh2DForName(const std::string&) { return -1; }
 
 std::string AbstractImporter::mesh2DName(const UnsignedInt id) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh2DName(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     CORRADE_ASSERT(id < doMesh2DCount(), "Trade::AbstractImporter::mesh2DName(): index" << id << "out of range for" << doMesh2DCount() << "entries", {});
     return doMesh2DName(id);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
 std::string AbstractImporter::doMesh2DName(UnsignedInt) { return {}; }
 
 Containers::Optional<MeshData2D> AbstractImporter::mesh2D(const UnsignedInt id) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh2D(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     CORRADE_ASSERT(id < doMesh2DCount(), "Trade::AbstractImporter::mesh2D(): index" << id << "out of range for" << doMesh2DCount() << "entries", {});
     return doMesh2D(id);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
 Containers::Optional<MeshData2D> AbstractImporter::doMesh2D(UnsignedInt) {
@@ -478,35 +487,54 @@ Containers::Optional<MeshData2D> AbstractImporter::doMesh2D(UnsignedInt) {
 
 UnsignedInt AbstractImporter::mesh3DCount() const {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh3DCount(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     return doMesh3DCount();
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
-UnsignedInt AbstractImporter::doMesh3DCount() const { return 0; }
+UnsignedInt AbstractImporter::doMesh3DCount() const {
+    return doMeshCount();
+}
 
 Int AbstractImporter::mesh3DForName(const std::string& name) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh3DForName(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     return doMesh3DForName(name);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
-Int AbstractImporter::doMesh3DForName(const std::string&) { return -1; }
+Int AbstractImporter::doMesh3DForName(const std::string& name) {
+    return doMeshForName(name);
+}
 
 std::string AbstractImporter::mesh3DName(const UnsignedInt id) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh3DName(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     CORRADE_ASSERT(id < doMesh3DCount(), "Trade::AbstractImporter::mesh3DName(): index" << id << "out of range for" << doMesh3DCount() << "entries", {});
     return doMesh3DName(id);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
-std::string AbstractImporter::doMesh3DName(UnsignedInt) { return {}; }
+std::string AbstractImporter::doMesh3DName(const UnsignedInt id) {
+    return doMeshName(id);
+}
 
 Containers::Optional<MeshData3D> AbstractImporter::mesh3D(const UnsignedInt id) {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::mesh3D(): no file opened", {});
+    CORRADE_IGNORE_DEPRECATED_PUSH
     CORRADE_ASSERT(id < doMesh3DCount(), "Trade::AbstractImporter::mesh3D(): index" << id << "out of range for" << doMesh3DCount() << "entries", {});
     return doMesh3D(id);
+    CORRADE_IGNORE_DEPRECATED_POP
 }
 
-Containers::Optional<MeshData3D> AbstractImporter::doMesh3D(UnsignedInt) {
-    CORRADE_ASSERT(false, "Trade::AbstractImporter::mesh3D(): not implemented", {});
+Containers::Optional<MeshData3D> AbstractImporter::doMesh3D(const UnsignedInt id) {
+    Containers::Optional<MeshData> out = doMesh(id);
+    CORRADE_IGNORE_DEPRECATED_PUSH
+    if(out) return MeshData3D{*out};
+    CORRADE_IGNORE_DEPRECATED_POP
+    return Containers::NullOpt;
 }
+#endif
 
 UnsignedInt AbstractImporter::materialCount() const {
     CORRADE_ASSERT(isOpened(), "Trade::AbstractImporter::materialCount(): no file opened", {});

src/Magnum/Trade/AbstractImporter.h

@@ -690,69 +690,87 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         Containers::Optional<MeshData> mesh(UnsignedInt id);
 
+        #ifdef MAGNUM_BUILD_DEPRECATED
         /**
          * @brief Two-dimensional mesh count
          *
          * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref meshCount() instead.
          */
-        UnsignedInt mesh2DCount() const;
+        CORRADE_DEPRECATED("use meshCount() instead") UnsignedInt mesh2DCount() const;
 
         /**
          * @brief Two-dimensional mesh ID for given name
          *
          * If no mesh for given name exists, returns @cpp -1 @ce. Expects that
          * a file is opened.
+         * @m_deprecated_since_latest Use @ref meshForName() instead.
          * @see @ref mesh2DName()
          */
-        Int mesh2DForName(const std::string& name);
+        CORRADE_DEPRECATED("use meshForName() instead") Int mesh2DForName(const std::string& name);
 
         /**
          * @brief Two-dimensional mesh name
          * @param id        Mesh ID, from range [0, @ref mesh2DCount()).
          *
          * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref meshName() instead.
          * @see @ref mesh2DForName()
          */
-        std::string mesh2DName(UnsignedInt id);
+        CORRADE_DEPRECATED("use meshName() instead") std::string mesh2DName(UnsignedInt id);
 
         /**
          * @brief Two-dimensional mesh
          * @param id        Mesh ID, from range [0, @ref mesh2DCount()).
          *
          * Returns given mesh or @ref Containers::NullOpt if importing failed.
          * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref mesh() instead.
          */
-        Containers::Optional<MeshData2D> mesh2D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_PUSH /* Clang doesn't warn, but GCC does */
+        CORRADE_DEPRECATED("use mesh() instead") Containers::Optional<MeshData2D> mesh2D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_POP
 
-        /** @brief Three-dimensional mesh count */
-        UnsignedInt mesh3DCount() const;
+        /**
+         * @brief Three-dimensional mesh count
+         *
+         * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref meshCount() instead.
+         */
+        CORRADE_DEPRECATED("use meshCount() instead") UnsignedInt mesh3DCount() const;
 
         /**
          * @brief Three-dimensional mesh ID for given name
          *
          * If no mesh for given name exists, returns @cpp -1 @ce. Expects that
          * a file is opened.
+         * @m_deprecated_since_latest Use @ref meshForName() instead.
          * @see @ref mesh3DName()
          */
-        Int mesh3DForName(const std::string& name);
+        CORRADE_DEPRECATED("use meshForName() instead") Int mesh3DForName(const std::string& name);
 
         /**
          * @brief Three-dimensional mesh name
          * @param id        Mesh ID, from range [0, @ref mesh3DCount()).
          *
          * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref meshName() instead.
          * @see @ref mesh3DForName()
          */
-        std::string mesh3DName(UnsignedInt id);
+        CORRADE_DEPRECATED("use meshName() instead") std::string mesh3DName(UnsignedInt id);
 
         /**
          * @brief Three-dimensional mesh
          * @param id        Mesh ID, from range [0, @ref mesh3DCount()).
          *
          * Returns given mesh or @ref Containers::NullOpt if importing failed.
          * Expects that a file is opened.
+         * @m_deprecated_since_latest Use @ref meshName() instead.
          */
-        Containers::Optional<MeshData3D> mesh3D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_PUSH /* Clang doesn't warn, but GCC does */
+        CORRADE_DEPRECATED("use mesh() instead") Containers::Optional<MeshData3D> mesh3D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_POP
+        #endif
 
         /**
          * @brief Material count
@@ -1167,53 +1185,90 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi
          */
         virtual Containers::Optional<MeshData> doMesh(UnsignedInt id);
 
+        #ifdef MAGNUM_BUILD_DEPRECATED
         /**
          * @brief Implementation for @ref mesh2DCount()
          *
-         * Default implementation returns @cpp 0 @ce.
+         * Default implementation returns @cpp 0 @ce. There weren't any
+         * importers in existence known to implement 2D mesh import, so unlike
+         * @ref doMesh3DCount() this function doesn't delegate to
+         * @ref doMeshCount().
+         * @m_deprecated_since_latest Implement @ref doMeshCount() instead.
          */
-        virtual UnsignedInt doMesh2DCount() const;
+        CORRADE_DEPRECATED("implement doMeshCount() instead") virtual UnsignedInt doMesh2DCount() const;
 
         /**
          * @brief Implementation for @ref mesh2DForName()
          *
-         * Default implementation returns @cpp -1 @ce.
+         * Default implementation returns @cpp -1 @ce. There weren't any
+         * importers in existence known to implement 2D mesh import, so unlike
+         * @ref doMesh3DForName() this function doesn't delegate to
+         * @ref doMeshForName().
+         * @m_deprecated_since_latest Implement @ref doMeshForName() instead.
          */
-        virtual Int doMesh2DForName(const std::string& name);
+        CORRADE_DEPRECATED("implement doMeshForName() instead") virtual Int doMesh2DForName(const std::string& name);
 
         /**
          * @brief Implementation for @ref mesh2DName()
          *
-         * Default implementation returns empty string.
+         * Default implementation returns empty string. There weren't any
+         * importers in existence known to implement 2D mesh import, so unlike
+         * @ref doMesh3DName() this function doesn't delegate to
+         * @ref doMeshName().
+         * @m_deprecated_since_latest Implement @ref doMeshName() instead.
          */
-        virtual std::string doMesh2DName(UnsignedInt id);
+        CORRADE_DEPRECATED("implement doMeshName() instead") virtual std::string doMesh2DName(UnsignedInt id);
 
-        /** @brief Implementation for @ref mesh2D() */
-        virtual Containers::Optional<MeshData2D> doMesh2D(UnsignedInt id);
+        /**
+         * @brief Implementation for @ref mesh2D()
+         *
+         * There weren't any importers in existence known to implement 2D mesh
+         * import, so unlike @ref doMesh3D() this function doesn't
+         * delegate to @ref doMesh().
+         * @m_deprecated_since_latest Implement @ref doMesh() instead.
+         */
+        CORRADE_IGNORE_DEPRECATED_PUSH /* Clang doesn't warn, but GCC does */
+        CORRADE_DEPRECATED("implement doMesh() instead") virtual Containers::Optional<MeshData2D> doMesh2D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_POP
 
         /**
          * @brief Implementation for @ref mesh3DCount()
          *
-         * Default implementation returns @cpp 0 @ce.
+         * Default implementation returns @ref doMeshCount() for backwards
+         * compatibility.
+         * @m_deprecated_since_latest Implement @ref doMeshCount() instead.
          */
-        virtual UnsignedInt doMesh3DCount() const;
+        CORRADE_DEPRECATED("implement doMeshCount() instead") virtual UnsignedInt doMesh3DCount() const;
 
         /**
          * @brief Implementation for @ref mesh3DForName()
          *
-         * Default implementation returns @cpp -1 @ce.
+         * Default implementation returns @ref doMeshForName() for backwards
+         * compatibility.
+         * @m_deprecated_since_latest Implement @ref doMeshForName() instead.
          */
-        virtual Int doMesh3DForName(const std::string& name);
+        CORRADE_DEPRECATED("implement doMeshForName() instead") virtual Int doMesh3DForName(const std::string& name);
 
         /**
          * @brief Implementation for @ref mesh3DName()
          *
-         * Default implementation returns empty string.
+         * Default implementation returns @ref doMeshName() for backwards
+         * compatibility.
+         * @m_deprecated_since_latest Implement @ref doMeshName() instead.
          */
-        virtual std::string doMesh3DName(UnsignedInt id);
+        CORRADE_DEPRECATED("implement doMeshName() instead") virtual std::string doMesh3DName(UnsignedInt id);
 
-        /** @brief Implementation for @ref mesh3D() */
-        virtual Containers::Optional<MeshData3D> doMesh3D(UnsignedInt id);
+        /**
+         * @brief Implementation for @ref mesh3D()
+         *
+         * Default implementation returns @ref doMesh() converted to
+         * @ref MeshData3D for backwards compatibility.
+         * @m_deprecated_since_latest Implement @ref doMesh() instead.
+         */
+        CORRADE_IGNORE_DEPRECATED_PUSH /* Clang doesn't warn, but GCC does */
+        CORRADE_DEPRECATED("implement doMesh() instead") virtual Containers::Optional<MeshData3D> doMesh3D(UnsignedInt id);
+        CORRADE_IGNORE_DEPRECATED_POP
+        #endif
 
         /**
          * @brief Implementation for @ref materialCount()