From 5c9f74e4b053d4b4e5f879954fefccb9f382b783 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 26 Feb 2018 19:27:16 +0100 Subject: [PATCH] doc: converted Platform docs to use compiled code snippets. They got terribly outdated over the years, ugh. --- doc/platform.dox | 178 ++---------------- doc/snippets/CMakeLists.txt | 29 ++- doc/snippets/MagnumPlatform-custom.cpp | 45 +++++ .../MagnumPlatform-windowless-custom.cpp | 56 ++++++ .../MagnumPlatform-windowless-thread.cpp | 47 +++++ doc/snippets/MagnumPlatform-windowless.cpp | 52 +++++ doc/snippets/MagnumPlatform.cpp | 145 ++++++++++++++ 7 files changed, 387 insertions(+), 165 deletions(-) create mode 100644 doc/snippets/MagnumPlatform-custom.cpp create mode 100644 doc/snippets/MagnumPlatform-windowless-custom.cpp create mode 100644 doc/snippets/MagnumPlatform-windowless-thread.cpp create mode 100644 doc/snippets/MagnumPlatform-windowless.cpp create mode 100644 doc/snippets/MagnumPlatform.cpp diff --git a/doc/platform.dox b/doc/platform.dox index 2b66c82f7..51cc2184d 100644 --- a/doc/platform.dox +++ b/doc/platform.dox @@ -64,38 +64,7 @@ blue color is shown in the following code listing. `base` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository. -@code{.cpp} -#include -#include -#include -#include - -using namespace Magnum; - -class MyApplication: public Platform::Application { - public: - MyApplication(const Arguments& arguments); - - private: - void drawEvent() override; -}; - -MyApplication::MyApplication(const Arguments& arguments): Platform::Application(arguments) { - // Set clear color to dark blue - Renderer::setClearColor({0.0f, 0.0f, 0.4f}); -} - -void MyApplication::drawEvent() { - // Clear the window - defaultFramebuffer.clear(FramebufferClear::Color); - - // The context is double-buffered, swap buffers - swapBuffers(); -} - -// main() function implementation -MAGNUM_APPLICATION_MAIN(MyApplication) -@endcode +@snippet MagnumPlatform.cpp windowed @subsection platform-windowed-viewport Responding to viewport size changes @@ -105,20 +74,7 @@ example by resizing the default framebuffer, you need to reimplement @ref Platform::Sdl2Application::viewportEvent() "viewportEvent()" function and pass the new size to the framebuffer: -@code{.cpp} -class MyApplication: public Platform::Application { - // ... - - private: - void viewportEvent(const Vector2i& size) override; -}; - -// ... - -void MyApplication::viewportEvent(const Vector2i& size) { - defaultFramebuffer.setViewport({{}, size}); -} -@endcode +@snippet MagnumPlatform.cpp size @section platform-windowless Windowless applications @@ -127,13 +83,13 @@ performing tasks on GPU. There is not yet any platform-independent toolkit which could handle this in portable way, thus you have to use platform-specific ones. Magnum provides windowless applications for X11-based Unix, macOS and Windows. To make things simple, as an example we will use only -@ref Platform::WindowlessGlxApplication, see link for bootstrap application +@ref Platform::WindowlessEglApplication, see link for bootstrap application below for fully portable example. -You need to implement just @ref Platform::WindowlessGlxApplication::exec() "exec()" +You need to implement just @ref Platform::WindowlessEglApplication::exec() "exec()" function. The class can be then used directly in @cpp main() @ce, but again, for convenience and portability it's better to use -@ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN() macro. +@ref MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() macro. Similarly as with windowed applications, to simplify the porting, the library provides @cpp Platform::WindowlessApplication @ce typedef and @@ -153,32 +109,7 @@ renderer string and exits is in the following code listing. is available in `windowless` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository. -@code{.cpp} -#include -#include - -using namespace Magnum; - -class MyApplication: public Platform::WindowlessApplication { - public: - MyApplication(const Arguments& arguments); - - int exec() override; -}; - -MyApplication::MyApplication(const Arguments& arguments): Platform::WindowlessApplication(arguments) {} - -int MyApplication::exec() { - Debug() << "OpenGL version:" << Context::current()->versionString(); - Debug() << "OpenGL renderer:" << Context::current()->rendererString(); - - // Exit with success - return 0; -} - -// main() function implementation -MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication) -@endcode +@snippet MagnumPlatform-windowless.cpp windowless @section platform-compilation Compilation with CMake @@ -210,32 +141,14 @@ window size 800x600 pixels). If you want something else, you can pass application constructor. Using method chaining it can be done conveniently like this: -@code{.cpp} -MyApplication::MyApplication(int& argc, char** argv): - Platform::Application(argc, argv, Configuration() - .setTitle("My Application") - .setSize({800, 600})) -{ - // ... -} -@endcode +@snippet MagnumPlatform.cpp configuration However, sometimes you would need to configure the application based on some configuration file or system introspection. In that case you can pass `nullptr` instead of @ref Platform::Sdl2Application::Configuration "Configuration" instance and then specify it later with @ref Platform::Sdl2Application::createContext() "createContext()": -@code{.cpp} -MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) { - // ... - - createContext(Configuration() - .setTitle("My Application") - .setSize(size)); - - // ... -} -@endcode +@snippet MagnumPlatform.cpp createcontext If the context creation in constructor or @ref Platform::Sdl2Application::createContext() "createContext()" fails, the application exits. However, it is also possible to negotiate the @@ -244,20 +157,7 @@ The only difference is that this function returns `false` instead of exiting. You can for example try enabling MSAA and if the context creation fails, fall back to no-AA rendering: -@code{.cpp} -MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) { - // ... - - Configuration conf; - conf.setTitle("My Application") - .setSampleCount(16); - - if(!tryCreateContext(conf)) - createContext(conf.setSampleCount(0)); - - // ... -} -@endcode +@snippet MagnumPlatform.cpp trycreatecontext @section platform-custom Using custom platform toolkits @@ -272,23 +172,11 @@ code listing. @note Fully contained application using with manual Magnum initialization on top of Qt toolkit is available in `base-qt` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository. +@note + There's also @ref examples-triangle-plain-glfw an example showing usage of + plain GLFW to render a basic triangle. -@code{.cpp} -int main(int argc, char** argv) { - // Create OpenGL context ... - - { - // Initialize Magnum - Platform::Context context; - - // Open window, enter main loop ... - - // Magnum context gets destroyed - } - - // Delete OpenGL context ... -} -@endcode +@snippet MagnumPlatform-custom.cpp custom @attention Currently Magnum is limited to single OpenGL context, which must be always set as current. @@ -340,28 +228,7 @@ windowless application header is included. @attention With this approach it is possible to switch between different GL contexts, but make sure that Magnum is used only with its OpenGL context. -@code{.cpp} -int main(int argc, char** argv) { - Platform::WindowlessGLContext glContext{{}}; - glContext.makeCurrent(); - Platform::Context context{argc, argv}; - - // Your GL code ... - - // Make another context current - eglMakeCurrent(); - - // Someone else's code ... - - // Make Magnum context current again - glContext.makeCurrent(); - - // Your GL code again ... - - // Magnum context gets destroyed - // Windowless GL context gets destroyed -} -@endcode +@snippet MagnumPlatform-windowless-custom.cpp custom The main purpose of windowless contexts is threaded OpenGL, used for example for background data processing. The workflow is to create the windowless @@ -373,21 +240,6 @@ current (for example for the main application rendering). See also @note Context creation is not thread safe on all platforms, that's why it still has to be done on the main thread. -@code{.cpp} -int main() { - Platform::WindowlessGLContext glContext{{}}; - - std::thread worker{[&glContext]{ - glContext.makeCurrent(); - Platform::Context context{0, nullptr}; - - // Use Magnum here ... - }}; - - // Independent main application code here ... - - worker.join(); -} -@endcode +@snippet MagnumPlatform-windowless-thread.cpp thread */ } diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt index 076127f11..56651bb94 100644 --- a/doc/snippets/CMakeLists.txt +++ b/doc/snippets/CMakeLists.txt @@ -55,14 +55,39 @@ if(WITH_SDL2APPLICATION) add_executable(getting-started-blue getting-started-blue.cpp) target_link_libraries(getting-started PRIVATE MagnumSdl2Application) target_link_libraries(getting-started-blue PRIVATE MagnumSdl2Application) + + add_library(snippets-MagnumPlatform STATIC MagnumPlatform.cpp) + target_link_libraries(snippets-MagnumPlatform PRIVATE MagnumSdl2Application) + + set_target_properties( + getting-started + getting-started-blue + snippets-MagnumPlatform + PROPERTIES FOLDER "Magnum/doc/snippets") # Otherwise it's not linked correctly. I have no idea why, but whatever. if(CMAKE_VERSION VERSION_LESS 3.0) find_package(SDL2 REQUIRED) target_link_libraries(getting-started PRIVATE SDL2::SDL2) target_link_libraries(getting-started-blue PRIVATE SDL2::SDL2) + target_link_libraries(snippets-MagnumPlatform PRIVATE SDL2::SDL2) endif() +endif() + +if(WITH_WINDOWLESSEGLAPPLICATION) + add_library(snippets-MagnumPlatform-custom STATIC MagnumPlatform-custom.cpp) + add_library(snippets-MagnumPlatform-windowless STATIC MagnumPlatform-windowless.cpp) + add_library(snippets-MagnumPlatform-windowless-custom STATIC MagnumPlatform-windowless-custom.cpp) + add_library(snippets-MagnumPlatform-windowless-thread STATIC MagnumPlatform-windowless-thread.cpp) + + target_link_libraries(snippets-MagnumPlatform-custom PRIVATE MagnumWindowlessEglApplication) + target_link_libraries(snippets-MagnumPlatform-windowless PRIVATE MagnumWindowlessEglApplication) + target_link_libraries(snippets-MagnumPlatform-windowless-custom PRIVATE MagnumWindowlessEglApplication) + target_link_libraries(snippets-MagnumPlatform-windowless-thread PRIVATE MagnumWindowlessEglApplication) + set_target_properties( - getting-started - getting-started-blue + snippets-MagnumPlatform-windowless + snippets-MagnumPlatform-windowless-custom + snippets-MagnumPlatform-windowless-thread + snippets-MagnumPlatform-custom PROPERTIES FOLDER "Magnum/doc/snippets") endif() diff --git a/doc/snippets/MagnumPlatform-custom.cpp b/doc/snippets/MagnumPlatform-custom.cpp new file mode 100644 index 000000000..dc0f9bb3b --- /dev/null +++ b/doc/snippets/MagnumPlatform-custom.cpp @@ -0,0 +1,45 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + 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 + +using namespace Magnum; + +/* [custom] */ +int main() { + // Create OpenGL context ... + + { + /* Initialize Magnum */ + Platform::Context context; + + // Main loop ... + + /* Magnum context gets destroyed */ + } + + // Delete OpenGL context ... +} +/* [custom] */ diff --git a/doc/snippets/MagnumPlatform-windowless-custom.cpp b/doc/snippets/MagnumPlatform-windowless-custom.cpp new file mode 100644 index 000000000..366e2f1f7 --- /dev/null +++ b/doc/snippets/MagnumPlatform-windowless-custom.cpp @@ -0,0 +1,56 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + 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 + +using namespace Magnum; + +EGLDisplay display{}; +EGLSurface surface{}; +EGLContext anotherContext{}; + +/* [custom] */ +int main(int argc, char** argv) { + Platform::WindowlessGLContext glContext{{}}; + glContext.makeCurrent(); + Platform::Context context{argc, argv}; + + // Your GL code ... + + /* Make another context current */ + eglMakeCurrent(display, surface, surface, anotherContext); + + // Someone else's code ... + + /* Make Magnum context current again */ + glContext.makeCurrent(); + + // Your GL code again ... + + /* Magnum context gets destroyed */ + /* Windowless GL context gets destroyed */ +} +/* [custom] */ diff --git a/doc/snippets/MagnumPlatform-windowless-thread.cpp b/doc/snippets/MagnumPlatform-windowless-thread.cpp new file mode 100644 index 000000000..a2e60a334 --- /dev/null +++ b/doc/snippets/MagnumPlatform-windowless-thread.cpp @@ -0,0 +1,47 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + 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 +#include + +using namespace Magnum; + +/* [thread] */ +int main() { + Platform::WindowlessGLContext glContext{{}}; + + std::thread worker{[&glContext]{ + glContext.makeCurrent(); + Platform::Context context; + + // Use Magnum here ... + }}; + + // Independent main application code here ... + + worker.join(); +} +/* [thread] */ diff --git a/doc/snippets/MagnumPlatform-windowless.cpp b/doc/snippets/MagnumPlatform-windowless.cpp new file mode 100644 index 000000000..e5989b13b --- /dev/null +++ b/doc/snippets/MagnumPlatform-windowless.cpp @@ -0,0 +1,52 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + 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. +*/ + +/* [windowless] */ +#include +#include + +using namespace Magnum; + +class MyApplication: public Platform::WindowlessApplication { + public: + MyApplication(const Arguments& arguments); + + int exec() override; +}; + +MyApplication::MyApplication(const Arguments& arguments): + Platform::WindowlessApplication{arguments} {} + +int MyApplication::exec() { + Debug{} << "OpenGL version:" << Context::current().versionString(); + Debug{} << "OpenGL renderer:" << Context::current().rendererString(); + + /* Exit with success */ + return 0; +} + +/* main() function implementation */ +MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication) +/* [windowless] */ diff --git a/doc/snippets/MagnumPlatform.cpp b/doc/snippets/MagnumPlatform.cpp new file mode 100644 index 000000000..7f158a4d0 --- /dev/null +++ b/doc/snippets/MagnumPlatform.cpp @@ -0,0 +1,145 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + 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. +*/ + +/* [windowed] */ +#include +#include +#include +#include +#include + +using namespace Magnum; + +class MyApplication: public Platform::Application { + public: + MyApplication(const Arguments& arguments); + + private: + void drawEvent() override; +}; + +MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} { + using namespace Math::Literals; + /* Set clear color to dark blue */ + Renderer::setClearColor(0x000066_rgbf); +} + +void MyApplication::drawEvent() { + /* Clear the window */ + defaultFramebuffer.clear(FramebufferClear::Color); + + /* The context is double-buffered, swap buffers */ + swapBuffers(); +} + +/* main() function implementation */ +MAGNUM_APPLICATION_MAIN(MyApplication) +/* [windowed] */ + +namespace B { + +/* [size] */ +class MyApplication: public Platform::Application { + // ... + + private: + void viewportEvent(const Vector2i& size) override; +}; + +// ... + +void MyApplication::viewportEvent(const Vector2i& size) { + defaultFramebuffer.setViewport({{}, size}); +} +/* [size] */ + +} + +namespace C { + +struct MyApplication: Platform::Application { + MyApplication(const Arguments& arguments); +}; + +/* [configuration] */ +MyApplication::MyApplication(const Arguments& arguments): + Platform::Application(arguments, Configuration{} + .setTitle("My Application") + .setSize({800, 600})) +{ + // ... +} +/* [configuration] */ + +} + +namespace D { + +constexpr Vector2i size; + +struct MyApplication: Platform::Application { + MyApplication(const Arguments& arguments); +}; + +/* [createcontext] */ +MyApplication::MyApplication(const Arguments& arguments): + Platform::Application{arguments, NoCreate} +{ + // ... + + createContext(Configuration{} + .setTitle("My Application") + .setSize(size)); + + // ... +} +/* [createcontext] */ + +} + +namespace E { + +struct MyApplication: Platform::Application { + MyApplication(const Arguments& arguments); +}; + +/* [trycreatecontext] */ +MyApplication::MyApplication(const Arguments& arguments): + Platform::Application{arguments, NoCreate} +{ + // ... + + Configuration conf; + conf.setTitle("My Application") + .setSampleCount(16); + + if(!tryCreateContext(conf)) + createContext(conf.setSampleCount(0)); + + // ... +} +/* [trycreatecontext] */ + +}