diff --git a/Doxyfile b/Doxyfile index d9dff7fed..9bb7567bd 100644 --- a/Doxyfile +++ b/Doxyfile @@ -775,7 +775,8 @@ EXAMPLE_RECURSIVE = NO # directories that contain image that are included in the documentation (see # the \image command). -IMAGE_PATH = ../magnum-examples/src/ +IMAGE_PATH = doc/ \ + ../magnum-examples/src/ # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/README.md b/README.md index 33299aa2c..d88d832df 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,9 @@ There are also examples of engine usage, varying from simple *Hello World*-like example to more advanced applications, such as viewer for complex 3D models. Example repository is at https://github.com/mosra/magnum-examples. +Repository with bootstrap projects for many use cases, helping you get up and +running in no time is located at https://github.com/mosra/magnum-bootstrap. + CONTACT ======= diff --git a/doc/getting-started-blue.png b/doc/getting-started-blue.png new file mode 100644 index 000000000..554613df2 Binary files /dev/null and b/doc/getting-started-blue.png differ diff --git a/doc/getting-started.dox b/doc/getting-started.dox new file mode 100644 index 000000000..d98af28d5 --- /dev/null +++ b/doc/getting-started.dox @@ -0,0 +1,202 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013 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. +*/ + +namespace Magnum { +/** @page getting-started Getting started +@brief Get started with %Magnum in matter of minutes. + +@tableofcontents + +@section getting-started-download Download, build and install Magnum + +Get latest version from GitHub and install it. Read full guide on +@ref building "how to download, build and install Magnum" on platform of your +choice. For our first project we will use GLUT toolkit, don't forget to enable +it for building using `WITH_GLUTAPPLICATION` CMake parameter. + +@section getting-started-bootstrap Download bootstrap project + +Setting up a new project can be pretty gruesome and nobody likes repeating the +same process every time. %Magnum provides "bootstrap" project structures for +many use cases, helping you get up and running in no time. + +The [bootstrap repository](https://github.com/mosra/magnum-bootstrap) is +located on GitHub. The `master` branch contains just an README file and the +actual bootstrap projects are in various other branches, each covering some +particular use case. For your first project you would need the `base` branch, +which contains only the essential files you need. Download the branch [as an +archive](https://github.com/mosra/magnum-bootstrap/archive/base.zip) and +extract it somewhere. Do it rather than cloning the full repository, as it's +better to init your own repository from scratch to avoid having the history +polluted. + +@section getting-started-review Review project structure + +The base project consists of just seven files in two subfolders. %Magnum uses +CMake build system, see @ref cmake for more information. + + modules/FindCorrade.cmake + modules/FindMagnum.cmake + modules/FindGLEW.cmake + src/MyApplication.cpp + src/CMakeLists.txt + CMakeLists.txt + .gitignore + +In root there is pre-filled `.gitignore` for your Git project and also +project-wide `CMakeLists.txt`. It just sets up project name, specifies module +directory and delegates everything important to `CMakeLists.txt` in `src/` +subdirectory. +@code +cmake_minimum_required(VERSION 2.8.8) +project(MyApplication) + +set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/modules/") + +add_subdirectory(src) +@endcode + +Directory `modules/` contains CMake modules for finding the needed +dependencies. Unlike modules for finding e.g. GLUT and OpenGL, which are part +of standard CMake installation, these aren't part of it and thus must be +distributed with the project. These files are just verbatim copied from %Magnum +repository. + +Directory `src/` contains the actual project. To keep things simple, the +project consists of just one source file with the most minimal code possible: +@code +#include +#include + +using namespace Magnum; + +class MyApplication: public Platform::Application { + public: + explicit MyApplication(const Arguments& arguments); + + protected: + void viewportEvent(const Vector2i& size) override; + void drawEvent() override; +}; + +MyApplication::MyApplication(const Arguments& arguments): Platform::Application(arguments) {} + +void MyApplication::viewportEvent(const Vector2i& size) { + defaultFramebuffer.setViewport({{}, size}); +} + +void MyApplication::drawEvent() { + defaultFramebuffer.clear(FramebufferClear::Color); + swapBuffers(); +} + +MAGNUM_APPLICATION_MAIN(MyApplication) +@endcode + +The application essentially does nothing, just clears properly sized screen +framebuffer to default (black) color and then does buffer swap to actually +display it on the screen. `CMakeLists.txt` finds %Magnum, sets up compiler +flags, creates the executable and links it to all needed libraries: +@code +find_package(Magnum REQUIRED GlutApplication) + +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CORRADE_CXX_FLAGS}") +include_directories(${MAGNUM_INCLUDE_DIRS} ${MAGNUM_APPLICATION_INCLUDE_DIRS}) + +add_executable(MyApplication MyApplication.cpp) +target_link_libraries(MyApplication + ${MAGNUM_LIBRARIES} + ${MAGNUM_APPLICATION_LIBRARIES}) +@endcode + +In the following tutorials the code will be explained more thoroughly. + +@section getting-started-build Build it and run + +In Linux (and other Unix-based OSs) you can build the example using the +following three commands: create out-of-source build directory, run cmake in it +and then run make. The application binary will then appear in src/ subdirectory +of build dir: + + mkdir -p build && cd build + cmake .. + make + ./src/MyApplication + +On Windows, if you don't want to touch the command-line, the easiest way is to +open root `CMakeLists.txt` in QtCreator, let it import the project and then +just build and run the application. If CMake isn't able to find the +dependencies or the building fails for some reason, you might want to look at +@ref building-windows-troubleshooting. + +@image html getting-started.png +@image latex getting-started.png + +Now you can try to change something in the code. Without going too deep into +the concepts of graphics programming, we can change clear color to something +else and also print basic information about the GPU the engine is running on. +First include the needed headers: +@code +#include +#include +#include +@endcode + +And in the constructor (which is currently empty) change the clear color and +print something to debug output: +@code +Renderer::setClearColor({0.07f, 0.44f, 0.73f}); + +Debug() << "Hello! This application is running on" << Context::current()->version() + << "using" << Context::current()->rendererString(); +@endcode + +After rebuilding and starting the application, the clear color changes to +blueish one and something like this would be printed to the console: +@code +Hello! This application is running on OpenGL 3.3 using Geforce GT 330M +@endcode + +@image html getting-started-blue.png +@image latex getting-started-blue.png + +@section getting-started-tutorials Follow tutorials and learn the principles + +Now that you have your first application up and running, the best way to +continue is to render your first triangle in @ref example-index "step-by-step tutorial". +Then you can dig deeper and try other examples, read about +@ref features "fundamental principles" in the documentation and start +experimenting on your own! + +@section getting-started-more Additional information + +- @subpage building +- @subpage building-plugins +- @subpage building-integration +- @subpage cmake +- @subpage cmake-plugins +- @subpage cmake-integration + +*/ +} diff --git a/doc/getting-started.png b/doc/getting-started.png new file mode 100644 index 000000000..cc0fc6112 Binary files /dev/null and b/doc/getting-started.png differ diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 38697a952..d2fac13bf 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -83,16 +83,10 @@ namespace Magnum { - Pre-made shaders, primitives and other tools for easy prototyping and debugging. -@section mainpage-download-build Downloading and building Magnum - -Guide @ref building "how to download and build Magnum" on different platforms. - @section mainpage-getting-started Getting started -The best way to get started is to render your first triangle in -@ref example-index "step-by-step tutorial". Then you can dig deeper and try -other examples, read about @ref features "fundamental principles" in the -documentation or start experimenting on your own! +@ref getting-started "Thorough guide" to download, build, install and start +using Magnum in your project. @section mainpage-hacking Hacking Magnum