mirror of https://github.com/mosra/magnum.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
254 lines
10 KiB
254 lines
10 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 |
|
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 |
|
|
|
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. |
|
|
|
@section getting-started-bootstrap Download the bootstrap project |
|
|
|
The [bootstrap repository](https://github.com/mosra/magnum-bootstrap) is |
|
located on GitHub. The `master` branch contains just a 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](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 new project from scratch with clean Git history. |
|
|
|
@section getting-started-download Download, build and install Corrade and Magnum |
|
|
|
Magnum libraries support both separate compilation/installation and CMake |
|
subprojects. If you are lucky, you may already have Magnum packages ready for |
|
your platform and you can skip the rest of this section: |
|
|
|
- @ref building-packages-arch |
|
- @ref building-packages-deb |
|
- @ref building-packages-gentoo |
|
- @ref building-packages-brew |
|
|
|
If you don't, don't worry, let's use the subproject approach instead. Adding |
|
the dependencies means just cloning them into your project tree: |
|
|
|
@code{.sh} |
|
cd /path/to/the/extracted/bootstrap/project |
|
git clone git://github.com/mosra/corrade.git |
|
git clone git://github.com/mosra/magnum.git |
|
@endcode |
|
|
|
Then open the `CMakeLists.txt` file in the root of bootstrap project and add |
|
these two new subdirectories using @cmake add_subdirectory() @ce so the file |
|
looks like this: |
|
|
|
@code{.cmake} |
|
cmake_minimum_required(VERSION 2.8.12) |
|
project(MyApplication) |
|
|
|
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/modules/") |
|
|
|
add_subdirectory(corrade) |
|
add_subdirectory(magnum) |
|
add_subdirectory(src) |
|
@endcode |
|
|
|
@note |
|
In the long run it's better to install Corrade and Magnum separately |
|
instead of cloning them into your project tree, as that vastly improves |
|
your iteration times. Follow @ref building "the full installation guide" if |
|
you want to go that route; don't forget to enable `WITH_SDL2APPLICATION` |
|
when building Magnum so the bootstrap project can use it later. There are |
|
also ready-to-use packages for various OSes and distributions. |
|
@note |
|
If you have that, you don't need to clone the subprojects and modify the |
|
`CMakeLists.txt` file like above, you might only need to set |
|
`CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to a non-standard |
|
location. |
|
|
|
@section getting-started-review Review project structure |
|
|
|
The base project consists of just six files in two subfolders. Magnum uses the |
|
CMake build system, you can read more about it in @ref cmake. |
|
|
|
modules/FindCorrade.cmake |
|
modules/FindMagnum.cmake |
|
modules/FindSDL2.cmake |
|
src/MyApplication.cpp |
|
src/CMakeLists.txt |
|
CMakeLists.txt |
|
|
|
In root there is the project-wide `CMakeLists.txt`, which you have seen above. |
|
It just sets up project name, specifies module directory and delegates |
|
everything important to `CMakeLists.txt` in the `src/` subdirectory. |
|
|
|
The `modules/` directory 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. |
|
|
|
@note These modules are just the bare minimum you need for starting. If you |
|
plan to use additional functionality that isn't part of the core library or |
|
you are targeting specific platforms, you may need to include additional |
|
modules. See @ref cmake, @ref cmake-plugins, @ref cmake-integration and |
|
@ref cmake-extras for more information. |
|
|
|
The `src/` directory contains the actual project. To keep things simple, the |
|
project consists of just a single `MyApplication.cpp` file with the most |
|
minimal code possible: |
|
|
|
@snippet getting-started.cpp 0 |
|
|
|
The application essentially does nothing, just clears the 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: |
|
|
|
@code{.cmake} |
|
find_package(Magnum REQUIRED Sdl2Application) |
|
|
|
set_directory_properties(PROPERTIES CORRADE_USE_PEDANTIC_FLAGS ON) |
|
|
|
add_executable(MyApplication MyApplication.cpp) |
|
target_link_libraries(MyApplication |
|
Magnum::Magnum |
|
Magnum::Application) |
|
@endcode |
|
|
|
In the following tutorials the code will be explained more thoroughly. |
|
|
|
@section getting-started-build Build it and run |
|
|
|
@subsection getting-started-linux Linux, macOS and other Unix-based OSes |
|
|
|
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: |
|
|
|
@code{.sh} |
|
mkdir -p build && cd build |
|
cmake .. -DWITH_SDL2APPLICATION=ON |
|
cmake --build . |
|
./src/MyApplication |
|
@endcode |
|
|
|
@note If you installed Corrade and Magnum separately (instead of putting them |
|
in the project as subprojects), the `-DWITH_SDL2APPLICATION=ON` is not |
|
needed as that was already done when compiling & installing Magnum before. |
|
|
|
@subsection getting-started-windows Windows |
|
|
|
On Windows you can use either MSVC 2015+ or MinGW-w64. Prebuilt SDL2 binaries |
|
can be downloaded at https://libsdl.org/download-2.0.php, dependeding on where |
|
you extract them you may need to specify `CMAKE_PREFIX_PATH` so CMake is able |
|
to find them. For running the executable properly, Windows also need to have |
|
all dependency DLLs copied along it. That can be done by setting |
|
`CMAKE_RUNTIME_OUTPUT_DIRECTORY`. It's then up to you whether you will use a |
|
command line, Visual Studio or for example QtCreator. With Visual Studio the |
|
most straightforward way to generate the project file is via the command line: |
|
|
|
@code{.bat} |
|
mkdir build && cd build |
|
cmake .. ^ |
|
-DWITH_SDL2APPLICATION=ON ^ |
|
-DCMAKE_PREFIX_PATH="C:/Users/you/where/you/extracted/SDL2-2.0.5" ^ |
|
-DCMAKE_RUNTIME_OUTPUT_DIRECTORY="bin" |
|
@endcode |
|
|
|
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 |
|
(`-DWITH_SDL2APPLICATION=ON` and others) and then you can just press *Configure* |
|
and everything is ready to be built. |
|
|
|
@note If you installed Corrade and Magnum separately, the install directory |
|
containing the DLLs needs to be in @cb{.bat} %PATH% @ce in order to |
|
properly run the executable. You can also enable `BUILD_STATIC` to compile |
|
everything as static, see @ref building "the full installation guide" for |
|
details. |
|
|
|
@section getting-started-running Running the application |
|
|
|
If everything went well and the application starts, you will see a blank window |
|
like this: |
|
|
|
@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 the clear color to |
|
something else and also print basic information about the GPU the engine is |
|
running on. First include the needed headers: |
|
|
|
@snippet getting-started-blue.cpp 0 |
|
|
|
And in the constructor (which is currently empty) change the clear color and |
|
print something to debug output: |
|
|
|
@snippet getting-started-blue.cpp 1 |
|
|
|
After rebuilding and starting the application, the clear color changes to |
|
blueish one and something like this would be printed to the console: |
|
|
|
@code{.shell-session} |
|
$ ./MyApplication |
|
[...] |
|
Hello! This application is running on OpenGL 4.5 using GeForce GT 740M |
|
@endcode |
|
|
|
@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 a @ref examples-triangle "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 --- @copybrief building |
|
- @subpage building-plugins --- @copybrief building-plugins |
|
- @subpage building-integration --- @copybrief building-integration |
|
- @subpage building-extras --- @copybrief building-extras |
|
- @subpage building-examples --- @copybrief building-examples |
|
- @subpage cmake --- @copybrief cmake |
|
- @subpage cmake-plugins --- @copybrief cmake-plugins |
|
- @subpage cmake-integration --- @copybrief cmake-integration |
|
- @subpage cmake-extras --- @copybrief cmake-extras |
|
|
|
*/ |
|
}
|
|
|