diff --git a/doc/debug-tools.dox b/doc/debug-tools.dox index d0787b90e..e1818a033 100644 --- a/doc/debug-tools.dox +++ b/doc/debug-tools.dox @@ -59,7 +59,7 @@ given key doesn't exist, default fallback is used. Example usage: visualizing object position, rotation and scaling using @ref DebugTools::ObjectRenderer : -@snippet MagnumDebugTools.cpp debug-tools-renderers +@snippet MagnumDebugTools-gl.cpp debug-tools-renderers See @ref DebugTools::ObjectRenderer and @ref DebugTools::ShapeRenderer for more information. diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt index 90626d653..080e1b943 100644 --- a/doc/snippets/CMakeLists.txt +++ b/doc/snippets/CMakeLists.txt @@ -92,24 +92,31 @@ if(WITH_DEBUGTOOLS) MagnumDebugTools.cpp) target_link_libraries(snippets-MagnumDebugTools PRIVATE MagnumDebugTools) set_target_properties(snippets-MagnumDebugTools PROPERTIES FOLDER "Magnum/doc/snippets") -endif() -# TODO: causes spurious linker errors on Travis iOS build, so I'm disabling it -if(WITH_DEBUGTOOLS AND Corrade_TestSuite_FOUND AND NOT CORRADE_TARGET_IOS) - set(SNIPPETS_DIR ${CMAKE_CURRENT_SOURCE_DIR}) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake - ${CMAKE_CURRENT_BINARY_DIR}/configure.h) - - # CompareImage documentation snippet. I need it executable so I can - # copy&paste the output to the documentation. Also not using - # corrade_add_test() because it shouldn't be run as part of CTest as it - # purposedly fails. - add_executable(debugtools-compareimage debugtools-compareimage.cpp) - target_link_libraries(debugtools-compareimage PRIVATE - MagnumDebugTools - MagnumTrade) - target_include_directories(debugtools-compareimage PRIVATE ${CMAKE_CURRENT_BINARY_DIR}) - set_target_properties(debugtools-compareimage PROPERTIES FOLDER "Magnum/doc/snippets") + # TODO: causes spurious linker errors on Travis iOS build, so I'm disabling it + if(NOT CORRADE_TARGET_IOS) + set(SNIPPETS_DIR ${CMAKE_CURRENT_SOURCE_DIR}) + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake + ${CMAKE_CURRENT_BINARY_DIR}/configure.h) + + # CompareImage documentation snippet. I need it executable so I can + # copy&paste the output to the documentation. Also not using + # corrade_add_test() because it shouldn't be run as part of CTest as it + # purposedly fails. + add_executable(debugtools-compareimage debugtools-compareimage.cpp) + target_link_libraries(debugtools-compareimage PRIVATE + MagnumDebugTools + MagnumTrade) + target_include_directories(debugtools-compareimage PRIVATE ${CMAKE_CURRENT_BINARY_DIR}) + set_target_properties(debugtools-compareimage PROPERTIES FOLDER "Magnum/doc/snippets") + endif() + + if(TARGET_GL) + add_library(snippets-MagnumDebugTools-gl STATIC + MagnumDebugTools-gl.cpp) + target_link_libraries(snippets-MagnumDebugTools-gl PRIVATE MagnumDebugTools) + set_target_properties(snippets-MagnumDebugTools-gl PROPERTIES FOLDER "Magnum/doc/snippets") + endif() endif() if(WITH_PRIMITIVES) diff --git a/doc/snippets/MagnumDebugTools-gl.cpp b/doc/snippets/MagnumDebugTools-gl.cpp new file mode 100644 index 000000000..83d2160fe --- /dev/null +++ b/doc/snippets/MagnumDebugTools-gl.cpp @@ -0,0 +1,135 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +#include + +#include "Magnum/Image.h" +#include "Magnum/PixelFormat.h" +#include "Magnum/DebugTools/ForceRenderer.h" +#include "Magnum/DebugTools/ResourceManager.h" +#include "Magnum/DebugTools/ObjectRenderer.h" +#include "Magnum/DebugTools/TextureImage.h" +#include "Magnum/GL/CubeMapTexture.h" +#include "Magnum/GL/Texture.h" +#include "Magnum/Math/Range.h" +#include "Magnum/SceneGraph/Drawable.h" +#include "Magnum/SceneGraph/Object.h" +#include "Magnum/SceneGraph/MatrixTransformation3D.h" + +#ifndef MAGNUM_TARGET_GLES2 +#include "Magnum/GL/BufferImage.h" +#endif + +using namespace Magnum; +using namespace Magnum::Math::Literals; + +int main() { +{ +SceneGraph::Object* object{}; +/* [debug-tools-renderers] */ +// Global instance of debug resource manager, drawable group for the renderers +DebugTools::ResourceManager manager; +SceneGraph::DrawableGroup3D debugDrawables; + +// Create renderer options which will be referenced later by "my" resource key +DebugTools::ResourceManager::instance().set("my", + DebugTools::ObjectRendererOptions{}.setSize(0.3f)); + +// Create debug renderer for given object, use "my" options for it. The +// renderer is automatically added to the object features and also to +// specified drawable group. +new DebugTools::ObjectRenderer3D{*object, "my", &debugDrawables}; +/* [debug-tools-renderers] */ +} + +{ +SceneGraph::Object* object{}; +SceneGraph::DrawableGroup3D debugDrawables; +/* [ForceRenderer] */ +DebugTools::ResourceManager::instance().set("my", + DebugTools::ForceRendererOptions{} + .setSize(5.0f) + .setColor(Color3::fromHsv(120.0_degf, 1.0f, 0.7f))); + +// Create debug renderer for given object, use "my" options for it +Vector3 force; +new DebugTools::ForceRenderer3D(*object, {0.3f, 1.5f, -0.7f}, force, "my", + &debugDrawables); +/* [ForceRenderer] */ +} + +{ +SceneGraph::Object* object{}; +SceneGraph::DrawableGroup3D debugDrawables; +/* [ObjectRenderer] */ +// Create some options +DebugTools::ResourceManager::instance().set("my", + DebugTools::ObjectRendererOptions{}.setSize(0.3f)); + +// Create debug renderer for given object, use "my" options for it +new DebugTools::ObjectRenderer3D(*object, "my", &debugDrawables); +/* [ObjectRenderer] */ +} +{ +GL::Texture2D texture; +Range2Di rect; +/* [textureSubImage-2D-rvalue] */ +Image2D image = DebugTools::textureSubImage(texture, 0, rect, + {PixelFormat::RGBA8Unorm}); +/* [textureSubImage-2D-rvalue] */ +} + +#ifndef MAGNUM_TARGET_GLES2 +{ +GL::Texture2D texture; +Range2Di rect; +/* [textureSubImage-2D-rvalue-buffer] */ +GL::BufferImage2D image = DebugTools::textureSubImage(texture, 0, rect, + {PixelFormat::RGBA8Unorm}, GL::BufferUsage::StaticRead); +/* [textureSubImage-2D-rvalue-buffer] */ +} +#endif + +{ +GL::CubeMapTexture texture; +Range2Di rect; +/* [textureSubImage-cubemap-rvalue] */ +Image2D image = DebugTools::textureSubImage(texture, + GL::CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA8Unorm}); +/* [textureSubImage-cubemap-rvalue] */ +} + +#ifndef MAGNUM_TARGET_GLES2 +{ +GL::CubeMapTexture texture; +Range2Di rect; +/* [textureSubImage-cubemap-rvalue-buffer] */ +GL::BufferImage2D image = DebugTools::textureSubImage(texture, + GL::CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA8Unorm}, + GL::BufferUsage::StaticRead); +/* [textureSubImage-cubemap-rvalue-buffer] */ +} +#endif +} diff --git a/doc/snippets/MagnumDebugTools.cpp b/doc/snippets/MagnumDebugTools.cpp index e289e7fdd..c33a743b9 100644 --- a/doc/snippets/MagnumDebugTools.cpp +++ b/doc/snippets/MagnumDebugTools.cpp @@ -25,15 +25,12 @@ #include #include -#include -#include -#include -#include -#include -#include -#include -#include -#include + +#include "Magnum/Image.h" +#include "Magnum/PixelFormat.h" +#include "Magnum/DebugTools/CompareImage.h" +#include "Magnum/Math/Color.h" +#include "Magnum/Trade/AbstractImporter.h" using namespace Magnum; @@ -92,23 +89,3 @@ CORRADE_COMPARE_WITH("actual.png", expected, } } }; - -int main() { -{ -SceneGraph::Object* object{}; -/* [debug-tools-renderers] */ -// Global instance of debug resource manager, drawable group for the renderers -DebugTools::ResourceManager manager; -SceneGraph::DrawableGroup3D debugDrawables; - -// Create renderer options which will be referenced later by "my" resource key -DebugTools::ResourceManager::instance().set("my", - DebugTools::ObjectRendererOptions{}.setSize(0.3f)); - -// Create debug renderer for given object, use "my" options for it. The -// renderer is automatically added to the object features and also to -// specified drawable group. -new DebugTools::ObjectRenderer3D{*object, "my", &debugDrawables}; -/* [debug-tools-renderers] */ -} -} diff --git a/src/Magnum/DebugTools/ForceRenderer.h b/src/Magnum/DebugTools/ForceRenderer.h index 08ade28f5..508915fc8 100644 --- a/src/Magnum/DebugTools/ForceRenderer.h +++ b/src/Magnum/DebugTools/ForceRenderer.h @@ -97,16 +97,7 @@ See @ref debug-tools-renderers for more information. Example code: -@code{.cpp} -DebugTools::ResourceManager::instance().set("my", DebugTools::ForceRendererOptions() - .setScale(5.0f) - .setColor(Color3::fromHSV(120.0_degf, 1.0f, 0.7f)); - -// Create debug renderer for given object, use "my" options for it -Object3D* object; -Vector3 force; -new DebugTools::ForceRenderer2D(object, {0.3f, 1.5f, -0.7f}, &force, "my", debugDrawables); -@endcode +@snippet MagnumDebugTools-gl.cpp ForceRenderer @note This class is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" and `WITH_SCENEGRAPH` enabled (done by diff --git a/src/Magnum/DebugTools/ObjectRenderer.h b/src/Magnum/DebugTools/ObjectRenderer.h index 4994272c2..7dabd1a8b 100644 --- a/src/Magnum/DebugTools/ObjectRenderer.h +++ b/src/Magnum/DebugTools/ObjectRenderer.h @@ -81,14 +81,7 @@ Visualizes object position, rotation and scale using colored axes. See Example code: -@code{.cpp} -// Create some options -DebugTools::ResourceManager::instance().set("my", DebugTools::ObjectRendererOptions().setSize(0.3f)); - -// Create debug renderer for given object, use "my" options for it -Object3D* object; -new DebugTools::ObjectRenderer2D(object, "my", debugDrawables); -@endcode +@snippet MagnumDebugTools-gl.cpp ObjectRenderer @note This class is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" and `WITH_SCENEGRAPH` enabled (done by diff --git a/src/Magnum/DebugTools/TextureImage.h b/src/Magnum/DebugTools/TextureImage.h index d8e418f38..c7a7f6795 100644 --- a/src/Magnum/DebugTools/TextureImage.h +++ b/src/Magnum/DebugTools/TextureImage.h @@ -65,9 +65,7 @@ MAGNUM_DEBUGTOOLS_EXPORT void textureSubImage(GL::Texture2D& texture, Int level, Convenience alternative to the above, example usage: -@code{.cpp} -Image2D image = DebugTools::textureSubImage(texture, 0, rect, {PixelFormat::RGBA, PixelType::UnsignedByte}); -@endcode +@snippet MagnumDebugTools-gl.cpp textureSubImage-2D-rvalue @note This function is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" enabled (done by default). See @@ -97,9 +95,7 @@ MAGNUM_DEBUGTOOLS_EXPORT void textureSubImage(GL::CubeMapTexture& texture, GL::C Convenience alternative to the above, example usage: -@code{.cpp} -Image2D image = DebugTools::textureSubImage(texture, CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA, PixelType::UnsignedByte}); -@endcode +@snippet MagnumDebugTools-gl.cpp textureSubImage-cubemap-rvalue @note This function is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" enabled (done by default). See @@ -134,9 +130,7 @@ MAGNUM_DEBUGTOOLS_EXPORT void textureSubImage(GL::Texture2D& texture, Int level, Convenience alternative to the above, example usage: -@code{.cpp} -BufferImage2D image = DebugTools::textureSubImage(texture, 0, rect, {PixelFormat::RGBA, PixelType::UnsignedByte}, BufferUsage::StaticRead); -@endcode +@snippet MagnumDebugTools-gl.cpp textureSubImage-2D-rvalue-buffer @note This function is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" enabled (done by default). See @@ -168,9 +162,7 @@ MAGNUM_DEBUGTOOLS_EXPORT void textureSubImage(GL::CubeMapTexture& texture, GL::C Convenience alternative to the above, example usage: -@code{.cpp} -BufferImage2D image = DebugTools::textureSubImage(texture, CubeMapCoordinate::PositiveX, 0, rect, {PixelFormat::RGBA, PixelType::UnsignedByte}, BufferUsage::StaticRead); -@endcode +@snippet MagnumDebugTools-gl.cpp textureSubImage-cubemap-rvalue-buffer @note This function is available only if Magnum is compiled with @ref MAGNUM_TARGET_GL "TARGET_GL" enabled (done by default). See