From 08c8f5a6350468a1ac20408d69d654c2b7df54e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 11 Feb 2016 11:45:13 +0100 Subject: [PATCH] Advertise iOS support, document building and usage. --- README.md | 1 + doc/building.dox | 29 ++++++++++ doc/mainpage.dox | 2 +- src/Magnum/Platform/Sdl2Application.h | 82 ++++++++++++++++++++++++++- 4 files changed, 112 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5cf9212e6..0c941e11c 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,7 @@ Platforms: SDL2 or GLUT toolkit) [![Build Status](https://travis-ci.org/mosra/magnum.svg?branch=master)](https://travis-ci.org/mosra/magnum) * **Windows** natively or using ANGLE (through SDL2 or GLUT toolkit) [![Build status](https://ci.appveyor.com/api/projects/status/5b477m034cfaskse/branch/master?svg=true)](https://ci.appveyor.com/project/mosra/magnum/branch/master) * **OS X** (through SDL2 toolkit) [![Build Status](https://travis-ci.org/mosra/magnum.svg?branch=master)](https://travis-ci.org/mosra/magnum) +* **iOS** (through SDL2 toolkit) * **Android** 2.3 (API Level 9) and higher * **Windows RT** (Store/Phone) using ANGLE (through SDL2 toolkit) * **Google Chrome** (through [Native Client](https://developers.google.com/native-client/), diff --git a/doc/building.dox b/doc/building.dox index b1a5cdcec..f8a66421f 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -522,6 +522,35 @@ information. See @ref Platform::Sdl2Application documentation for more information about building your projects for Emscripten. +@subsection building-cross-ios Crosscompiling for iOS + +You will need OSX and Xcode installed. + +Set `CMAKE_OSX_ROOT` to SDK you want to target and enable all desired +architectures in `CMAKE_OSX_ARCHITECTURES`. The toolchain needs access to its +platform file, so be sure to properly set **absolute** path to `modules/` +directory containing `Platform/iOS.cmake`. Set `CMAKE_INSTALL_PREFIX` to prefix +where you store other iOS dependencies such as Corrade or SDL2. + +OpenGL ES 2.0 is enabled by default, switch to 3.0 by disabling `TARGET_GLES2`. + + mkdir build-ios && cd build-ios + cmake .. \ + -DCMAKE_MODULE_PATH=/absolute/path/to/toolchains/modules/ \ + -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \ + -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \ + -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \ + -DCMAKE_INSTALL_PREFIX=~/ios-libs \ + -DWITH_SDL2APPLICATION=ON \ + -G Xcode + cmake --build . + +Then you can install the library using `cmake --build . --target install` to +make it available for depending projects. + +See @ref Platform::Sdl2Application documentation for more information about +building your projects for iOS. + @subsection building-cross-android Crosscompiling for Android ARM and x86 You will need [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 0adc3db54..e1af78bb3 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -79,7 +79,7 @@ Platforms: - **Linux** and embedded Linux (natively using GLX/EGL and Xlib or through SDL2 or GLUT toolkit) - **Windows** natively or using ANGLE (through SDL2 or GLUT toolkit) -- **OS X** (through SDL2 toolkit) +- **OS X**, **iOS** (through SDL2 toolkit) - **Android** 2.3 (API Level 9) and higher - **Windows RT** (Store/Phone) using ANGLE (through SDL2 toolkit) - **Google Chrome** (through [Native Client](https://developers.google.com/native-client/), diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index ff6c330bd..42c183fd3 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -110,6 +110,37 @@ webserver, e.g. `/srv/http/emscripten`). You can then open `MyApplication.html` in Chrome or Firefox (through webserver, e.g. `http://localhost/emscripten/MyApplication.html`). +## Bootstrap application for iOS + +Fully contained base application using @ref Sdl2Application for both desktop +and iOS build along with pre-filled `*.plist` is available in `base-ios` branch +of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository, +download it as [tar.gz](https://github.com/mosra/magnum-bootstrap/archive/base-ios.tar.gz) +or [zip](https://github.com/mosra/magnum-bootstrap/archive/base-ios.zip) file. +After extracting the downloaded archive, you can do the desktop build in +the same way as above. For the iOS build you also need to put the contents of +toolchains repository from https://github.com/mosra/toolchains in `toolchains/` +subdirectory. + +Then create build directory and run `cmake` to generate the Xcode project. Set +`CMAKE_OSX_ROOT` to SDK you want to target and enable all desired architectures +in `CMAKE_OSX_ARCHITECTURES`. The toolchain needs access to its platform file, +so be sure to properly set **absolute** path to `toolchains/modules/` directory +containing `Platform/iOS.cmake`. Set `CMAKE_PREFIX_PATH` to the directory where +you have all the dependencies. + + mkdir build-ios && cd build-ios + cmake .. \ + -DCMAKE_MODULE_PATH=/absolute/path/to/toolchains/modules/ \ + -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \ + -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \ + -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \ + -DCMAKE_PREFIX_PATH=~/ios-libs \ + -G Xcode + +You can then open the generated project file in Xcode and build/deploy it from +there. + ## Bootstrap application for Windows RT Fully contained base application using @ref Sdl2Application for both desktop @@ -199,6 +230,53 @@ The application redirects all output (thus also @ref Corrade::Utility::Debug "De @ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error") to JavaScript console. +## 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 + + + + + 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 + +Some other options can be configured from runtime when creating the SDL2 +application window, see documentation of 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 + ## Usage with Windows RT For Windows RT you need to provide logo images and splash screen, all @@ -590,7 +668,9 @@ class Sdl2Application::Configuration { #ifndef CORRADE_TARGET_EMSCRIPTEN /** - * Allow high DPI. + * Allow high DPI. On iOS you also have to set the + * `NSHighResolutionCapable` entry in the `*.plist` file to make + * it working. * @note Not available in @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten". */ AllowHighDpi = SDL_WINDOW_ALLOW_HIGHDPI,