Downloading and building examples
Guide how to download and build examples for the Magnum engine.
Examples demonstrate Magnum features, usage and capabilities. They are not needed for essential usage, but are useful for learning purposes in addition to the documentation itself.
Prepared packages
The easiest way to install Magnum Examples is to use one of the ready-made packages for your platform of choice. See Manual build if you want to have more control. Cross-compiling is very similar to cross-compiling of Magnum itself.
- ArchLinux packages
- Packages for Debian, Ubuntu and derivatives
- Gentoo Linux ebuilds
- Packages for Fedora, openSUSE and other RPM-based Linux distributions
- Homebrew formulas for macOS
ArchLinux packages
In package/archlinux/magnum-examples-git
there is a package for Git development build. The package is also in AUR as The package is also in AUR as magnum-examples-git. It depends on Corrade, Magnum, Magnum Plugins, Magnum Extras and Magnum Integration ArchLinux packages.
There are also quite a few development packages for native builds or cross-compilation for Emscripten, Android and MinGW. See the PKGBUILD files in the package/archlinux
directory. They allow you to build and install the package directly from the source tree. Example usage:
git clone https://github.com/mosra/magnum-examples && cd magnum-examples cd package/archlinux makepkg -fp PKGBUILD # or any other PKGBUILD file
Once built, install the package using pacman
:
sudo pacman -U magnum-examples-*.pkg.tar.zst
Edit the PKGBUILDs if you want to pass additional flags to CMake or enable / disable additional features.
Packages for Debian, Ubuntu and derivatives
The package/debian/
directory contains all files needed for building Debian packages. You need Corrade, Magnum, Magnum Plugins, Magnum Extras and Magnum Integration Debian packages installed and in addition also the dpkg-dev
and debhelper
packages. Building is easy, just change directory to package root, link or copy the package/debian
directory there and run dpkg-buildpackage
:
git clone https://github.com/mosra/magnum-examples && cd magnum-examples ln -s package/debian . dpkg-buildpackage --no-sign
This will compile binary and development packages, which will then appear in a parent directory. Install them using dpkg
:
sudo dpkg -i ../magnum-examples*.deb
If you want to pass additional flags to CMake or enable / disable additional features, add them to dh_auto_configure
at the bottom of debian/rules
. Watch out, as indentation has to be done using tabs, not spaces.
Gentoo Linux ebuilds
Gentoo Git ebuild is available in the package/gentoo
directory. Get the Corrade, Magnum, Magnum Plugins, Magnum Extras and Magnum Integration Gentoo packages first and then build and install Magnum Examples like this:
git clone https://github.com/mosra/magnum-examples && cd magnum-examples cd package/gentoo sudo ebuild dev-libs/magnum-examples/magnum-examples-9999.ebuild manifest clean merge
If you want to pass additional flags to CMake or enable / disable additional features, add them to mycmakeargs
in the *.ebuild
file.
Packages for Fedora, openSUSE and other RPM-based Linux distributions
Spec files for RPM-based distributions are in the package/rpm/
directory. In addition you will need to install the following dependencies in order to build the packages (assuming Fedora Linux):
sudo dnf install fedora-packager rpmdevtools
After that, make sure you build and install the Corrade, Magnum, Magnum Plugins, Magnum Extras and Magnum Integration RPM packages first, and run the build.sh
script. Internally it queries the Git version, makes a tarball, may ask you to install appropriate dependencies if not present already, and then builds the package.
./package/rpm/build.sh
At the end, if everything succeeds, you'll have the newly built packages located in ~/rpmbuild/RPMS
. The script will print their names at the end.
If you want to pass additional flags to CMake or enable / disable additional features, edit the *.spec
file.
Homebrew formulas for macOS
macOS Homebrew formulas building the latest Git revision are in the package/homebrew
directory. Either use the *.rb
files directly or use the tap at https:/
brew install mosra/magnum/magnum-examples
But often you may want to install the latest Git revision of all Magnum projects instead:
brew install --HEAD mosra/magnum/corrade brew install --HEAD mosra/magnum/magnum brew install --HEAD mosra/magnum/magnum-plugins brew install --HEAD mosra/magnum/magnum-integration brew install --HEAD mosra/magnum/magnum-extras brew install --HEAD mosra/magnum/magnum-examples # If already installed, use the following to upgrade, in the same order brew upgrade --fetch-HEAD mosra/magnum/corrade brew upgrade --fetch-HEAD mosra/magnum/magnum brew upgrade --fetch-HEAD mosra/magnum/magnum-plugins brew upgrade --fetch-HEAD mosra/magnum/magnum-integration brew upgrade --fetch-HEAD mosra/magnum/magnum-extras brew upgrade --fetch-HEAD mosra/magnum/magnum-examples
When installing from the *.rb
files you need to install the Corrade, Magnum, Magnum Plugins, Magnum Extras and Magnum Integration Homebrew packages first. If you want to pass additional flags to CMake or enable / disable additional features, edit the *.rb
file.
Manual build
The source is available on GitHub: https:/master
in order to keep the example code as simple as possible.
Enabling or disabling features
By default only the Triangle example is built. All examples depend on various libraries from the core Magnum repository and the Platform::
MAGNUM_WITH_ANIMATED_GIF_EXAMPLE
– Build the Animated GIF example. Requires StbImageImporter.MAGNUM_WITH_ARCBALL_EXAMPLE
– Build the ArcBall Camera example.MAGNUM_WITH_AREALIGHTS_EXAMPLE
– Build the Area Lights example. Requires the Ui library and some TTF font plugin such as FreeTypeFont.MAGNUM_WITH_AUDIO_EXAMPLE
— Build the Audio example. Requires the Audio library and the StbVorbisAudioImporter plugin.MAGNUM_WITH_BOX2D_EXAMPLE
— Build the Box2D example. Depends on Box2D.MAGNUM_WITH_BULLET_EXAMPLE
— Build the Bullet Physics example. Requires the BulletIntegration library.MAGNUM_WITH_CUBEMAP_EXAMPLE
— Build the Cube Map example. Requires some JPEG importer plugin such as JpegImporter, not available in OpenGL ES.MAGNUM_WITH_DART_EXAMPLE
— Build the DART Physics example. Requires the DartIntegration library.MAGNUM_WITH_FLUIDSIMULATION3D_EXAMPLE
– Build the 3D Fluid Simulation example.MAGNUM_WITH_LEAPMOTION_EXAMPLE
— Build the Leap Motion example.MAGNUM_WITH_MOTIONBLUR_EXAMPLE
— Build the Motion blur example. Not available on OpenGL ES.MAGNUM_WITH_MOUSEINTERACTION_EXAMPLE
— Build the Mouse Interaction example.MAGNUM_WITH_OCTREE_EXAMPLE
— Build the Octree example.MAGNUM_WITH_OVR_EXAMPLE
— Build the Oculus VR example. Requires the OvrIntegration library.MAGNUM_WITH_PICKING_EXAMPLE
— Build the Object Picking example.MAGNUM_WITH_PRIMITIVES_EXAMPLE
— Build the Primitives example.MAGNUM_WITH_RAYTRACING_EXAMPLE
— Build the RayTracing example.MAGNUM_WITH_SHADOWS_EXAMPLE
— Build the Shadow map example.MAGNUM_WITH_TEXT_EXAMPLE
— Build the Text rendering example. Requires the Text library and some TTF font plugin such as FreeTypeFont.MAGNUM_WITH_TEXTUREDQUAD_EXAMPLE
— Build the Textured Quad example. Requires some TGA importer plugin such as TgaImporter, not available in OpenGL ES.MAGNUM_WITH_TEXTUREDTRIANGLE_VULKAN_EXAMPLE
— Build the Vulkan Textured Triangle example. Requires the ShaderTools, Vk and Trade libraries, the SpirvToolsShaderConverter plugin and somePngImporter
andPngImageConverter
plugin implementation.MAGNUM_WITH_TRIANGLE_EXAMPLE
— Build the Triangle example. Enabled by default.MAGNUM_WITH_TRIANGLE_PLAIN_GLFW_EXAMPLE
— Build the Plain GLFW Triangle example. Depends on GLFW and a*Context
library for given platform.MAGNUM_WITH_TRIANGLE_SOKOL_EXAMPLE
— Build the sokol_gfx Triangle example. Depends on GLEW. MAGNUM_WITH_TRIANGLE_VULKAN_EXAMPLE
— Build the Vulkan Triangle example. Requires the ShaderTools, Vk and Trade libraries, the SpirvToolsShaderConverter plugin and somePngImageConverter
plugin implementation.MAGNUM_WITH_VIEWER_EXAMPLE
— Build the Viewer example. Requires the AnySceneImporter plugin.MAGNUM_WITH_WEBXR_EXAMPLE
— Build the WebXR example. Available only on Emscripten.
Some examples accept additional options:
MAGNUM_FLUIDSIMULATION3D_EXAMPLE_USE_MULTITHREADING
— Controls multithreading for the 3D Fluid Simulation example.ON
by default.MAGNUM_FLUIDSIMULATION3D_EXAMPLE_USE_TBB
— If enabled together withMAGNUM_FLUIDSIMULATION3D_EXAMPLE_USE_MULTITHREADING
, uses Intel TBB for parallel processing in the 3D Fluid Simulation example.OFF
by default.
Besides building the whole project and enabling a particular subset of examples, it's also possible to build each example as if the example itself would be a project root. For example:
cd magnum-examples mkdir build-cubemap && cd build-cubemap cmake ../src/cubemap # ...
Building documentation
The documentation for examples is built as part of of the main Magnum documentation. Clone the projects next to each other and continue as described in Building documentation.
Continuous Integration
CircleCI
In package/ci/
there is a circle.yml
file with Linux GCC 4.8, macOS, Linux desktop GLES2/GLES3, Emscripten WebGL1/WebGL2, AddressSanitizer and ThreadSanitizer configuration. Online at https:/
Travis
In package/ci/
there is a travis.yml
file with iOS GLES2/GLES3 and Android GLES2/GLES3 configuration. Online at https:/
AppVeyor
In package/ci/
there is an appveyor.yml
file with Windows desktop MSVC, MinGW, Windows desktop GLES2/GLES3 and Windows RT GLES2/GLES3 configuration. Online at https:/