GitHub - mosra/magnum-bootstrap: Bootstrap projects for the Magnum C++11 graphics engine (original) (raw)

This repository contains "bootstrap projects" for the Magnum C++11/C++14 graphics engine.

Join the chat at https://gitter.im/mosra/magnum Build Status Build Status Build Status UNLICENSE

Setting up a new project can be pretty gruesome and nobody likes repeating the same process every time. This repository provides "bootstrap" project structures for many use cases, helping you get up and running in no time.

USAGE

To use Magnum, you obviously need to have Magnum installed. The whole building and installation process (along with the following guide) is thoroughly explained in Magnum documentation, particularly in theGetting Started Guide.

Minimal dependencies

Note that each bootstrap project has additional dependency requirements, listed below. See Magnum building documentationfor more information.

Bootstrapping the project

Desired usage is to download selected branch from the list below as an archive (using the Download button in GitHub) or by using URL similar to one of the following (replace <branch> with desired branch name):

https://github.com/mosra/magnum-bootstrap/archive/<branch>.tar.gz
https://github.com/mosra/magnum-bootstrap/archive/<branch>.zip

After extracting the downloaded archive you can build and run the application with these four commands:

mkdir build && cd build
cmake ..
cmake --build .
./src/MyApplication # or ./src/Debug/MyApplication

For crosscompiling (in base-nacl and base-emscripten branches, see below) you will need to have the toolchains submodule. It is present in Git clone and can be updated with these commands:

git submodule init
git submodule update

However, because you should use downloaded archive anyway, you need to manually download snapshot of toolchains repository from https://github.com/mosra/toolchainsand put the contents in toolchains/ subdirectory.

Contents of the repository

This master branch contains just an README file and the actual bootstrap projects are in various other branches, each covering some particular use case.

Base application

The base branch contains barebones windowed application using Platform::Sdl2Application with only the essential files. You need Magnum built with WITH_SDL2APPLICATIONenabled.

Base application using GLFW

The base-glfwbranch is similar to base one, except that it uses Platform::GlfwApplicationinstead of Platform::Sdl2Application. You need Magnum built withWITH_GLFWAPPLICATION enabled.

Base application using gtkmm

The base-gtkmmbranch does not use any of the application wrappers provided in Platformnamespace, but uses gtkmm window and context creation directly and manually initializes Magnum on top of that using EGL on embedded devices, WGL on Windows, CGL on macOS and GLX on Unix/Linux. You need Magnum built withWITH_EGLCONTEXT, WITH_WGLCONTEXT, WITH_CGLCONTEXT or WITH_GLXCONTEXTenabled, depending on the platform of your choice.

Base application using Qt5 / Qt6

The base-qt5 /base-qt6 branches do not use any of the application wrappers provided in Platform namespace, but use a Qt5 / Qt6 window and context creation directly and manually initialize Magnum on top of that using EGL on embedded devices, WGL on Windows, CGL on macOS and GLX on Unix/Linux. You need Magnum built withWITH_EGLCONTEXT, WITH_WGLCONTEXT, WITH_CGLCONTEXT or WITH_GLXCONTEXTenabled, depending on the platform of your choice.

Base application using wxWidgets

The base-wxwidgetsbranch does not use any of the application wrappers provided in Platformnamespace, but uses wxWidgets window and context creation directly and manually initializes Magnum on top of that using EGL on embedded devices, WGL on Windows, CGL on macOS and GLX on Unix/Linux. You need Magnum built withWITH_EGLCONTEXT, WITH_WGLCONTEXT, WITH_CGLCONTEXT or WITH_GLXCONTEXTenabled, depending on the platform of your choice.

Windowless application

The windowlessbranch contains windowless application using Platform::WindowlessGlxApplicationon X11-based Unix, Platform::WindowlessCglApplication on macOS,Platform::WindowlessWglApplication on Windows, Platform::WindowlessWindowsEglApplicationon Windows GLES or ANGLE, Platform::WindowlessEglApplication on headless systems supporting EGL and Platform::WindowlessIosApplication on iOS. Useful for querying information about the renderer, offscreen rendering, image processing etc. You need Magnum built with WITH_WINDOWLESS*APPLICATIONenabled, depending on the platform of your choice.

Scene graph

The scenegraph2Dand scenegraph3Dbranches contain application prepared for using 2D/3D SceneGraph. You need Magnum built with WITH_SDL2APPLICATION and WITH_SCENEGRAPH enabled.

Base application with port to Emscripten

The base-emscriptenbranch contains application using Platform::Sdl2Application for desktop and and Platform::EmscriptenApplication for Emscripten build. For desktop build you need Magnum built with WITH_SDL2APPLICATION enabled and you can use the commands above to build it.

For Emscripten build you need to have Emscripten installed with Corrade and Magnum crosscompiled for Emscripten, don't forget to build Magnum withWITH_EMSCRIPTENAPPLICATION enabled. SeeCorrade'sand Magnum'sbuilding documentation for more information.

In the toolchains/ submodule there are two toolchain files. Thegeneric/Emscripten.cmake is for the classical (asm.js) build, thegeneric/Emscripten-wasm.cmake is for WebAssembly build. Don't forget to adaptEMSCRIPTEN_PREFIX variable in generic/Emscripten*.cmake to path where Emscripten is installed; you can also pass it explicitly on command-line using-DEMSCRIPTEN_PREFIX. Default is /usr/lib/emscripten.

Then create build directory and run cmake and build/install commands in it. Set CMAKE_PREFIX_PATH to where you have all the dependencies installed, setCMAKE_INSTALL_PREFIX to have the files installed in proper location (a webserver, e.g. /srv/http/emscripten).

mkdir build-emscripten && cd build-emscripten
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=path/to/toolchains/generic/Emscripten-wasm.cmake \
    -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
    -DCMAKE_INSTALL_PREFIX=/srv/http/emscripten
cmake --build .
cmake --build . --target install

You can then open MyApplication.html in your browser (through webserver, e.g.http://localhost/emscripten/MyApplication.html).

Windowless application with port to Emscripten

The windowless-emscriptenbranch contains a version of the windowless bootstrap project which in addition uses Platform::WindowlessEglApplication for Emscripten build. You need Magnum built with WITH_WINDOWLESS*APPLICATION enabled depending on your platform of choice and you can use the commands above to build the desktop version.

For Emscripten build you need to have Emscripten installed with Corrade and Magnum crosscompiled for Emscripten, don't forget to build Magnum withWITH_WINDOWLESSEGLAPPLICATION enabled. SeeCorrade'sand Magnum'sbuilding documentation for more information.

In the toolchains/ submodule there are two toolchain files. Thegeneric/Emscripten.cmake is for the classical (asm.js) build, thegeneric/Emscripten-wasm.cmake is for WebAssembly build. Don't forget to adaptEMSCRIPTEN_PREFIX variable in generic/Emscripten*.cmake to path where Emscripten is installed; you can also pass it explicitly on command-line using-DEMSCRIPTEN_PREFIX. Default is /usr/lib/emscripten.

Then create build directory and run cmake and build/install commands in it. Set CMAKE_PREFIX_PATH to where you have all the dependencies installed, setCMAKE_INSTALL_PREFIX to have the files installed in proper location (a webserver, e.g. /srv/http/emscripten).

mkdir build-emscripten && cd build-emscripten
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=path/to/toolchains/generic/Emscripten-wasm.cmake \
    -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
    -DCMAKE_INSTALL_PREFIX=/srv/http/emscripten
cmake --build .
cmake --build . --target install

You can then open MyApplication.html in your browser (through webserver, e.g.http://localhost/emscripten/MyApplication.html).

Base application with port to Android

The base-androidbranch contains application using Platform::Sdl2Application for desktop build and Platform::AndroidApplication for Android build. For desktop build you need Magnum built with WITH_SDL2APPLICATION enabled and you can use the commands above to build it.

For Android build you need to have Android NDK installed with Corrade and Magnum crosscompiled for Android, Magnum built with WITH_ANDROIDAPPLICATIONenabled. See Corrade'sand Magnum'sbuilding documentation for more information.

In order to build the application and install it on your device, use Gradle:

gradle build
gradle installDebug

Base application with port to iOS

The base-iosbranch contains application using Platform::Sdl2Application for both desktop and iOS build. You need Magnum built with WITH_SDL2APPLICATION enabled and you can use the commands above to build the desktop version.

For iOS you need macOS and XCode installed with Corrade and Magnum crosscompiled for iOS, don't forget to build Magnum with WITH_SDL2APPLICATIONenabled. See Corrade'sand Magnum'sbuilding documentation for more information.

Then create build directory and run cmake to generate the Xcode project. SetCMAKE_OSX_ROOT to SDK you want to target and enable all desired architectures in CMAKE_OSX_ARCHITECTURES. Set CMAKE_PREFIX_PATH to the directory where you have all the dependencies.

mkdir build-ios && cd build-ios
cmake .. \
    -DCMAKE_TOOLCHAIN_FILE=path/to/toolchains/generic/iOS.cmake \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
    -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
    -DCMAKE_PREFIX_PATH=~/ios-libs \
    -G Xcode

You can then open the generated project file in Xcode and build/deploy it from there.

Base application with port to Windows RT (Store/Phone)

The base-winrtbranch contains application using Platform::Sdl2Application for both desktop and Windows RT build. You need Magnum built with WITH_SDL2APPLICATION enabled and you can use the commands above to build the desktop version.

For Windows RT build you need to have at least Windows 8.1, Visual Studio 2013 and Windows 8.1 Store/Phone SDK installed with Corrade and Magnum crosscompiled for Windows RT, don't forget to build Magnum with WITH_SDL2APPLICATION enabled. See Corrade'sand Magnum'sbuilding documentation for more information.

You need to provide your own *.pfx certificate fileand pass it to CMake in a SIGNING_CERTIFICATE variable. The bootstrap application assumes that SDL2 and ANGLE is built as DLL and both Corrade and Magnum are built statically. Assuming the native Corrade installation is inC:/Sys and all WinRT dependencies are in C:/Sys-winrt, the build can be done similarly to the following:

mkdir build-winrt && cd build-winrt
cmake .. ^
    -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
    -DCMAKE_PREFIX_PATH="C:/Sys-winrt" ^
    -DCMAKE_SYSTEM_NAME=WindowsStore ^
    -DCMAKE_SYSTEM_VERSION=8.1 ^
    -DSIGNING_CERTIFICATE=<path-to-your-pfx-file> ^
    -G "Visual Studio 14 2015"
cmake --build .

Change WindowsStore to WindowsPhone if you want to build for Windows Phone instead. The build-winrt/src/AppPackages directory will then contain the final package along with a PowerShell script for easy local installation.

CONTACT & SUPPORT

If you want to contribute to Magnum, if you spotted a bug, need a feature or have an awesome idea, you can get a copy of the sources from GitHub and start right away! There is the already mentioned guide abouthow to download and build Magnumand also a guide about coding style and best practiceswhich you should follow to keep the library as consistent and maintainable as possible.

See also the Magnum Project Contact & Support pagefor further information.

LICENSE

While Magnum itself and its documentation are licensed under the MIT/Expat license, all boostrap projects are put into public domain (or UNLICENSE) to free you from any legal obstacles when reusing the code in your apps. See theCOPYING file for details.