diff --git a/README.md b/README.md index 68cfeae81..5a22c7889 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,8 @@ Graphics APIs: Platforms: * **Linux** and embedded Linux (natively using GLX/EGL and Xlib or through - GLUT or SDL2 toolkit) -* **Windows** (through GLUT or SDL2 toolkit) + SDL2 or GLUT toolkit) +* **Windows** (through SDL2 or GLUT toolkit) * **OS X** (through SDL2 toolkit, thanks to [Miguel Martin](https://github.com/miguelishawt)) * **Android** 2.3 (API Level 9) and higher * **Google Chrome** (through [Native Client](https://developers.google.com/native-client/), @@ -97,13 +97,13 @@ Note that full feature set is available only on GCC 4.8.1 and Clang 3.1. Compilation, installation ------------------------- -The library (for example with support for GLUT applications) can be built and +The library (for example with support for SDL2 applications) can be built and installed using these four commands: mkdir -p build && cd build cmake .. \ -DCMAKE_INSTALL_PREFIX=/usr \ - -DWITH_GLUTAPPLICATION=ON + -DWITH_SDL2APPLICATION=ON make make install diff --git a/doc/building.dox b/doc/building.dox index c513a58da..53ac127ee 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -66,13 +66,13 @@ assuming you have at least basic knowledge of CMake. @subsection building-linux Via command-line (on Linux/Unix) -On Unix-based OSs, the library (for example with support for GLUT applications) +On Unix-based OSs, the library (for example with support for SDL2 applications) can be built and installed using these four commands: mkdir build && cd build cmake .. \ -DCMAKE_INSTALL_PREFIX=/usr \ - -DWITH_GLUTAPPLICATION=ON + -DWITH_SDL2APPLICATION=ON make make install diff --git a/doc/cmake.dox b/doc/cmake.dox index d5b7aa086..c8cb7b1cb 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -120,7 +120,7 @@ in build and use it with CMake. Example usage with specifying additional components is: - find_package(Magnum REQUIRED MeshTools Primitives GlutApplication) + find_package(Magnum REQUIRED MeshTools Primitives Sdl2Application) For each component is then defined: diff --git a/doc/getting-started-blue.png b/doc/getting-started-blue.png index 50b64d15c..10e381ddb 100644 Binary files a/doc/getting-started-blue.png and b/doc/getting-started-blue.png differ diff --git a/doc/getting-started.dox b/doc/getting-started.dox index adcdd39a7..35b90f9ad 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -33,10 +33,11 @@ namespace Magnum { Get latest version from GitHub and install it. Read full guide on @ref building "how to download, build and install Magnum" on platform of your -choice. For our first project we will use GLUT toolkit, don't forget to enable -it for building using `WITH_GLUTAPPLICATION` CMake parameter. On newer systems, -Mac OS X and Windows you might want to use SDL2 toolkit instead, it is enabled -using `WITH_SDL2APPLICATION` CMake parameter. +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. @section getting-started-bootstrap Download bootstrap project @@ -54,8 +55,8 @@ 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 SDL2 instead of GLUT, download the `base-sdl2` branch -[archive](https://github.com/mosra/magnum-bootstrap/archive/base-sdl2.zip). +If you want to use GLUT instead of SDL2, download the `base-glut` branch +[archive](https://github.com/mosra/magnum-bootstrap/archive/base-glut.zip). 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. @@ -67,6 +68,7 @@ CMake build system, see @ref cmake for more information. modules/FindCorrade.cmake modules/FindMagnum.cmake + modules/FindSDL2.cmake src/MyApplication.cpp src/CMakeLists.txt CMakeLists.txt @@ -86,8 +88,8 @@ add_subdirectory(src) @endcode Directory `modules/` contains CMake modules for finding the needed -dependencies. Unlike modules for finding e.g. GLUT and OpenGL, which are part -of standard CMake installation, these aren't part of it and thus must be +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. @@ -95,7 +97,7 @@ Directory `src/` contains the actual project. To keep things simple, the project consists of just one source file with the most minimal code possible: @code #include -#include +#include using namespace Magnum; @@ -127,7 +129,7 @@ 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: @code -find_package(Magnum REQUIRED GlutApplication) +find_package(Magnum REQUIRED Sdl2Application) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CORRADE_CXX_FLAGS}") include_directories(${MAGNUM_INCLUDE_DIRS} ${MAGNUM_APPLICATION_INCLUDE_DIRS}) @@ -169,8 +171,8 @@ where to create build directory, allows you to specify initial CMake parameters everything is ready to be built. If CMake isn't able to find the dependencies on Windows, you might want to look -at @ref building-windows. If CMake complains about `GlutApplication` missing, -you forgot to enable `WITH_GLUTAPPLICATION` when building %Magnum, +at @ref building-windows. If CMake complains about `Sdl2Application` missing, +you forgot to enable `WITH_SDL2APPLICATION` when building %Magnum, @ref getting-started-download "go back and fix it". @image html getting-started.png diff --git a/doc/getting-started.png b/doc/getting-started.png index 7f4cf8c3a..2df2b37b3 100644 Binary files a/doc/getting-started.png and b/doc/getting-started.png differ diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 920ad37cb..64774d72e 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -75,8 +75,8 @@ Graphics APIs: Platforms: - **Linux** and embedded Linux (natively using GLX/EGL and Xlib or through - GLUT or SDL2 toolkit) -- **Windows** (through GLUT or SDL2 toolkit) + SDL2 or GLUT toolkit) +- **Windows** (through SDL2 or GLUT toolkit) - **OS X** (through SDL2 toolkit, thanks to [Miguel Martin](https://github.com/miguelishawt)) - **Android** 2.3 (API Level 9) and higher - **Google Chrome** (through [Native Client](https://developers.google.com/native-client/), diff --git a/doc/platform.dox b/doc/platform.dox index 44c6700a5..633f38057 100644 --- a/doc/platform.dox +++ b/doc/platform.dox @@ -45,12 +45,12 @@ to subclass the chosen `*Application` class and implement required methods. @section platform-windowed Windowed applications Windowed applications provide a window and keyboard and mouse handling. The -most basic toolkit (and toolkit packaged for most systems) is GLUT, which is -implemented in @ref Platform::GlutApplication. As said above, the usage is -similar for all toolkits, you must provide one-argument constructor and -implement at least @ref GlutApplication::drawEvent() "drawEvent()" function. -The class can be then used directly in `main()`, but for convenience and -portability it's better to use @ref MAGNUM_GLUTAPPLICATION_MAIN() macro. +de-facto standard and most widely used toolkit is SDL2, which is implemented in +@ref Platform::Sdl2Application. As said above, the usage is similar for all +toolkits, you must provide one-argument constructor and implement at least +@ref Sdl2Application::drawEvent() "drawEvent()" function. The class can be then +used directly in `main()`, but for convenience and portability it's better to +use @ref MAGNUM_SDL2APPLICATION_MAIN() macro. To simplify the porting, the library provides `Platform::Application` typedef and `MAGNUM_APPLICATION_MAIN()` macro (but only if only one application header @@ -69,7 +69,7 @@ blue color is shown in the following code listing. #include #include #include -#include +#include using namespace Magnum; @@ -103,7 +103,7 @@ MAGNUM_APPLICATION_MAIN(MyApplication) By default the application doesn't respond to window size changes in any way, as the window has fixed size in most cases. To respond to size change for example by resizing the default framebuffer, you need to reimplement -@ref GlutApplication::viewportEvent() "viewportEvent()" function and pass the +@ref Sdl2Application::viewportEvent() "viewportEvent()" function and pass the new size to the framebuffer: @code class MyApplication: public Platform::Application { @@ -177,19 +177,21 @@ MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication) @section platform-compilation Compilation with CMake Barebone compilation consists just of finding %Magnum library with required -`*Application` component, adding %Magnum's `${MAGNUM_INCLUDE_DIRS}` and application-specific `${MAGNUM_GLUTAPPLICATION_INCLUDE_DIRS}` to include path, compilation of the -executable and linking `${MAGNUM_LIBRARIES}` and `${MAGNUM_GLUTAPPLICATION_LIBRARIES}` -to it. +`*Application` component, adding %Magnum's `${MAGNUM_INCLUDE_DIRS}` and +application-specific `${MAGNUM_SDL2APPLICATION_INCLUDE_DIRS}` to include path, +compilation of the executable and linking `${MAGNUM_LIBRARIES}` and +`${MAGNUM_SDL2APPLICATION_LIBRARIES}` to it. Again, to simplify porting, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` -and `${MAGNUM_WAPPLICATION_LIBRARIES}` aliases (or `${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}`, `${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` for windowless applications), but +and `${MAGNUM_WAPPLICATION_LIBRARIES}` aliases (or `${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}`, +`${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` for windowless applications), but only if only one application (windowless application) component is requested to avoid ambiguity. Changing the build script to use different toolkit is then matter of replacing only the requested `*Application` component (and one #`include` line in the actual code, as said above). @code -find_package(Magnum REQUIRED GlutApplication) +find_package(Magnum REQUIRED Sdl2Application) include_directories(${MAGNUM_INCLUDE_DIRS} ${MAGNUM_APPLICATION_INCLUDE_DIRS}) @@ -203,7 +205,7 @@ target_link_libraries(myapplication By default the application is created with some reasonable defaults (e.g. window size 800x600 pixels). If you want something else, you can pass -@ref GlutApplication::Configuration "Configuration" instance to application +@ref Sdl2Application::Configuration "Configuration" instance to application constructor. Using method chaining it can be done conveniently like this: @code MyApplication::MyApplication(int& argc, char** argv): @@ -217,8 +219,8 @@ MyApplication::MyApplication(int& argc, char** argv): However, sometimes you would need to configure the application based on some configuration file or system introspection. In that case you can pass `nullptr` -instead of @ref GlutApplication::Configuration "Configuration" instance and -then specify it later with @ref GlutApplication::createContext() "createContext()": +instead of @ref Sdl2Application::Configuration "Configuration" instance and +then specify it later with @ref Sdl2Application::createContext() "createContext()": @code MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) { // ... @@ -231,9 +233,9 @@ MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc } @endcode -If the context creation in constructor or @ref GlutApplication::createContext() "createContext()" +If the context creation in constructor or @ref Sdl2Application::createContext() "createContext()" fails, the application exits. However, it is also possible to negotiate the -context using @ref GlutApplication::tryCreateContext() "tryCreateContext()". +context using @ref Sdl2Application::tryCreateContext() "tryCreateContext()". The only difference is that this function returns `false` instead of exiting. You can for example try enabling MSAA and if the context creation fails, fall back to no-AA rendering: diff --git a/package/archlinux/magnum-git/PKGBUILD b/package/archlinux/magnum-git/PKGBUILD index 660b77f98..26335fba5 100644 --- a/package/archlinux/magnum-git/PKGBUILD +++ b/package/archlinux/magnum-git/PKGBUILD @@ -6,7 +6,7 @@ pkgdesc="C++11 and OpenGL 2D/3D graphics engine (Git version)" arch=('i686' 'x86_64') url="http://mosra.cz/blog/magnum.php" license=('MIT') -depends=('corrade-git' 'openal' 'freeglut') +depends=('corrade-git' 'openal' 'sdl2') makedepends=('cmake' 'git') provides=('magnum') conflicts=('magnum') @@ -40,7 +40,7 @@ build() { -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr \ -DWITH_AUDIO=ON \ - -DWITH_GLUTAPPLICATION=ON \ + -DWITH_SDL2APPLICATION=ON \ -DWITH_GLXAPPLICATION=ON \ -DWITH_WINDOWLESSGLXAPPLICATION=ON \ -DWITH_MAGNUMFONT=ON \ diff --git a/src/Magnum/DebugTools/Profiler.h b/src/Magnum/DebugTools/Profiler.h index 85b2070df..9c6a4cfff 100644 --- a/src/Magnum/DebugTools/Profiler.h +++ b/src/Magnum/DebugTools/Profiler.h @@ -43,7 +43,7 @@ namespace Magnum { namespace DebugTools { @brief %Profiler Measures time passed during specified sections of each frame. It's meant to be -used in rendering and event loops (e.g. Platform::GlutApplication::drawEvent()), +used in rendering and event loops (e.g. Platform::Sdl2Application::drawEvent()), but it's possible to use it standalone elsewhere. Example usage: @code DebugTools::Profiler p; diff --git a/src/Magnum/DefaultFramebuffer.h b/src/Magnum/DefaultFramebuffer.h index 347d3e3dd..b28353fea 100644 --- a/src/Magnum/DefaultFramebuffer.h +++ b/src/Magnum/DefaultFramebuffer.h @@ -45,7 +45,7 @@ surface. When you are using only the default framebuffer, the usage is simple. You must ensure that it is properly resized when application surface is resized, -i.e. you must pass the new size in your @ref Platform::GlutApplication::viewportEvent() "viewportEvent()" +i.e. you must pass the new size in your @ref Platform::Sdl2Application::viewportEvent() "viewportEvent()" implementation, for example: @code void viewportEvent(const Vector2i& size) { @@ -56,7 +56,7 @@ void viewportEvent(const Vector2i& size) { @endcode Next thing you probably want is to clear all used buffers before performing -any drawing in your @ref Platform::GlutApplication::drawEvent() "drawEvent()" +any drawing in your @ref Platform::Sdl2Application::drawEvent() "drawEvent()" implementation, for example: @code void drawEvent() { diff --git a/src/Magnum/Platform/AbstractXApplication.h b/src/Magnum/Platform/AbstractXApplication.h index 00eee6066..2d95ec5cc 100644 --- a/src/Magnum/Platform/AbstractXApplication.h +++ b/src/Magnum/Platform/AbstractXApplication.h @@ -220,19 +220,19 @@ class AbstractXApplication::Configuration { return *this; } - /** @copydoc GlutApplication::Configuration::size() */ + /** @copydoc Sdl2Application::Configuration::size() */ Vector2i size() const { return _size; } - /** @copydoc GlutApplication::Configuration::setSize() */ + /** @copydoc Sdl2Application::Configuration::setSize() */ Configuration& setSize(const Vector2i& size) { _size = size; return *this; } - /** @copydoc GlutApplication::Configuration::version() */ + /** @copydoc Sdl2Application::Configuration::version() */ Version version() const { return _version; } - /** @copydoc GlutApplication::Configuration::setVersion() */ + /** @copydoc Sdl2Application::Configuration::setVersion() */ Configuration& setVersion(Version version) { _version = version; return *this; diff --git a/src/Magnum/Platform/AndroidApplication.h b/src/Magnum/Platform/AndroidApplication.h index 38d482c4b..4b9a2431f 100644 --- a/src/Magnum/Platform/AndroidApplication.h +++ b/src/Magnum/Platform/AndroidApplication.h @@ -59,14 +59,14 @@ CMake. ## Bootstrap application -Fully contained base application using @ref GlutApplication for desktop build +Fully contained base application using @ref Sdl2Application for desktop build and @ref AndroidApplication for Android build along with full Android packaging stuff and CMake setup is available in `base-android` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository, download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-android.tar.gz) or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-android.zip) file. After extracting the downloaded archive, you can do the desktop build in the -same way as with @ref GlutApplication. For the Android build you also +same way as with @ref Sdl2Application. For the Android build you also need to put the contents of toolchains repository from https://github.com/mosra/toolchains in `toolchains/` subdirectory. Don't forget to adapt `ANDROID_NDK_ROOT` in `toolchains/generic/Android-*.cmake` to path where NDK is installed. Default is diff --git a/src/Magnum/Platform/GlxApplication.h b/src/Magnum/Platform/GlxApplication.h index 8aead290a..f714c1a0c 100644 --- a/src/Magnum/Platform/GlxApplication.h +++ b/src/Magnum/Platform/GlxApplication.h @@ -76,10 +76,10 @@ to simplify porting. */ class GlxApplication: public AbstractXApplication { public: - /** @copydoc Sdl2Application::GlutApplication(const Arguments&, const Configuration&) */ + /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ explicit GlxApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); - /** @copydoc Sdl2Application::GlutApplication(const Arguments&, std::nullptr_t) */ + /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ explicit GlxApplication(const Arguments& arguments, std::nullptr_t); protected: diff --git a/src/Magnum/Platform/NaClApplication.h b/src/Magnum/Platform/NaClApplication.h index 63fe8c491..641067e7c 100644 --- a/src/Magnum/Platform/NaClApplication.h +++ b/src/Magnum/Platform/NaClApplication.h @@ -68,14 +68,14 @@ CMake. ## Bootstrap application -Fully contained base application using @ref GlutApplication for desktop build +Fully contained base application using @ref Sdl2Application for desktop build and @ref NaClApplication for Native Client build along with full HTML markup and CMake setup is available in `base-nacl` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository, download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-nacl.tar.gz) or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-nacl.zip) file. After extracting the downloaded archive, you can do the desktop build in the -same way as with @ref GlutApplication. For the Native Client build you also +same way as with @ref Sdl2Application. For the Native Client build you also need to put the contents of toolchains repository from https://github.com/mosra/toolchains in `toolchains/` subdirectory. Don't forget to adapt `NACL_PREFIX` variable in `toolchains/generic/NaCl-newlib-x86-32.cmake` and diff --git a/src/Magnum/Platform/XEglApplication.h b/src/Magnum/Platform/XEglApplication.h index 067cd8476..e930b313b 100644 --- a/src/Magnum/Platform/XEglApplication.h +++ b/src/Magnum/Platform/XEglApplication.h @@ -76,10 +76,10 @@ to simplify porting. */ class XEglApplication: public AbstractXApplication { public: - /** @copydoc Sdl2Application::GlutApplication(const Arguments&, const Configuration&) */ + /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ explicit XEglApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); - /** @copydoc Sdl2Application::GlutApplication(const Arguments&, std::nullptr_t) */ + /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ explicit XEglApplication(const Arguments& arguments, std::nullptr_t); protected: diff --git a/src/Magnum/Renderer.h b/src/Magnum/Renderer.h index ff2226294..b26bd93f2 100644 --- a/src/Magnum/Renderer.h +++ b/src/Magnum/Renderer.h @@ -145,7 +145,7 @@ class MAGNUM_EXPORT Renderer { /** * Multisampling. Enabled by default. Note that the actual presence * of this feature in default framebuffer depends on context - * configuration, see for example Platform::GlutApplication::Configuration::setSampleCount(). + * configuration, see for example @ref Platform::Sdl2Application::Configuration::setSampleCount(). * @requires_gl Always enabled in OpenGL ES. */ Multisampling = GL_MULTISAMPLE,