From fa014ad131a0781f0ac891880855e67aa86a2270 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 8 Jan 2018 12:30:17 +0100 Subject: [PATCH] doc: using an actual snippet from the getting started app source. --- doc/generated/CMakeLists.txt | 5 -- doc/generated/README.md | 15 ------ doc/getting-started.dox | 45 ++-------------- doc/snippets/CMakeLists.txt | 11 ++++ doc/snippets/README.md | 11 ++++ .../getting-started-blue.cpp} | 35 +++++++----- doc/snippets/getting-started.cpp | 53 +++++++++++++++++++ 7 files changed, 100 insertions(+), 75 deletions(-) create mode 100644 doc/snippets/README.md rename doc/{generated/hello.cpp => snippets/getting-started-blue.cpp} (73%) create mode 100644 doc/snippets/getting-started.cpp diff --git a/doc/generated/CMakeLists.txt b/doc/generated/CMakeLists.txt index 0ef89b491..175afcaa5 100644 --- a/doc/generated/CMakeLists.txt +++ b/doc/generated/CMakeLists.txt @@ -49,11 +49,6 @@ endif() configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake ${CMAKE_CURRENT_BINARY_DIR}/configure.h) -add_executable(hello hello.cpp) -target_link_libraries(hello - Magnum::Magnum - Magnum::Application) - add_executable(shaders shaders.cpp) target_include_directories(shaders PRIVATE ${CMAKE_CURRENT_BINARY_DIR}) target_link_libraries(shaders diff --git a/doc/generated/README.md b/doc/generated/README.md index e3f8bdbdc..dd8a85e8c 100644 --- a/doc/generated/README.md +++ b/doc/generated/README.md @@ -12,21 +12,6 @@ Create build dir, point CMake to this directory and compile the executables: cmake ../doc/generated cmake --build . -### "Getting started" image - -Displayed by the `hello` executable. Run the app and take screenshot using -KSnapshot (including decorations, 880x707). Similarly for the gray version. The -resulting files should be resized to half the size and without alpha channel -using imagemagick: - -```bash -mogrify -flatten -background '#ffffff' -resize 440 getting-started.png -mogrify -flatten -background '#ffffff' -resize 440 getting-started-blue.png -``` - -The output printed by the application can be used to update the example output -in `doc/getting-started.dox`. - ### Shader images Generated by the `shaders` executable. Must be run in this directory, the diff --git a/doc/getting-started.dox b/doc/getting-started.dox index d6cac97ee..73ba4b75b 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -115,34 +115,7 @@ The `src/` directory contains the actual project. To keep things simple, the project consists of just a single `MyApplication.cpp` file with the most minimal code possible: -@code{.cpp} -#include -#include - -using namespace Magnum; - -class MyApplication: public Platform::Application { - public: - explicit MyApplication(const Arguments& arguments); - - private: - void drawEvent() override; -}; - -MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} { - // TODO: Add your initialization code here -} - -void MyApplication::drawEvent() { - defaultFramebuffer.clear(FramebufferClear::Color); - - // TODO: Add your drawing code here - - swapBuffers(); -} - -MAGNUM_APPLICATION_MAIN(MyApplication) -@endcode +@snippet getting-started.cpp 0 The application essentially does nothing, just clears the screen framebuffer to default (dark gray) color and then does buffer swap to actually display it on @@ -229,24 +202,12 @@ the concepts of graphics programming, we can change the clear color to something else and also print basic information about the GPU the engine is running on. First include the needed headers: -@code{.cpp} -#include -#include -#include -#include -@endcode +@snippet getting-started-blue.cpp 0 And in the constructor (which is currently empty) change the clear color and print something to debug output: -@code{.cpp} - using namespace Magnum::Math::Literals; - - Renderer::setClearColor(0xa5c9ea_rgbf); - - Debug() << "Hello! This application is running on" << Context::current().version() - << "using" << Context::current().rendererString(); -@endcode +@snippet getting-started-blue.cpp 1 After rebuilding and starting the application, the clear color changes to blueish one and something like this would be printed to the console: diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt index 56890c925..dfb74f9c9 100644 --- a/doc/snippets/CMakeLists.txt +++ b/doc/snippets/CMakeLists.txt @@ -40,3 +40,14 @@ if(WITH_DEBUGTOOLS AND Corrade_TestSuite_FOUND AND NOT CORRADE_TARGET_IOS) target_include_directories(debugtools-compareimage PRIVATE ${CMAKE_CURRENT_BINARY_DIR}) set_target_properties(debugtools-compareimage PROPERTIES FOLDER "Magnum/doc/snippets") endif() + +if(WITH_SDL2APPLICATION) + add_executable(getting-started getting-started.cpp) + add_executable(getting-started-blue getting-started-blue.cpp) + target_link_libraries(getting-started PRIVATE MagnumSdl2Application) + target_link_libraries(getting-started-blue PRIVATE MagnumSdl2Application) + set_target_properties( + getting-started + getting-started-blue + PROPERTIES FOLDER "Magnum/doc/snippets") +endif() diff --git a/doc/snippets/README.md b/doc/snippets/README.md new file mode 100644 index 000000000..ab329f282 --- /dev/null +++ b/doc/snippets/README.md @@ -0,0 +1,11 @@ +Snippets that possibly generate output for Magnum documentation +############################################################### + +### "Getting started" image + +Displayed by the `getting-started` executable. Run the app and take screenshot +using Spectacle (including decorations, 880x707). Similarly for the gray +version. The resulting files should be resized to half. + +The output printed by the application can be used to update the example output +in `doc/getting-started.dox`. diff --git a/doc/generated/hello.cpp b/doc/snippets/getting-started-blue.cpp similarity index 73% rename from doc/generated/hello.cpp rename to doc/snippets/getting-started-blue.cpp index 526ffefb0..b0a3ca3f0 100644 --- a/doc/generated/hello.cpp +++ b/doc/snippets/getting-started-blue.cpp @@ -23,33 +23,42 @@ DEALINGS IN THE SOFTWARE. */ -#include #include +#include +/** [0] */ +#include #include #include #include -#include +/** [0] */ using namespace Magnum; -using namespace Magnum::Math::Literals; -class Hello: public Platform::Application { -public: - explicit Hello(const Arguments& arguments); +class MyApplication: public Platform::Application { + public: + explicit MyApplication(const Arguments& arguments); -private: - void drawEvent() override; + private: + void drawEvent() override; }; -Hello::Hello(const Arguments& arguments): Platform::Application(arguments) { - Renderer::setClearColor(Color3::fromHSV(216.0_degf, 0.85f, 1.0f)); - Debug() << "Hello! This application is running on" << Context::current().version() +/** [1] */ +MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} { + using namespace Magnum::Math::Literals; + + Renderer::setClearColor(0xa5c9ea_rgbf); + + Debug{} << "Hello! This application is running on" << Context::current().version() << "using" << Context::current().rendererString(); } +/** [1] */ -void Hello::drawEvent() { +void MyApplication::drawEvent() { defaultFramebuffer.clear(FramebufferClear::Color); + + // TODO: Add your drawing code here + swapBuffers(); } -MAGNUM_APPLICATION_MAIN(Hello) +MAGNUM_APPLICATION_MAIN(MyApplication) diff --git a/doc/snippets/getting-started.cpp b/doc/snippets/getting-started.cpp new file mode 100644 index 000000000..d83aa0f2a --- /dev/null +++ b/doc/snippets/getting-started.cpp @@ -0,0 +1,53 @@ +/* + 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. +*/ + +/** [0] */ +#include +#include + +using namespace Magnum; + +class MyApplication: public Platform::Application { + public: + explicit MyApplication(const Arguments& arguments); + + private: + void drawEvent() override; +}; + +MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} { + // TODO: Add your initialization code here +} + +void MyApplication::drawEvent() { + defaultFramebuffer.clear(FramebufferClear::Color); + + // TODO: Add your drawing code here + + swapBuffers(); +} + +MAGNUM_APPLICATION_MAIN(MyApplication) +/** [0] */