diff --git a/doc/snippets/imageconverter-info-converter.ansi b/doc/snippets/imageconverter-info-converter.ansi new file mode 100644 index 000000000..7ae119509 --- /dev/null +++ b/doc/snippets/imageconverter-info-converter.ansi @@ -0,0 +1,16 @@ +Plugin name: StbResizeImageConverter +Features: + Convert2D + Convert3D +Configuration: +  # Target width and height, separated by a space. Required. +  size=512 512 + +  # How neighboring pixel values are retrieved on image edges. Valid values +  # are: +  # - clamp -- as if the edge pixels were extended +  # - wrap -- as if the image was repeated +  # - reflect -- as if the image was repeated and reflected +  # - zero -- uses zero values for out-of-bounds pixels +  edge=clamp +… diff --git a/doc/snippets/sceneconverter-info-converter.ansi b/doc/snippets/sceneconverter-info-converter.ansi new file mode 100644 index 000000000..1620c559e --- /dev/null +++ b/doc/snippets/sceneconverter-info-converter.ansi @@ -0,0 +1,24 @@ +Plugin name: GltfSceneConverter +Features: + ConvertMultipleToData + AddScenes + AddMeshes + AddMaterials + AddTextures + AddImages2D + AddCompressedImages2D +Configuration: +  # Copyright and generator name, written into the asset object. If empty, no +  # value is written. +  copyright=Me & Myself +  generator=Magnum GltfSceneConverter + +  # Add one or more extensionUsed and/or extensionRequired values to populate +  # the extension usage and requirement arrays. + +  # Whether to write a *.gltf or a *.glb file. If empty, detected automatically +  # based on filename extension, conversion to data defaults to a binary file. +  # If a text file is selected for conversion to data, converting anything that +  # involves binary buffers will currently fail. +  binary= +… diff --git a/src/Magnum/SceneTools/sceneconverter.cpp b/src/Magnum/SceneTools/sceneconverter.cpp index 1672e0de7..e312fdc9e 100644 --- a/src/Magnum/SceneTools/sceneconverter.cpp +++ b/src/Magnum/SceneTools/sceneconverter.cpp @@ -94,24 +94,83 @@ magnum-sceneconverter --info Box.gltf @endparblock -Converting an OBJ file to a PLY, implicitly using +Converting an OBJ file to a glTF, implicitly using @relativeref{Trade,AnySceneConverter} that delegates to -@relativeref{Trade,StanfordSceneConverter} or -@ref file-formats "any other plugin capable of PLY export" depending on what's +@relativeref{Trade,GltfSceneConverter} or +@ref file-formats "any other plugin capable of glTF export" depending on what's available: @code{.sh} -magnum-sceneconverter chair.obj chair.ply +magnum-sceneconverter chair.obj chair.gltf @endcode -Processing an OBJ file with @relativeref{Trade,MeshOptimizerSceneConverter}, -setting @ref Trade-MeshOptimizerSceneConverter-configuration "plugin-specific configuration options" -to reduce the index count to half, saving as a PLY, with verbose output showing -the processing stats: +Extracting a single mesh from a glTF to a PLY file, implicitly delegated to +@relativeref{Trade,StanfordSceneConverter}, for closer inspection: @code{.sh} -magnum-sceneconverter chair.obj -C MeshOptimizerSceneConverter \ - -c simplify=true,simplifyTargetIndexCountThreshold=0.5 chair.ply -v +magnum-sceneconverter scene.gltf --mesh 17 mesh17.ply +@endcode + +Repacking a glTF and encoding all its images as Basis UASTC with +@relativeref{Trade,BasisImageConverter} using the @cb{.ini} imageConverter @ce +@ref Trade-GltfSceneConverter-configuration "option of GltfSceneConverter": + +@code{.sh} +magnum-sceneconverter scene.gltf scene.basis.gltf \ + -c imageConverter=BasisKtxImageConverter,imageConverter/uastc +@endcode + +Printing features and documented options of a particular scene converter +plugin. For debugging convenience the printed configuration file will reflect +also all options specified via `-c`: + +@m_class{m-code-figure} + +@parblock + +@code{.sh} +magnum-sceneconverter --info-converter -C GltfSceneConverter -c copyright="Me & Myself" +@endcode + + + +@m_class{m-nopad} + +@include sceneconverter-info-converter.ansi + +@endparblock + +@subsection magnum-sceneconverter-example-image-mesh-conversion Performing operations on all images and meshes in the file + +Processing a glTF file and removing duplicates in all its meshes: + +@code{.sh} +magnum-sceneconverter scene.gltf --remove-duplicates scene.deduplicated.gltf +@endcode + +Processing a glTF file, resizing all its images to 512x512 with +@relativeref{Trade,StbResizeImageConverter}, block-compressing their data to a +BC3 using @relativeref{Trade,StbDxtImageConverter} with high-quality output and +saving them in a KTX2 container with @relativeref{Trade,KtxImageConverter} and +an experimental [KHR_texture_ktx](https://github.com/KhronosGroup/glTF/pull/1964) +glTF extension: + +@code{.sh} +magnum-sceneconverter scene.gltf scene.dxt.gltf \ + -P StbResizeImageConverter -p size="512 512" \ + -P StbDxtImageConverter -p highQuality \ + -c imageConverter=KtxImageConverter,experimentalKhrTextureKtx +@endcode + +Processing a glTF file and decimating all its meshes to a half size with +@relativeref{Trade,MeshOptimizerSceneConverter}, with verbose output showing +the processing stats. The `-M` / `-m` options can be chained the same way as +`-P` / `-p` above, if needed: + +@code{.sh} +magnum-sceneconverter scene.gltf scene.decimated.gltf \ + -M MeshOptimizerSceneConverter \ + -m simplify,simplifyTargetIndexCountThreshold=0.5 -v @endcode @section magnum-sceneconverter-usage Full usage documentation diff --git a/src/Magnum/Trade/imageconverter.cpp b/src/Magnum/Trade/imageconverter.cpp index 026f15bc8..408a616a0 100644 --- a/src/Magnum/Trade/imageconverter.cpp +++ b/src/Magnum/Trade/imageconverter.cpp @@ -128,7 +128,7 @@ from: @parblock @code{.sh} -magnum-imageconverter -I AnySceneImporter --info file.gltf +magnum-imageconverter -I GltfImporter --info file.gltf @endcode @@ -141,22 +141,45 @@ magnum-imageconverter -I AnySceneImporter --info file.gltf @m_class{m-noindent} -and then extracting the third image to a PNG file for inspection: +... and then extracting the third image to a PNG file for inspection: @code{.sh} -magnum-imageconverter -I AnySceneImporter --image 2 file.gltf image.png +magnum-imageconverter -I GltfImporter --image 2 file.gltf image.png @endcode -Converting a PNG file to a KTX2, block-compressing the data to BC3 using -@relativeref{Trade,StbDxtImageConverter} and enabling a high-quality output. +Converting a PNG file to a KTX2, resizing it to 512x512 with +@relativeref{Trade,StbResizeImageConverter}, block-compressing its data to BC3 +using @relativeref{Trade,StbDxtImageConverter} with high-quality output. Because the plugin implements image-to-image conversion, the @relativeref{Trade,AnyImageConverter} plugin is implicitly used after it, proxying to @relativeref{Trade,KtxImageConverter} as the `*.ktx2` extension was chosen: @code{.sh} -magnum-imageconverter image.png -C StbDxtImageConverter -c highQuality image.ktx2 +magnum-imageconverter image.png image.ktx2 \ + -C StbResizeImageConverter -c size="512 512" \ + -C StbDxtImageConverter -c highQuality @endcode +Printing features and documented options of a particular image converter +plugin. For debugging convenience the printed configuration file will reflect +also all options specified via `-c`: + +@m_class{m-code-figure} + +@parblock + +@code{.sh} +magnum-imageconverter --info-converter -C StbResizeImageConverter -c size="512 512" +@endcode + + + +@m_class{m-nopad} + +@include imageconverter-info-converter.ansi + +@endparblock + @subsection magnum-imageconverter-example-levels-layers Dealing with image levels and layers Converting six 2D images to a 3D cube map file using @relativeref{Trade,OpenExrImageConverter}. Note the `-c envmap-cube` which the