Magnum
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Getting started

Table of Contents

Get started with Magnum in matter of minutes.

Download, build and install Magnum

Get latest version from GitHub and install it. Read full guide on 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.

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 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 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. 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 so the compatibility mode gets properly detected and used.

Review project structure

The base project consists of just six files in two subfolders. Magnum uses CMake build system, see Usage with 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.

cmake_minimum_required(VERSION 2.8.8)
project(MyApplication)
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/modules/")
add_subdirectory(src)

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:

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)

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:

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})

In the following tutorials the code will be explained more thoroughly.

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 Building on Windows. If CMake complains about Sdl2Application missing, you forgot to enable WITH_SDL2APPLICATION when building Magnum, go back and fix it.

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:

#include <Magnum/Color.h>
#include <Magnum/Context.h>
#include <Magnum/Version.h>

And in the constructor (which is currently empty) change the clear color and print something to debug output:

Renderer::setClearColor({0.07f, 0.44f, 0.73f});
Debug() << "Hello! This application is running on" << Context::current()->version()
<< "using" << Context::current()->rendererString();

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 3.3 using Geforce GT 330M

getting-started-blue.png

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 step-by-step tutorial. Then you can dig deeper and try other examples, read about fundamental principles in the documentation and start experimenting on your own!

Additional information