doc: converted Platform docs to use compiled code snippets.

They got terribly outdated over the years, ugh.

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}
+@snippet MagnumPlatform.cpp windowed
-#include <Magnum/DefaultFramebuffer.h>
-#include <Magnum/Renderer.h>
-#include <Magnum/Math/Color.h>
-#include <Magnum/Platform/Sdl2Application.h>
-
-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
 
 @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}
+@snippet MagnumPlatform.cpp size
-class MyApplication: public Platform::Application {
-    // ...
-
-    private:
-        void viewportEvent(const Vector2i& size) override;
-};
-
-// ...
-
-void MyApplication::viewportEvent(const Vector2i& size) {
-    defaultFramebuffer.setViewport({{}, size});
-}
-@endcode
 
 @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}
+@snippet MagnumPlatform-windowless.cpp windowless
-#include <Magnum/Context.h>
-#include <Magnum/Platform/WindowlessGlxApplication.h>
-
-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
 
 @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}
+@snippet MagnumPlatform.cpp configuration
-MyApplication::MyApplication(int& argc, char** argv):
-    Platform::Application(argc, argv, Configuration()
-        .setTitle("My Application")
-        .setSize({800, 600}))
-{
-    // ...
-}
-@endcode
 
 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}
+@snippet MagnumPlatform.cpp createcontext
-MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) {
-    // ...
-
-    createContext(Configuration()
-        .setTitle("My Application")
-        .setSize(size));
-
-    // ...
-}
-@endcode
 
 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}
+@snippet MagnumPlatform.cpp trycreatecontext
-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
 
 @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}
+@snippet MagnumPlatform-custom.cpp custom
-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
 
 @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}
+@snippet MagnumPlatform-windowless-custom.cpp 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();
-
-    // 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
 
 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}
+@snippet MagnumPlatform-windowless-thread.cpp thread
-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
 */
 }

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
+        snippets-MagnumPlatform-windowless
-        getting-started-blue
+        snippets-MagnumPlatform-windowless-custom
+        snippets-MagnumPlatform-windowless-thread
+        snippets-MagnumPlatform-custom
         PROPERTIES FOLDER "Magnum/doc/snippets")
 endif()

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š <mosra@centrum.cz>
+
+    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 <Magnum/Platform/Context.h>
+
+using namespace Magnum;
+
+/* [custom] */
+int main() {
+    // Create OpenGL context ...
+
+    {
+        /* Initialize Magnum */
+        Platform::Context context;
+
+        // Main loop ...
+
+        /* Magnum context gets destroyed */
+    }
+
+    // Delete OpenGL context ...
+}
+/* [custom] */

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š <mosra@centrum.cz>
+
+    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 <Magnum/Platform/WindowlessEglApplication.h>
+#include <Magnum/Platform/Context.h>
+
+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] */

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š <mosra@centrum.cz>
+
+    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 <thread>
+#include <Magnum/Platform/WindowlessEglApplication.h>
+#include <Magnum/Platform/Context.h>
+
+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] */

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š <mosra@centrum.cz>
+
+    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 <Magnum/Context.h>
+#include <Magnum/Platform/WindowlessEglApplication.h>
+
+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] */

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š <mosra@centrum.cz>
+
+    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 <Magnum/DefaultFramebuffer.h>
+#include <Magnum/Renderer.h>
+#include <Magnum/Math/Color.h>
+#include <Magnum/Platform/Sdl2Application.h>
+#include <Magnum/Platform/Context.h>
+
+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] */
+
+}