diff --git a/src/Magnum/Platform/GlutApplication.h b/src/Magnum/Platform/GlutApplication.h index e2ae1bbe2..43198593d 100644 --- a/src/Magnum/Platform/GlutApplication.h +++ b/src/Magnum/Platform/GlutApplication.h @@ -54,19 +54,36 @@ warping. This application library is available only on desktop OpenGL (Linux, Windows, OS X). It depends on **GLUT** library and is built if `WITH_GLUTAPPLICATION` is -enabled in CMake. To use it, you need to request `%GlutApplication` component -in CMake, add `${MAGNUM_GLUTAPPLICATION_INCLUDE_DIRS}` to include path and link -to `${MAGNUM_GLUTAPPLICATION_LIBRARIES}`. If no other application is requested, +enabled in CMake. + +## Bootstrap application + +Fully contained base application using @ref GlutApplication along with +CMake setup is available in `base` branch of +[Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository, +download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base.tar.gz) +or [zip](https://github.com/mosra/magnum-bootstrap/archive/base.zip) file. +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 + +## General usage + +In CMake you need to request `%GlutApplication` component, add +`${MAGNUM_GLUTAPPLICATION_INCLUDE_DIRS}` to include path and link to +`${MAGNUM_GLUTAPPLICATION_LIBRARIES}`. If no other application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section GlutApplication-usage Usage - -You need to implement at least @ref drawEvent() to be able to draw on the -screen. The subclass can be then used directly in `main()` -- see convenience -macro @ref MAGNUM_GLUTAPPLICATION_MAIN(). See @ref platform for more -information. +In C++ code you need to implement at least @ref drawEvent() to be able to draw +on the screen. The subclass can be then used directly in `main()` -- see +convenience macro @ref MAGNUM_GLUTAPPLICATION_MAIN(). See @ref platform for +more information. @code class MyApplication: public Platform::GlutApplication { // implement required methods... diff --git a/src/Magnum/Platform/GlxApplication.h b/src/Magnum/Platform/GlxApplication.h index 696ed5963..b406817bc 100644 --- a/src/Magnum/Platform/GlxApplication.h +++ b/src/Magnum/Platform/GlxApplication.h @@ -42,18 +42,26 @@ Application using pure X11 and GLX. Supports keyboard and mouse handling. This application library is available on desktop OpenGL and @ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux. It depends on **X11** library and is built if `WITH_GLXAPPLICATION` is enabled in -CMake. To use it, you need to request `%GlxApplication` component in CMake, add +CMake. + +## Bootstrap application + +The usage is very similar to @ref Sdl2Application, for which fully contained +base application along with CMake setup is available, see its documentation for +more information. + +## General usage + +In CMake you need to request `%GlxApplication` component, add `${MAGNUM_GLXAPPLICATION_INCLUDE_DIRS}` to include path and link to `${MAGNUM_GLXAPPLICATION_LIBRARIES}`. If no other application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section GlxApplication-usage Usage - -You need to implement at least @ref drawEvent() to be able to draw on the -screen. The subclass can be then used directly in `main()` -- see convenience -macro @ref MAGNUM_GLXAPPLICATION_MAIN(). See @ref platform for more +In C++ code you need to implement at least @ref drawEvent() to be able to draw +on the screen. The subclass can be then used directly in `main()` -- see +convenience macro @ref MAGNUM_GLXAPPLICATION_MAIN(). See @ref platform for more information. @code class MyApplication: public Platform::GlxApplication { diff --git a/src/Magnum/Platform/NaClApplication.h b/src/Magnum/Platform/NaClApplication.h index 426187485..fb3552d69 100644 --- a/src/Magnum/Platform/NaClApplication.h +++ b/src/Magnum/Platform/NaClApplication.h @@ -56,19 +56,66 @@ namespace Magnum { namespace Platform { Application running in [Google Chrome Native Client](https://developers.google.com/native-client/). Supports keyboard and mouse handling. -This application library is available only in @ref CORRADE_TARGET_NACL "Native Client". -It is built if `WITH_NACLAPPLICATION` is enabled in CMake. To use it, you need -to request `%NaClApplication` component in CMake, add +This application library is available only in +@ref CORRADE_TARGET_NACL "Google Chrome Native Client", see respective sections +in @ref building-corrade-cross-nacl "Corrade's" and @ref building-cross-nacl "Magnum's" +building documentation. It is built if `WITH_NACLAPPLICATION` is enabled in +CMake. + +## Bootstrap application + +Fully contained base application using @ref GlutApplication 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 +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 +`toolchains/generic/NaCl-newlib-x86-64.cmake` to path where your SDK is +installed. Default is `/usr/nacl`. You may need to adapt also +`NACL_TOOLCHAIN_PATH` so CMake is able to find the compiler. + +Then create build directories for x86-32 and x86-64 and run `cmake` and +build/install commands in them. The toolchains need access to the platform +file, so be sure to properly set **absolute** path to `toolchains/modules/` +directory containing `Platform/NaCl.cmake`. Set `CMAKE_INSTALL_PREFIX` to +location of your webserver to have the files installed in proper location (e.g. +`/srv/http/nacl`). + + mkdir build-nacl-x86-32 && cd build-nacl-x86-32 + cmake .. \ + -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ + -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-32.cmake" \ + -DCMAKE_INSTALL_PREFIX=/srv/http/nacl + cmake --build . + cmake --build . --target install + + mkdir build-nacl-x86-64 && cd build-nacl-x86-64 + cmake .. \ + -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ + -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-64.cmake" \ + -DCMAKE_INSTALL_PREFIX=/srv/http/nacl + cmake --build . + cmake --build . --target install + +You can then open `MyApplication` through your webserver in Chrome (e.g. +`http://localhost/nacl/MyApplication.html`). + +## General usage + +In CMake you need to request `%NaClApplication` component, add `${MAGNUM_NACLAPPLICATION_INCLUDE_DIRS}` to include path and link to `${MAGNUM_NACLAPPLICATION_LIBRARIES}`. If no other application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section NaClApplication-usage Usage - -You need to implement at least @ref drawEvent() to be able to draw on the -screen. The subclass must be then registered to NaCl API using +In C++ code you need to implement at least @ref drawEvent() to be able to draw +on the screen. The subclass must be then registered to NaCl API using @ref MAGNUM_NACLAPPLICATION_MAIN() macro. See @ref platform for more information. @code @@ -82,13 +129,14 @@ If no other application header is included, this class is also aliased to `Platform::Application` and the macro is aliased to `MAGNUM_APPLICATION_MAIN()` to simplify porting. -@section NaClApplication-html HTML markup and NMF file +### HTML markup and NMF file -You need to provide HTML markup for your application. Template one is below, -you can modify it to your liking. The markup references two files, -`NaClApplication.js` and `WebApplication.css`, both are in `Platform/` -directory in the source tree and are also installed into `share/magnum/` inside -your NaCl toolchain. Change `<application>` to name of your executable. +You need to provide HTML markup for your application. Template one is below or +in the bootstrap application, you can modify it to your liking. The markup +references two files, `NaClApplication.js` and `WebApplication.css`, both are +in `Platform/` directory in the source tree and are also installed into +`share/magnum/` inside your NaCl toolchain. Change `<application>` to +name of your executable. @code @@ -131,9 +179,9 @@ If you target @ref CORRADE_TARGET_NACL_GLIBC "glibc", you need to specify also all additional dependencies. See [Native Client](https://developers.google.com/native-client/) documentation for more information. -@section NaClApplication-console Redirecting output to Chrome's JavaScript console +## Redirecting output to Chrome's JavaScript console -The application redirects @ref Corrade::Utility::Debug "Debug", +The application by default redirects @ref Corrade::Utility::Debug "Debug", @ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error" output to JavaScript console. See also @ref Corrade::Utility::NaClConsoleStreamBuffer for more information. @@ -339,7 +387,7 @@ class NaClApplication: public pp::Instance, public pp::Graphics3DClient, public @brief %Configuration Double-buffered RGBA canvas with depth and stencil buffers. -@see @ref NaClApplication(), @ref createContext() +@see @ref NaClApplication(), @ref createContext(), @ref tryCreateContext() */ class NaClApplication::Configuration { public: diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 66f2aec62..b2c712343 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -59,21 +59,69 @@ Application using [Simple DirectMedia Layer](http://www.libsdl.org/) toolkit. Supports keyboard and mouse handling. This application library is in theory available for all platforms for which -SDL2 is ported (thus also @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", but not -@ref CORRADE_TARGET_NACL "NaCl"). It depends on **SDL2** library (Emscripten -has it built in) and is built if `WITH_SDL2APPLICATION` is enabled in CMake. To -use it, you need to copy `FindSDL2.cmake` from `modules/` directory in %Magnum -source to `modules/` dir in your project (so CMake is able to find SDL2), -request `%Sdl2Application` component in CMake, add -`${MAGNUM_SDL2APPLICATION_INCLUDE_DIRS}` to include path and link to -`${MAGNUM_SDL2APPLICATION_LIBRARIES}`. If no other application is requested, -you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and -`${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See +SDL2 is ported (thus also @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", see +respective sections in @ref building-corrade-cross-emscripten "Corrade's" and +@ref building-cross-emscripten "Magnum's" building documentation). It depends +on **SDL2** library (Emscripten has it built in) and is built if +`WITH_SDL2APPLICATION` is enabled in CMake. + +## Bootstrap application + +Fully contained base application using @ref Sdl2Application along with +CMake setup is available in `base-sdl2` branch of +[Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository, +download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-sdl2.tar.gz) +or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-sdl2.zip) file. +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 + +## Bootstrap application for Emscripten + +Fully contained base application using @ref Sdl2Application for both desktop +and Emscripten build along with full HTML markup and CMake setup is available +in `base-emscripten` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) +repository, download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-emscripten.tar.gz) +or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-emscripten.zip) +file. After extracting the downloaded archive, you can do the desktop build in +the same way as above. For the Emscripten 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 `EMSCRIPTEN_PREFIX` +variable in `toolchains/generic/Emscripten.cmake` to path where Emscripten is +installed. Default is `/usr/emscripten`. + +Then create build directory and run `cmake` and build/install commands in it. +The toolchain needs access to its platform file, so be sure to properly set +**absolute** path to `toolchains/modules/` directory containing `Platform/Emscripten.cmake`. +Set `CMAKE_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_MODULE_PATH="/absolute/path/to/toolchains/modules" \ + -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten.cmake" + -DCMAKE_INSTALL_PREFIX=/srv/http/emscripten + cmake --build . + cmake --build . --target install + +You can then open `MyApplication.html` in Chrome or Firefox (through webserver, +e.g. `http://localhost/emscripten/MyApplication.html`). + +## General usage + +For CMake you need to copy `FindSDL2.cmake` from `modules/` directory in +%Magnum source to `modules/` dir in your project (so it is able to find SDL2), +request `%Sdl2Application` component, add `${MAGNUM_SDL2APPLICATION_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_SDL2APPLICATION_LIBRARIES}`. If no other +application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` +and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section Sdl2Application-usage Usage - -You need to implement at least @ref drawEvent() to be able to draw on the +In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in `main()` -- see convenience macro @ref MAGNUM_SDL2APPLICATION_MAIN(). See @ref platform for more information. @@ -88,14 +136,15 @@ If no other application header is included, this class is also aliased to `Platform::Application` and the macro is aliased to `MAGNUM_APPLICATION_MAIN()` to simplify porting. -@section Sdl2Application-html Usage with Emscripten +### Usage with Emscripten -If you are targetting @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", you need to -provide HTML markup for your application. Template one is below, you can modify -it to your liking. The markup references two files, `EmscriptenApplication.js` -and `WebApplication.css`, both are in `Platform/` directory in the source tree -and are also installed into `share/magnum/` inside your Emscripten toolchain. -Change `<application>` to name of your executable. +If you are targetting Emscripten, you need to provide HTML markup for your +application. Template one is below or in the bootstrap application, you can +modify it to your liking. The markup references two files, +`EmscriptenApplication.js` and `WebApplication.css`, both are in `Platform/` +directory in the source tree and are also installed into `share/magnum/` inside +your Emscripten toolchain. Change `<application>` to name of your +executable. @code @@ -123,9 +172,11 @@ file contains event listeners which print loading status on the page. The status displayed in the remaining two `<div>`s, if they are available. The CSS file contains rudimentary style to avoid eye bleeding. -The application redirects @ref Corrade::Utility::Debug "Debug", -@ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error" -output to JavaScript console. +## Redirecting output to JavaScript console + +The application redirects all output (thus also @ref Corrade::Utility::Debug "Debug", +@ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error") +to JavaScript console. */ class Sdl2Application { public: diff --git a/src/Magnum/Platform/WindowlessGlxApplication.h b/src/Magnum/Platform/WindowlessGlxApplication.h index 9cb56707f..11d90b556 100644 --- a/src/Magnum/Platform/WindowlessGlxApplication.h +++ b/src/Magnum/Platform/WindowlessGlxApplication.h @@ -53,16 +53,33 @@ Application for offscreen rendering using pure X11 and GLX. This application library is available on desktop OpenGL and @ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux. It depends on **X11** library and is built if `WITH_WINDOWLESSGLXAPPLICATION` is -enabled in CMake. To use it, you need to request `%WindowlessGlxApplication` -component in CMake, add `${MAGNUM_WINDOWLESSGLXAPPLICATION_INCLUDE_DIRS}` to -include path and link to `${MAGNUM_WINDOWLESSGLXAPPLICATION_LIBRARIES}`. If no -other windowless application is requested, you can also use generic +enabled in CMake. + +## Bootstrap application + +Fully contained windowless application using @ref WindowlessGlxApplication +along with CMake setup is available in `base-windowless` branch of +[Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) +repository, download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-windowless.tar.gz) +or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-windowless.zip) +file. 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 + +## General usage + +In CMake you need to request `%WindowlessGlxApplication` component, add +`${MAGNUM_WINDOWLESSGLXAPPLICATION_INCLUDE_DIRS}` to include path and link to +`${MAGNUM_WINDOWLESSGLXAPPLICATION_LIBRARIES}`. If no other windowless +application is requested, you can also use generic `${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}` and `${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section WindowlessGlxApplication-usage Usage - Place your code into @ref exec(). The subclass can be then used directly in `main()` -- see convenience macro @ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN(). See @ref platform for more information. diff --git a/src/Magnum/Platform/WindowlessNaClApplication.h b/src/Magnum/Platform/WindowlessNaClApplication.h index a214a1fe1..c9f181d4b 100644 --- a/src/Magnum/Platform/WindowlessNaClApplication.h +++ b/src/Magnum/Platform/WindowlessNaClApplication.h @@ -52,9 +52,20 @@ namespace Magnum { namespace Platform { Application for offscreen rendering running in [Google Chrome Native Client](https://developers.google.com/native-client/). -This application library is available only in @ref CORRADE_TARGET_NACL "Native Client". -It is built if `WITH_WINDOWLESSNACLAPPLICATION` is enabled in CMake. To use it, -you need to request `%WindowlessNaClApplication` component in CMake, add +This application library is available only in @ref CORRADE_TARGET_NACL "Native Client", +see respective sections in @ref building-corrade-cross-nacl "Corrade's" and +@ref building-cross-nacl "Magnum's" building documentation. It is built if +`WITH_WINDOWLESSNACLAPPLICATION` is enabled in CMake. + +## Bootstrap application + +The usage is very similar to @ref NaClApplication, for which fully contained +base application along with CMake setup is available, see its documentation for +more information. + +## General Usage + +In CMake you need to request `%WindowlessNaClApplication` component, add `${MAGNUM_WINDOWLESSNACLAPPLICATION_INCLUDE_DIRS}` to include path and link to `${MAGNUM_WINDOWLESSNACLAPPLICATION_LIBRARIES}`. If no other windowless application is requested, you can also use generic @@ -62,8 +73,6 @@ application is requested, you can also use generic `${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section WindowlessNaClApplication-usage Usage - Place your code into @ref exec(). The subclass must be then registered to NaCl API using @ref MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() macro. See @ref platform for more information. @@ -78,7 +87,7 @@ If no other application header is included, this class is also aliased to `Platform::WindowlessApplication` and the macro is aliased to `MAGNUM_WINDOWLESSAPPLICATION_MAIN()` to simplify porting. -@section WindowlessNaClApplication-html HTML markup and NMF file +### HTML markup and NMF file You need to provide HTML markup containing `<embed>` pointing to `*.nmf` file describing the application. See @ref NaClApplication for more information. @@ -86,9 +95,9 @@ You may want to hide the `<embed>` (for example using CSS `visibility: hidden;`), as it probably won't display anything to default framebuffer. -@section WindowlessNaClApplication-console Redirecting output to Chrome's JavaScript console +## Redirecting output to Chrome's JavaScript console -The application redirects @ref Corrade::Utility::Debug "Debug", +The application by default redirects @ref Corrade::Utility::Debug "Debug", @ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error" output to JavaScript console. See also @ref Corrade::Utility::NaClConsoleStreamBuffer for more information. diff --git a/src/Magnum/Platform/XEglApplication.h b/src/Magnum/Platform/XEglApplication.h index ff96cfd65..759487d49 100644 --- a/src/Magnum/Platform/XEglApplication.h +++ b/src/Magnum/Platform/XEglApplication.h @@ -41,21 +41,28 @@ Application using pure X11 and EGL. Supports keyboard and mouse handling. This application library is available on both desktop OpenGL and @ref MAGNUM_TARGET_GLES "OpenGL ES" on Linux. It depends on **X11** and **EGL** -libraries and is built if `WITH_XEGLAPPLICATION` is enabled in CMake. To use -it, you need to copy `FindEGL.cmake` from `modules/` directory in %Magnum -source to `modules/` dir in your project (so CMake is able to find EGL), -request `%XEglApplication` component in CMake, add `${MAGNUM_XEGLAPPLICATION_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_XEGLAPPLICATION_LIBRARIES}`. If no other +libraries and is built if `WITH_XEGLAPPLICATION` is enabled in CMake. + +## Bootstrap application + +The usage is very similar to @ref Sdl2Application, for which fully contained +base application along with CMake setup is available, see its documentation for +more information. + +## General usage + +For CMake you need to copy `FindEGL.cmake` from `modules/` directory in %Magnum +source to `modules/` dir in your project (so it is able to find EGL), request +`%XEglApplication` component, add `${MAGNUM_XEGLAPPLICATION_INCLUDE_DIRS}` to +include path and link to `${MAGNUM_XEGLAPPLICATION_LIBRARIES}`. If no other application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See @ref building and @ref cmake for more information. -@section XEglApplication-usage Usage - -You need to implement at least @ref drawEvent() to be able to draw on the -screen. The subclass can be then used directly in `main()` -- see convenience -macro @ref MAGNUM_XEGLAPPLICATION_MAIN(). See @ref platform for more -information. +In C++ code you need to implement at least @ref drawEvent() to be able to draw +on the screen. The subclass can be then used directly in `main()` -- see +convenience macro @ref MAGNUM_XEGLAPPLICATION_MAIN(). See @ref platform for +more information. @code class MyApplication: public Platform::XEglApplication { // implement required methods...