From 3295e7e920dd228c417104c322250de7419306d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 29 Oct 2013 16:26:19 +0100 Subject: [PATCH] Platform: thoroughly documented building and usage with CMake. --- src/Platform/AbstractXApplication.h | 4 +++- src/Platform/GlutApplication.h | 26 +++++++++++++++-------- src/Platform/GlxApplication.h | 24 +++++++++++++++------ src/Platform/NaClApplication.h | 20 ++++++++++++------ src/Platform/Sdl2Application.h | 27 +++++++++++++++++------- src/Platform/WindowlessGlxApplication.h | 23 ++++++++++++++------ src/Platform/WindowlessNaClApplication.h | 22 +++++++++++++------ src/Platform/XEglApplication.h | 25 ++++++++++++++++------ 8 files changed, 121 insertions(+), 50 deletions(-) diff --git a/src/Platform/AbstractXApplication.h b/src/Platform/AbstractXApplication.h index 807c0fd77..795491f97 100644 --- a/src/Platform/AbstractXApplication.h +++ b/src/Platform/AbstractXApplication.h @@ -55,7 +55,9 @@ namespace Implementation { @brief Base for X11-based applications Supports keyboard and mouse handling. See @ref platform for brief introduction. -@note Not meant to be used directly, see subclasses. + +@note Not meant to be used directly, see @ref GlxApplication and + @ref XEglApplication subclasses. */ class AbstractXApplication { public: diff --git a/src/Platform/GlutApplication.h b/src/Platform/GlutApplication.h index a12e4671c..41b5541f5 100644 --- a/src/Platform/GlutApplication.h +++ b/src/Platform/GlutApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::GlutApplication + * @brief Class @ref Magnum::Platform::GlutApplication */ #include @@ -45,23 +45,31 @@ namespace Platform { /** @nosubgrouping @brief GLUT application -Supports keyboard handling for limited subset of keys, mouse handling with -support for changing cursor and mouse tracking and warping. See @ref platform -for brief introduction. +Application using GLUT toolkit. Supports keyboard handling for limited subset +of keys, mouse handling with support for changing cursor and mouse tracking and +warping. See @ref platform for brief introduction. + +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, +you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and +`${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. @section GlutApplication-usage Usage -You need to implement at least drawEvent() and viewportEvent() to be able to -draw on the screen. The subclass can be then used directly in `main()` -- see -convenience macro MAGNUM_GLUTAPPLICATION_MAIN(). +You need to implement at least @ref drawEvent() and @ref viewportEvent() to be +able to draw on the screen. The subclass can be then used directly in `main()` +-- see convenience macro @ref MAGNUM_GLUTAPPLICATION_MAIN(). @code -class MyApplication: public Magnum::Platform::GlutApplication { +class MyApplication: public Platform::GlutApplication { // implement required methods... }; MAGNUM_GLUTAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. */ diff --git a/src/Platform/GlxApplication.h b/src/Platform/GlxApplication.h index 91533277b..dcd6041a4 100644 --- a/src/Platform/GlxApplication.h +++ b/src/Platform/GlxApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::GlxApplication + * @brief Class @ref Magnum::Platform::GlxApplication */ #include "Platform/AbstractXApplication.h" @@ -35,21 +35,31 @@ namespace Magnum { namespace Platform { /** @brief GLX application -Uses GlxContextHandler. See @ref platform for brief introduction. +Application using pure X11 and GLX. Supports keyboard and mouse handling. See +@ref platform for brief introduction. + +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 +`${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. @section GlxApplication-usage Usage -You need to implement at least drawEvent() and viewportEvent() to be able to -draw on the screen. The subclass can be then used directly in `main()` - see -convenience macro MAGNUM_GLXAPPLICATION_MAIN(). +You need to implement at least @ref drawEvent() and @ref viewportEvent() to be +able to draw on the screen. The subclass can be then used directly in `main()` +-- see convenience macro @ref MAGNUM_GLXAPPLICATION_MAIN(). @code -class MyApplication: public Magnum::Platform::GlxApplication { +class MyApplication: public Platform::GlxApplication { // implement required methods... }; MAGNUM_GLXAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. */ diff --git a/src/Platform/NaClApplication.h b/src/Platform/NaClApplication.h index 2c40db2a4..6dcdf360e 100644 --- a/src/Platform/NaClApplication.h +++ b/src/Platform/NaClApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::NaClApplication + * @brief Class @ref Magnum::Platform::NaClApplication */ #include @@ -55,19 +55,27 @@ namespace Magnum { namespace Platform { Application running in [Google Chrome Native Client](https://developers.google.com/native-client/). Supports keyboard and mouse handling. See @ref platform for brief introduction. +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 +`${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. + @section NaClApplication-usage Usage -You need to implement at least drawEvent() and viewportEvent() to be able to -draw on the screen. The subclass must be then registered to NaCl API using -MAGNUM_NACLAPPLICATION_MAIN() macro. +You need to implement at least @ref drawEvent() and @ref viewportEvent() to be +able to draw on the screen. The subclass must be then registered to NaCl API +using @ref MAGNUM_NACLAPPLICATION_MAIN() macro. @code -class MyApplication: public Magnum::Platform::NaClApplication { +class MyApplication: public Platform::NaClApplication { // implement required methods... }; MAGNUM_NACLAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. diff --git a/src/Platform/Sdl2Application.h b/src/Platform/Sdl2Application.h index b3f077451..e2c4f9721 100644 --- a/src/Platform/Sdl2Application.h +++ b/src/Platform/Sdl2Application.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::Sdl2Application + * @brief Class @ref Magnum::Platform::Sdl2Application */ #include @@ -50,26 +50,37 @@ namespace Platform { /** @nosubgrouping @brief SDL2 application -Application using [Simple DirectMedia Layer](www.libsdl.org/). Supports +Application using [Simple DirectMedia Layer](www.libsdl.org/) toolkit. Supports keyboard and mouse handling. See @ref platform for brief introduction. +This application library is available on desktop OpenGL (Linux, Windows, OS X) +and in @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten". 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. + @section Sdl2Application-usage Usage -You need to implement at least drawEvent() and viewportEvent() to be able to -draw on the screen. The subclass can be then used directly in `main()` -- see -convenience macro MAGNUM_SDL2APPLICATION_MAIN(). +You need to implement at least @ref drawEvent() and @ref viewportEvent() to be +able to draw on the screen. The subclass can be then used directly in `main()` +-- see convenience macro @ref MAGNUM_SDL2APPLICATION_MAIN(). @code -class MyApplication: public Magnum::Platform::Sdl2Application { +class MyApplication: public Platform::Sdl2Application { // implement required methods... }; MAGNUM_SDL2APPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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 Usage with Emscripten +@section Sdl2Application-html 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 diff --git a/src/Platform/WindowlessGlxApplication.h b/src/Platform/WindowlessGlxApplication.h index 73e890dd4..bdd6db396 100644 --- a/src/Platform/WindowlessGlxApplication.h +++ b/src/Platform/WindowlessGlxApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::WindowlessGlxApplication + * @brief Class @ref Magnum::Platform::WindowlessGlxApplication */ #include @@ -45,20 +45,31 @@ namespace Magnum { namespace Platform { /** @brief Windowless GLX application -See @ref platform for brief introduction. +Application for offscreen rendering using pure X11 and GLX. See @ref platform +for brief introduction. + +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 +`${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}` and +`${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. @section WindowlessGlxApplication-usage Usage -Place your code into exec(). The subclass can be then used directly in -`main()` -- see convenience macro MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN(). +Place your code into @ref exec(). The subclass can be then used directly in +`main()` -- see convenience macro @ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN(). @code -class MyApplication: public Magnum::Platform::WindowlessGlxApplication { +class MyApplication: public Platform::WindowlessGlxApplication { // implement required methods... }; MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. */ diff --git a/src/Platform/WindowlessNaClApplication.h b/src/Platform/WindowlessNaClApplication.h index 5b15d5c0f..78866fca3 100644 --- a/src/Platform/WindowlessNaClApplication.h +++ b/src/Platform/WindowlessNaClApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::WindowlessNaClApplication + * @brief Class @ref Magnum::Platform::WindowlessNaClApplication */ #include @@ -50,21 +50,31 @@ namespace Magnum { namespace Platform { /** @nosubgrouping @brief Windowless NaCl application -Application running in [Google Chrome Native Client](https://developers.google.com/native-client/). +Application for offscreen rendering running in +[Google Chrome Native Client](https://developers.google.com/native-client/). See @ref platform for brief introduction. +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 +`${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 +`${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}` and +`${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. + @section WindowlessNaClApplication-usage Usage -Place your code into exec(). The subclass must be then registered to NaCl API -using MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() macro. +Place your code into @ref exec(). The subclass must be then registered to NaCl +API using @ref MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() macro. @code -class MyApplication: public Magnum::Platform::WindowlessNaClApplication { +class MyApplication: public Platform::WindowlessNaClApplication { // implement required methods... }; MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. diff --git a/src/Platform/XEglApplication.h b/src/Platform/XEglApplication.h index 4f0182757..11b9c4c56 100644 --- a/src/Platform/XEglApplication.h +++ b/src/Platform/XEglApplication.h @@ -25,7 +25,7 @@ */ /** @file - * @brief Class Magnum::Platform::XEglApplication + * @brief Class @ref Magnum::Platform::XEglApplication */ #include "Platform/AbstractXApplication.h" @@ -35,21 +35,32 @@ namespace Magnum { namespace Platform { /** @brief X/EGL application -Uses EglContextHandler. See @ref platform for brief introduction. +Application using pure X11 and EGL. Supports keyboard and mouse handling. See +@ref platform for brief introduction. + +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 +application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` +and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. @section XEglApplication-usage Usage -You need to implement at least drawEvent() and viewportEvent() to be able to -draw on the screen. The subclass can be then used directly in `main()` - see -convenience macro MAGNUM_XEGLAPPLICATION_MAIN(). +You need to implement at least @ref drawEvent() and @ref viewportEvent() to be +able to draw on the screen. The subclass can be then used directly in `main()` +-- see convenience macro @ref MAGNUM_XEGLAPPLICATION_MAIN(). @code -class MyApplication: public Magnum::Platform::XEglApplication { +class MyApplication: public Platform::XEglApplication { // implement required methods... }; MAGNUM_XEGLAPPLICATION_MAIN(MyApplication) @endcode -If no other application header is included this class is also aliased to +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. */