Trade: high-level docs for AbstractSceneConverter whole-scene operation.

doc/snippets/MagnumTrade.cpp

@@ -42,6 +42,7 @@
 #include "Magnum/Math/Color.h"
 #include "Magnum/Math/Swizzle.h"
 #include "Magnum/MeshTools/Interleave.h"
+#include "Magnum/MeshTools/RemoveDuplicates.h"
 #include "Magnum/MeshTools/Transform.h"
 #include "Magnum/Trade/AbstractImageConverter.h"
 #include "Magnum/Trade/AbstractImporter.h"
@@ -241,7 +242,7 @@ void doOpenData(Containers::Array<char>&& data, Trade::DataFlags dataFlags) over
 }
 
 {
-/* [AbstractSceneConverter-usage-file] */
+/* [AbstractSceneConverter-usage-mesh-file] */
 PluginManager::Manager<Trade::AbstractSceneConverter> manager;
 Containers::Pointer<Trade::AbstractSceneConverter> converter =
     manager.loadAndInstantiate("AnySceneConverter");
@@ -249,7 +250,7 @@ Containers::Pointer<Trade::AbstractSceneConverter> converter =
 Trade::MeshData mesh = DOXYGEN_ELLIPSIS(Trade::MeshData{{}, {}});
 if(!converter || !converter->convertToFile(mesh, "mesh.ply"))
     Fatal{} << "Can't save mesh.ply with AnySceneConverter";
-/* [AbstractSceneConverter-usage-file] */
+/* [AbstractSceneConverter-usage-mesh-file] */
 }
 
 {
@@ -274,6 +275,47 @@ if(!converter || !converter->convertInPlace(mesh))
 /* [AbstractSceneConverter-usage-mesh-in-place] */
 }
 
+{
+/* [AbstractSceneConverter-usage-multiple-file] */
+PluginManager::Manager<Trade::AbstractImporter> importerManager;
+Containers::Pointer<Trade::AbstractImporter> importer =
+    importerManager.loadAndInstantiate("AnySceneImporter");
+if(!importer || importer->openFile("file.dae"))
+    Fatal{} << "Can't open the input file";
+
+PluginManager::Manager<Trade::AbstractSceneConverter> manager;
+Containers::Pointer<Trade::AbstractSceneConverter> converter =
+    manager.loadAndInstantiate("AnySceneConverter");
+
+if(!converter->beginFile("file.gltf") ||
+   !converter->addSupportedImporterContents(*importer) ||
+   !converter->endFile())
+    Fatal{} << "Can't save the output file";
+/* [AbstractSceneConverter-usage-multiple-file] */
+}
+
+{
+Containers::Pointer<Trade::AbstractImporter> importer;
+Containers::Pointer<Trade::AbstractSceneConverter> converter;
+/* [AbstractSceneConverter-usage-multiple-file-selective] */
+if(!converter->beginFile("file.gltf"))
+    Fatal{} << "Can't begin the output file";
+
+/* Add meshes manually, removing duplicates in each in the process */
+for(UnsignedInt i = 0; i != importer->meshCount(); ++i) {
+    Containers::Optional<Trade::MeshData> mesh = importer->mesh(i);
+    if(!mesh ||
+       !converter->add(MeshTools::removeDuplicates(*mesh), importer->meshName(i)))
+        Fatal{} << "Can't add mesh" << i;
+}
+
+/* Add the rest of the input file and finish */
+if(!converter->addSupportedImporterContents(*importer, ~Trade::SceneContent::Meshes) ||
+   !converter->endFile())
+    Fatal{} << "Can't save the output file";
+/* [AbstractSceneConverter-usage-multiple-file-selective] */
+}
+
 {
 UnsignedInt id{};
 Containers::Pointer<Trade::AbstractImporter> importer;

src/Magnum/Trade/AbstractSceneConverter.h

@@ -622,20 +622,13 @@ case we *know* that @ref AnySceneConverter supports
 @ref SceneConverterFeature::ConvertMeshToFile, however in a more general case
 it might be good to check against the reported @ref features() first.
 
-@snippet MagnumTrade.cpp AbstractSceneConverter-usage-file
+@snippet MagnumTrade.cpp AbstractSceneConverter-usage-mesh-file
 
 See @ref plugins for more information about general plugin usage,
 @ref file-formats to compare implementations of common file formats and the
 list of @m_class{m-doc} [derived classes](#derived-classes) for all available
 scene converter plugins.
 
-@m_class{m-note m-success}
-
-@par
-    There's also the @ref magnum-sceneconverter "magnum-sceneconverter" tool
-    that exposes functionality of all scene converter plugins through a command
-    line interface.
-
 @subsection Trade-AbstractSceneConverter-usage-mesh-data Converting a single mesh data
 
 In the following snippet we use the @ref MeshOptimizerSceneConverter to perform
@@ -671,10 +664,37 @@ following:
 While the operations shown above are convenient enough for simple cases
 involving just a single mesh, general conversion of a whole scene needs much
 more than that. Such conversion is done in a batch way --- first initializing
-the conversion of desired kind, adding particular data, and finalizing the
+the conversion of desired kind using @ref begin(), @ref beginData() or
-conversion together with getting the output back.
+@ref beginFile(), adding particular data using @ref add(), and finalizing the
+conversion together with getting the output back using @ref end(),
+@ref endData() or @ref endFile().
+
+A common scenario is that you have an @ref AbstractImporter instance containing
+an imported file, and you want to convert it to another format. While it's
+possible to go through all imported meshes, images, textures materials, etc.
+and add them one by one, there's a convenience @ref addImporterContents() that
+passes everything through, and @ref addSupportedImporterContents() that passes
+through only data actually supported by the converter, printing a warning for
+the rest. In the following example, a COLLADA file is converted to a glTF using
+@ref GltfSceneConverter delegated from @link AnySceneConverter @endlink:
+
+@snippet MagnumTrade.cpp AbstractSceneConverter-usage-multiple-file
+
+This API takes an optional second parameter, @ref SceneContents, allowing you
+to selectively perform operations on certain data types while still making use
+of the convenience passthrough for the rest. The following snippet will remove
+duplicates from all meshes before saving them to the output:
 
-@todoc usage example once a batch converter exists
+@snippet MagnumTrade.cpp AbstractSceneConverter-usage-multiple-file-selective
+
+<b></b>
+
+@m_class{m-note m-success}
+
+@par
+    There's also the @ref magnum-sceneconverter "magnum-sceneconverter" tool
+    that exposes functionality of all scene converter plugins through a command
+    line interface.
 
 @section Trade-AbstractSceneConverter-data-dependency Data dependency