diff --git a/doc/building.dox b/doc/building.dox index 1aa8e429b..dbbfde068 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -29,6 +29,7 @@ namespace Magnum { @brief Guide how to download and build Magnum on different platforms. @m_keywords{Building} +@m_keyword{ANGLE OpenGL compatibility layer,,} @tableofcontents @m_footernavigation diff --git a/doc/platforms-gl.dox b/doc/platforms-gl.dox index f023ed773..bcf40e36a 100644 --- a/doc/platforms-gl.dox +++ b/doc/platforms-gl.dox @@ -29,6 +29,7 @@ namespace Magnum { @brief Information common for all platforms that support OpenGL and OpenGL ES @tableofcontents +@m_keyword{ANGLE OpenGL compatibility layer,,} @m_footernavigation @todoc desktop gles diff --git a/doc/platforms-ios.dox b/doc/platforms-ios.dox index 846b4da91..7769ec03c 100644 --- a/doc/platforms-ios.dox +++ b/doc/platforms-ios.dox @@ -32,11 +32,64 @@ namespace Magnum { @m_footernavigation With Apple decision to focus on Metal, iOS OpenGL ES support is stuck on -version 3.0 (i.e., a version before compute shaders are available). +version 3.0 (i.e., a version before compute shaders are available). Moreover, +OpenGL ES is deprecated since iOS 12. -See also @ref Platform::Sdl2Application for more information. Some of the +See also @ref Platform::Sdl2Application for more information, majority of the @ref platforms-macos "macOS platform-specific info" applies here as well. +@section platforms-ios-bundle Bundle creation + +Unlike on macOS, where applications can also run directly from a compiled +executable, on iOS you are required to create a bundle. The bundle setup is +similar to macOS, see the @ref platforms-macos-bundle "macOS platform guide" +for details. Compared to macOS, the `*.plist` file controls many more options +(such as HiDPI/Retina support, supported display orientation, icons, splash +screen...). CMake uses its own template that can be configured using various +`MACOSX_BUNDLE_*` variables, but the builtin file is tailored for macOS and you +are much better off rolling your own template and passing **abosolute** path to +it to CMake using the `MACOSX_BUNDLE_INFO_PLIST` property: + +@code{.cmake} +if(CORRADE_TARGET_IOS) + set_target_properties(my-application PROPERTIES + MACOSX_BUNDLE ON + MACOSX_BUNDLE_INFO_PLIST ${CMAKE_CURRENT_SOURCE_DIR}/MacOSXBundleInfo.plist.in) +endif() +@endcode + +Below are contents of the `*.plist` file as is used in the +@ref Platform-Sdl2Application-bootstrap-ios "SDL2 bootstrap application", +requesting OpenGL ES 2.0 and advertising Retina support: + +@code{.xml} + + + + + CFBundleDevelopmentRegion + en-US + CFBundleExecutable + ${MACOSX_BUNDLE_EXECUTABLE_NAME} + CFBundleIdentifier + cz.mosra.magnum.MyApplication + CFBundleInfoDictionaryVersion + 6.0 + CFBundleName + My Application + CFBundlePackageType + APPL + + UIRequiredDeviceCapabilities + + opengles-2 + + NSHighResolutionCapable + + + +@endcode + @section platforms-ios-xcode Xcode @subsection platforms-ios-xcode-cmake CMake can't find a compiler diff --git a/doc/platforms-macos.dox b/doc/platforms-macos.dox index 1d4cceb6a..668627a19 100644 --- a/doc/platforms-macos.dox +++ b/doc/platforms-macos.dox @@ -34,7 +34,8 @@ namespace Magnum { @todoc code coverage With Apple decision to focus on Metal, macOS OpenGL support is stuck on version -4.2 (i.e., a version before compute shaders are available). +4.2 (i.e., a version before compute shaders are available). Moreover, OpenGL is +deprecated since macOS 10.14. @section platforms-macos-bundle Bundle creation diff --git a/doc/platforms-windows.dox b/doc/platforms-windows.dox index 3c39f8802..b36b17345 100644 --- a/doc/platforms-windows.dox +++ b/doc/platforms-windows.dox @@ -29,9 +29,58 @@ namespace Magnum { @brief Tips and tricks for Windows platforms @tableofcontents +@m_keyword{ANGLE OpenGL compatibility layer,,} @m_footernavigation -See @ref Platform::Sdl2Application for more information about WinRT. +@section platforms-windows-rt Windows RT + +Windows RT is a restricted subset of Windows API, used for UWP / "Metro" / +Windows Store apps. The major difference is lack of access to APIs that are +common in Win32 world, such as memory-mapped files, DLLs or environment +variables. + +In particular, Windows RT doesn't provide a direct access to OpenGL, the only +possibility to use it is through ANGLE. See @ref building-windows-angle and +@ref platforms-gl-es-angle for more information. + +For Windows RT you need to provide logo images and splash screen, all +referenced from the `*.appxmanifest` file. The file is slightly different for +different targets, template for Windows Store and MSVC 2013 is below, others +are in the @ref Platform-Sdl2Application-bootstrap-winrt "SDL2 bootstrap application". + +@code{.xml} + + + + + My Application + A Publisher + assets/logo-store.png + + + + + + + + + + + + +@endcode + +The assets are referenced also from the main `CMakeLists.txt` file. You have to +mark all non-source files (except for the `*.pfx` key) with `VS_DEPLOYMENT_CONTENT` +property and optionally set their location with `VS_DEPLOYMENT_LOCATION`. If +you are using `*.resw` files, these need to have the `VS_TOOL_OVERRIDE` +property set to `PRIResource`. @todoc DLL paths @todoc vcpkg diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 395183de1..2281069fe 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -224,94 +224,18 @@ If no other application header is included, this class is also aliased to @cpp Platform::Application @ce and the macro is aliased to @cpp MAGNUM_APPLICATION_MAIN() @ce to simplify porting. -@section Platform-Sdl2Application-usage-ios Usage with iOS - -A lot of options for iOS build (such as HiDPI/Retina support, supported display -orientation, icons, splash screen...) is specified through the `*.plist` file. -CMake uses its own template that can be configured using various `MACOSX_BUNDLE_*` -variables, but many options are missing from there and you are much better off -rolling your own template and passing **abosolute** path to it to CMake using -the `MACOSX_BUNDLE_INFO_PLIST` property. Below are contents of the `*.plist` -file used in the bootstrap application, requesting OpenGL ES 2.0 and -advertising Retina support: - -@code{.xml} - - - - - CFBundleDevelopmentRegion - en-US - CFBundleExecutable - ${MACOSX_BUNDLE_EXECUTABLE_NAME} - CFBundleIdentifier - cz.mosra.magnum.MyApplication - CFBundleInfoDictionaryVersion - 6.0 - CFBundleName - My Application - CFBundlePackageType - APPL - - UIRequiredDeviceCapabilities - - opengles-2 - - NSHighResolutionCapable - - - -@endcode +@subsection Platform-Sdl2Application-usage-ios iOS specifics -Some other options can be configured from runtime when creating the SDL2 -application window, see documentation of particular value for details: +As noted in the @ref platforms-ios-bundle "iOS platform guide", a lot of +options needs to be set via a `*.plist` file. Some options can be configured +from runtime when creating the SDL2 application window, see documentation of +a particular value for details: - @ref Configuration::WindowFlag::AllowHighDpi allows creating HiDPI/Retina drawable - @ref Configuration::WindowFlag::Borderless hides the menu bar - @ref Configuration::WindowFlag::Resizable makes the application respond to device orientation changes - -@section Platform-Sdl2Application-usage-winrt Usage with Windows RT - -For Windows RT you need to provide logo images and splash screen, all -referenced from the `*.appxmanifest` file. The file is slightly different for -different targets, template for Windows Store and MSVC 2013 is below, others -are in the bootstrap application. - -@code{.xml} - - - - - My Application - A Publisher - assets/logo-store.png - - - - - - - - - - - - -@endcode - -The assets are referenced also from the main `CMakeLists.txt` file. You have to -mark all non-source files (except for the `*.pfx` key) with `VS_DEPLOYMENT_CONTENT` -property and optionally set their location with `VS_DEPLOYMENT_LOCATION`. If -you are using `*.resw` files, these need to have the `VS_TOOL_OVERRIDE` -property set to `PRIResource`. */ class Sdl2Application { public: