magnum/doc/getting-started.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014
              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.
*/

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 SDL2 toolkit, don't forget to enable
it for building using `WITH_SDL2APPLICATION` CMake parameter. On older Linux
distributions which don't have SDL2 in the repositories you might want to use
GLUT toolkit instead, it is enabled 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.

If you want to use GLUT instead of SDL2, download the `base-glut` branch
[archive](https://github.com/mosra/magnum-bootstrap/archive/base-glut.zip).
The code will be slightly different from what is presented below, but the
changes are only minor (two modified lines and one additional file) and the
main principles are the same.

If you are using `compatibility` branch of Magnum and Corrade, replace
`modules/FindCorrade.cmake` with [the one from `compatibility` branch](https://github.com/mosra/corrade/blob/compatibility/modules/FindCorrade.cmake)
so the compatibility mode gets properly detected and used.

@section getting-started-review Review project structure

The base project consists of just six files in two subfolders. Magnum uses
CMake build system, see @ref cmake for more information.

    modules/FindCorrade.cmake
    modules/FindMagnum.cmake
    modules/FindSDL2.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.9)
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. 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 <Magnum/DefaultFramebuffer.h>
#include <Magnum/Platform/Sdl2Application.h>

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

The application essentially does nothing, just clears screen framebuffer to
default (dark gray) 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 Sdl2Application)

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 you can use either MinGW or MSVC 2013 compiler. It's then up to you
whether you will use QtCreator or Visual Studio. With Visual Studio the most
straightforward way to create the project file is via the command-line:

    mkdir build
    cd build
    cmake -DCMAKE_PREFIX_PATH="C:/Sys" ..

You can also use CMake GUI. Then open the `MyApplication.sln` project file
generated by CMake in the build directory.

With QtCreator just open project's root `CMakeLists.txt` file. It then asks you
where to create build directory, allows you to specify initial CMake parameters
(e.g. `CMAKE_PREFIX_PATH`) and then you can just press *Configure* and
everything is ready to be built.

If CMake isn't able to find the dependencies on Windows, you might want to look
at @ref building-windows. If CMake complains about `Sdl2Application` missing,
you forgot to enable `WITH_SDL2APPLICATION` when building Magnum,
@ref getting-started-download "go back and fix it".

@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 <Magnum/Color.h>
#include <Magnum/Context.h>
#include <Magnum/Renderer.h>
#include <Magnum/Version.h>
@endcode

And in the constructor (which is currently empty) change the clear color and
print something to debug output:
@code
Renderer::setClearColor(Color3::fromHSV(216.0_degf, 0.85f, 1.0f));

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:

> Hello! This application is running on OpenGL 4.5 using GeForce GT 740M

@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

*/
}