Get started with Magnum in matter of minutes.
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 the first project you need the
base branch, which contains only the essential files. 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 with clean history.
If you want to (or have to) use GLUT instead of SDL2, download the
base-glut branch archive instead of
base branch. The code will be slightly different from what is presented below, but the changes are only minor (two modified lines) and the main principles are the same.
Magnum libraries support both separate compilation/installation and CMake subprojects. We'll use the subproject approach now, because adding the dependencies means just cloning them into your project tree:
cd /path/to/the/extracted/bootstrap/project git clone git://github.com/mosra/corrade.git git clone git://github.com/mosra/magnum.git
Then open the
CMakeLists.txt file in the root of bootstrap project and add these two new subdirectories using
add_subdirectory() so the file looks like this:
If you want to install Corrade and Magnum separately instead of cloning them into your project tree, just follow the installation guides mentioned above. Don't forget to enable
WITH_GLUTAPPLICATION, if you are using GLUT) when building Magnum so the bootstrap project can use it later.
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
In root there is project-wide
CMakeLists.txt, which you have seen above. It just sets up project name, specifies module directory and delegates everything important to
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.
src/ contains the actual project. To keep things simple, the project consists of just one source file with the most minimal code possible:
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. The
src/CMakeLists.txt file finds Magnum, creates the executable and links it to all needed libraries:
In the following tutorials the code will be explained more thoroughly.
In Linux (and other Unix-based OSs) you can build the application along with the subprojects using the following three commands: create out-of-source build directory, run cmake, enable SDL2 application in the Magnum subproject and then build everything. The compiled application binary will then appear in
src/ subdirectory of the build dir:
mkdir -p build && cd build cmake .. -DWITH_SDL2APPLICATION=ON cmake --build . ./src/MyApplication
On Windows you can use either MSVC or MinGW-w64 compiler. It's then up to you whether you will use command-line, 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 .. -DWITH_SDL2APPLICATION=ON
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. the
-DWITH_SDL2APPLICATION=ON parameter) and then you can just press Configure and everything is ready to be built.
If you have SDL2 in a non-standard location and CMake can't find it, you need to specify where SDL
lib/ directories are through
CMAKE_PREFIX_PATH. So, for example, on Windows, the full CMake invocation might look like this:
cmake .. -DCMAKE_PREFIX_PATH="C:/Users/you/Downloads/SDL2-2.0.4" -DWITH_SDL2APPLICATION=ON
On Windows you may get errors about missing DLLs when running the application. The solution is either compiling everything as static (enable
BUILD_STATIC CMake option) or installing the dependencies somewhere. To install them, change
CMAKE_INSTALL_PREFIX to your liking and run the
install target. Then run the application with
bin/ subdirectory of installation prefix as working dir or add the
bin/ subdirectory to
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:
And in the constructor (which is currently empty) change the clear color and print something to debug output:
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
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!