diff --git a/Doxyfile-mcss b/Doxyfile-mcss index 8300265da..a6e00bdb2 100644 --- a/Doxyfile-mcss +++ b/Doxyfile-mcss @@ -97,8 +97,8 @@ M_PAGE_FINE_PRINT = "

Magnum docs. Part of the : or / suffix lists all members of given symbol or directory. Navigate through the list using ↓ and ↑, press Enter to go." M_LINKS_NAVBAR1 = \ - "getting-started" \ - "pages features example-index tips utilities" + "getting-started building cmake" \ + "pages features platforms example-index tips utilities" M_LINKS_NAVBAR2 = \ "namespaces" \ "annotated" \ diff --git a/doc/best-practices.dox b/doc/best-practices.dox deleted file mode 100644 index 86d32550b..000000000 --- a/doc/best-practices.dox +++ /dev/null @@ -1,106 +0,0 @@ -/* - This file is part of Magnum. - - Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 - Vladimír Vondruš - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. -*/ - -namespace Magnum { -/** @page best-practices Best practices, pitfalls and platform-specific information -@brief Performance advices and solutions for platform-specific issues. - -@tableofcontents -@m_footernavigation - -Here is collection of carefully selected notes, links to official guidelines -and other articles with valuable information to help developers create better -applications. Feel free to add one, if it contains new unique information. - -@section best-practices-gles GLES-specific - -- Rendering to RGB textures doesn't work on many platforms, either due to - alignment issues or other factors. For example it is not possible to render - to @ref TextureFormat::RGB8 on iOS (but it works elsewhere); rendering to - @ref TextureFormat::RGB32F is not possible even on NVidia. Use RGBA formats - instead. -- [Writing Portable OpenGL ES 2.0](https://www.khronos.org/assets/uploads/developers/library/2011-siggraph-mobile/Writing-Portable-OpenGL-ES-2.0_Aug-11.pdf) - -@section best-practices-platform Platform-specific - -Some platforms need special care, see their respective sections for more -information. - -@subsection best-practices-mac macOS - -- @ref AbstractShaderProgram::validate() expects that the shader has a - properly configured framebuffer bound along with proper @ref Renderer - setup. That is often hard to achieve, so the function cannot be portably - used for shader validity testing. -- `GL_TIMESTAMP` used by @ref TimeQuery::timestamp() is not implemented on - macOS and gives zero results. -- [Best Practices for Working with Vertex Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_vertexdata/opengl_vertexdata.html) -- [Best Practices for Working with Texture Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_texturedata/opengl_texturedata.html) - -@subsection best-practices-ios iOS - -- GLSL @glsl texelFetch() @ce returns zero results if you have a texture with - integer type and the filtering is not @ref Sampler::Filter::Nearest. Yes, - it shouldn't matter, but it does. -- OpenGL ES 3.0 contexts don't support rendering to 32-bit float textures. - However, it is possible to work around that issue by creating 32-bit - unsigned integer texture -- [Best Practices for Working with Vertex Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html) -- [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html) -- [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3) - -@subsection best-practices-angle ANGLE (WebGL) - -- [WebGL Insights --- ANGLE](https://books.google.cz/books?id=6crECQAAQBAJ&lpg=PP1&pg=PA3&redir_esc=y#v=onepage&q&f=true) - -@subsection best-practices-webgl WebGL (Emscripten) - -WebGL is subset of OpenGL ES with some [specific restrictions and features](http://www.khronos.org/registry/webgl/specs/latest/1.0/#6), -namely requirement for unique buffer target binding, aligned buffer offset and -stride and some other restrictions and also support for combined depth/stencil -buffer attachments. See @ref Buffer, @ref Framebuffer, -@ref Texture::setSubImage() "*Texture::setSubImage()", @ref Mesh::addVertexBuffer(), -@ref Renderer::setStencilFunction(), @ref Renderer::setStencilMask() and -@ref Renderer::setBlendFunction() documentation for more information. - -@section best-practices-hw Hardware-specific - -@subsection best-practices-intel Intel hardware - -- [Performance tuning applications for Intel Graphics for Linux and Chrome OS](http://software.intel.com/sites/default/files/Performance-tuning-applications-for-Intel-GEN-Graphics-for-Linux-and-Google-Chrome-OS.pdf) [PDF] - -@subsection best-practices-powervr PowerVR hardware - -- [PowerVR Performance Recommendations](https://github.com/burningsun/pecker_framework/blob/master/参考资料/PowerVR.Performance%20Recommendations.pdf?raw=true) [PDF] - -@subsection best-practices-amd AMD hardware - -- [ATI Radeon HD 2000 programming guide](http://developer.amd.com/wordpress/media/2012/10/ATI_Radeon_HD_2000_programming_guide.pdf) - -@subsection best-practices-tegra NVidia Tegra hardware - -- [Optimize OpenGL ES 2.0 Performance for Tegra](http://docs.nvidia.com/tegra/index.html#GLES2_Perf_Main.html) -*/ -} diff --git a/doc/building.dox b/doc/building.dox index d6e2052f8..690061bbf 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -624,6 +624,8 @@ cmake .. ^ cmake --build . @endcode +See @ref platforms-gl-es-angle for more information about using ANGLE. + @section building-cross Cross-compiling For cross-compiling you need to have *both* target and native version of @@ -681,8 +683,8 @@ instead. When done, you can install the package using @cb{.bat} cmake --build . --target install @ce to make it available to depending projects. -See @ref Platform::Sdl2Application documentation for more information about -building your projects for WinRT. +See @ref platforms-windows for more information about building your projects +for WinRT. @subsection building-cross-win Cross-compiling for Windows using MinGW-w64 @@ -720,6 +722,9 @@ cmake --build . Then you can install the package using @cb{.sh} cmake --build . --target install @ce to make it available to depending projects. +See @ref platforms-windows for more information about building your projects +for Windows. + @subsection building-cross-emscripten Cross-compiling for Emscripten You will need [Emscripten](http://kripken.github.io/emscripten-site/) installed @@ -782,8 +787,8 @@ named `PKGBUILD-emscripten`, `PKGBUILD-emscripten-webgl2`, WebGL 1 / WebGL 2 optimized asm.js build (*slow* to compile), the second for unoptimized build (faster to compile) and the third for WebAssembly build. -See @ref Platform::Sdl2Application documentation for more information about -building your projects for Emscripten. +See @ref platforms-html5 for more information about building your projects for +Emscripten. @subsection building-cross-ios Cross-compiling for iOS @@ -822,8 +827,8 @@ cmake --build . Then you can install the library using @cb{.sh} cmake --build . --target install @ce to make it available to depending projects. -See @ref Platform::Sdl2Application documentation for more information about -building your projects for iOS. +See @ref platforms-ios documentation for more information about building your +projects for iOS. @subsection building-cross-android Crosscompiling for Android @@ -888,8 +893,8 @@ more information. build arbitrary Android projects. To fix it, use a different generator (for example Ninja, by passing `-G Ninja` to CMake). -See @ref Platform::AndroidApplication documentation for more information about -building your projects for Android. +See @ref platforms-android for more information about building your projects +for Android. @section building-ci Continuous Integration diff --git a/doc/changelog.dox b/doc/changelog.dox index 61646e7cb..a8b746abf 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -73,7 +73,7 @@ See also: @subsection changelog-latest-bugfixes Bug fixes - Engine startup info was not properly printed to Android log since - introducing the `--magnum-log` option in 2018.02 + introducing the `--magnum-log` option in version 2018.02 @subsection changelog-latest-deprecated Deprecated APIs @@ -223,7 +223,7 @@ See also: maintainers and core developers - A new set of @ref platforms "platform-specific guides" containing extended information that was previously scattered across @ref Platform application - class docs + class docs and elsewhere - Completely reworked @ref platforms-android "Android building" documentation, now using Gradle CMake integration instead of the outdated and no longer supported Apache Ant workflow. diff --git a/doc/platforms-android.dox b/doc/platforms-android.dox index 6907ef817..037ad1210 100644 --- a/doc/platforms-android.dox +++ b/doc/platforms-android.dox @@ -31,6 +31,9 @@ namespace Magnum { @tableofcontents @m_footernavigation +@todoc testing, gl tests, code coverage, travis setup +@todoc static plugins + The following guide explains how to build Android projects using minimal command-line tools, without Android Studio involved. @@ -39,14 +42,16 @@ Running console utilities and tests on the device don't need much more, in case you want to develop actual applications, you need also Gradle and SDK platform + SDK platform build tools for version of your choice. Gradle is able to download all the dependencies on its own, however it's also possible to install system -packages for a cleaner setup. On ArchLinux it's the `gradle` package and the -following AUR packages, adapt the version numbers as necessary: +packages for a cleaner setup. -- [android-sdk](https://aur.archlinux.org/packages/android-sdk/) -- [android-ndk](https://aur.archlinux.org/packages/android-ndk/) -- [android-sdk-build-tools-26.0.2](https://aur.archlinux.org/packages/android-sdk-build-tools-26.0.2/) -- [android-platform-25](https://aur.archlinux.org/packages/android-platform-25/) -- [android-sdk-cmake](https://aur.archlinux.org/packages/android-sdk-cmake/) +@note On ArchLinux it's the `gradle` package and the following AUR packages, + adapt the version numbers as necessary: +@note + - [android-sdk](https://aur.archlinux.org/packages/android-sdk/) + - [android-ndk](https://aur.archlinux.org/packages/android-ndk/) + - [android-sdk-build-tools-26.0.2](https://aur.archlinux.org/packages/android-sdk-build-tools-26.0.2/) + - [android-platform-25](https://aur.archlinux.org/packages/android-platform-25/) + - [android-sdk-cmake](https://aur.archlinux.org/packages/android-sdk-cmake/) Gradle requires Android SDK version of CMake, which is currently at version 3.6. See below for an experimental way to @ref platforms-android-system-cmake "use the system CMake" @@ -54,9 +59,9 @@ instead. @section platforms-android-command-line Building and running console applications -Android allows to run arbitrary console utilities and tests. Assuming you have -Magnum installed in the NDK path as described in @ref building-cross-android, -build your project simply as this (adapt as needed): +Android allows to run arbitrary console utilities and tests via ADB. Assuming +you have Magnum installed in the NDK path as described in @ref building-cross-android, +build your project simply as this (adapt version numbers and ABIs as needed): @code{.sh} mkdir build-android-arm64 && cd build-android-arm64 @@ -74,10 +79,10 @@ After that you can use ADB to upload your executable to the device and run it there. The global temporary directory is `/data/local/tmp` and while the parent directories often don't have permissions, it's possible to @cb{.sh} cd @ce into it and create arbitrary files there. Assuming you built an executable in -`src/my-application`, the workflow would be like this: +`build-android-arm64/src/my-application`, the workflow would be like this: @code{.sh} -adb push src/my-application /data/local/tmp +adb push build-android-arm64/src/my-application /data/local/tmp adb shell /data/local/tmp/my-application @endcode @@ -86,19 +91,30 @@ continue from there. Besides plain command-line apps it's also possible to create an EGL context without any extra setup using @ref Platform::WindowlessEglApplication. -@section platforms-android-apps Building and installing graphics applications +@section platforms-android-apps Building and installing graphics apps Building of graphics applications is managed fully using Gradle, which also -builds your CMake project internally. In case you don't have OpenGL ES build -set up yet, you need to copy `FindEGL.cmake` and `FindOpenGLES2.cmake` (or -`FindOpenGLES3.cmake`) from the `modules/` directory in Magnum source to the -`modules/` dir in your project so it is able to find EGL and OpenGL ES -libraries. +builds your CMake project internally. It's possible to use other means such as +`ndk-build`, but CMake is the officially preferred way. The following guide +assumes you have Gradle installed in a system-wide location available in +@cb{.sh} $PATH @ce. See the [Gradle installation docs](https://docs.gradle.org/current/userguide/installation.html) +for more information, @ref platforms-android-gradlew "see below" if you want to +use the `gradlew` wrappers instead. + +In case you don't have an OpenGL ES build set up yet, you need to copy +`FindEGL.cmake` and `FindOpenGLES2.cmake` (or `FindOpenGLES3.cmake`) from the +[modules/](https://github.com/mosra/magnum/tree/master/modules) directory in +Magnum source to the `modules/` dir in your project so it is able to find EGL +and OpenGL ES libraries. Magnum provides Android application wrapper in @ref Platform::AndroidApplication. See its documentation for more information about general usage. You can also use the Android Native Activity directly or any other way. +@note The @ref Platform::AndroidApplication also contains a fully configured + bootstrap project that's ready to build and deploy. Check its documentation + for details. + The first thing you need compared to building an app for other platforms is creating a shared library instead of an executable: @@ -139,7 +155,7 @@ android { } } ndk { - abiFilters "arm64-v8a" + abiFilters 'arm64-v8a' } } @@ -217,14 +233,120 @@ gradle installDebug after which you can launch the app from your home screen. See the @ref platforms-android-troubleshooting section below if you ran into problems. +@section platforms-android-multiple-abis Building for multiple ABIs and system versions + +The above guide simplifies things a bit and builds for just a single ARM64 ABI. +In order to support multiple platforms, you need to separately build and +install the dependencies for all ABIs of choice --- create separate build +directories and run CMake with different `CMAKE_ANDROID_ARCH_ABI` and +corresponding `CMAKE_INSTALL_PREFIX`. Similarly with SDK versions, adapt +`CMAKE_SYSTEM_VERSION` and `CMAKE_INSTALL_PREFIX` to a desired version. The +headers are shared and should be always installed into `<ndk>/sysroot/usr` +regardless of ABI or SDK version. The supported ABI values are: + +ABI | Corresponding install prefix +----------- | ---------------------------- +armeabi-v7a | <nk>/platforms/android-<version>/arch-arm/usr +arm64-v8a | <nk>/platforms/android-<version>/arch-arm64/usr +x86 | <nk>/platforms/android-<version>/arch-x86/usr +x86_64 | <nk>/platforms/android-<version>/arch-x86_64/usr + +After that, you can add the additional ABIs to the `abiFilters` list in your +`build.gradle`. + +For example, building Magnum for 32-bit and 64-bit ARM with SDK version 24 +could look like this: + +@code{.sh} +mkdir build-android-arm && cd build-android-arm +cmake .. \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION=24 \ + -DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \ + -DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang \ + -DCMAKE_ANDROID_STL_TYPE=c++_static \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/platforms/android-24/arch-arm/usr \ + -DMAGNUM_INCLUDE_INSTALL_PREFIX=/sysroot/usr +cmake --build . --target install + +cd .. + +mkdir build-android-arm64 && cd build-android-arm64 +cmake .. \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION=24 \ + -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \ + -DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang \ + -DCMAKE_ANDROID_STL_TYPE=c++_static \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/platforms/android-24/arch-arm64/usr \ + -DMAGNUM_INCLUDE_INSTALL_PREFIX=/sysroot/usr +cmake --build . --target install +@endcode + +And the `build.gradle` for your app then looks like this: + +@code{.gradle} +buildscript { + repositories { + jcenter() + google() + } + dependencies { + classpath 'com.android.tools.build:gradle:3.0.1' + } +} + +apply plugin: 'com.android.application' + +android { + compileSdkVersion 25 + + defaultConfig { + minSdkVersion 24 + + externalNativeBuild { + cmake { + arguments '-DANDROID_STL=c++_static' + } + } + ndk { + abiFilters 'armeabi-v7a', 'arm64-v8a' + } + } + + externalNativeBuild { + cmake { + path 'CMakeLists.txt' + } + } +} +@endcode + +See [the official documentation about ABIs](https://developer.android.com/ndk/guides/abis.html) +for more information. + @section platforms-android-output-redirection Redirecting output to Android log buffer While printing to standard output and standard error output "just works" with command-line apps, you might want to redirect your @ref Corrade::Utility::Debug "Debug", @ref Corrade::Utility::Warning "Warning" and @ref Corrade::Utility::Error "Error" output to Android log buffer. so it can be accessed through the @cb{.sh} adb logcat @ce -utility. See @ref Corrade::Utility::AndroidLogStreamBuffer for more information ---- the @ref Platform::AndroidApplication sets this up implicitly. +utility. See @ref Corrade::Utility::AndroidLogStreamBuffer for more +information. + +The @ref Platform::AndroidApplication sets this up implicitly with a `magnum` +tag, you can then filter it out like this, for example: + +@code{.shell-session} +$ adb logcat *:S magnum +... +03-16 17:35:26.703 17726 17745 I magnum : Renderer: Mali-G71 by ARM +03-16 17:35:26.703 17726 17745 I magnum : OpenGL version: OpenGL ES 3.2 v1.r2p0 +03-16 17:35:26.703 17726 17745 I magnum : Using optional features: +03-16 17:35:26.703 17726 17745 I magnum : GL_EXT_robustness +@endcode @section platforms-android-system-cmake Using system-wide CMake installation @@ -250,9 +372,58 @@ android { However, be aware that this is an experimental feature and may be broken. (It didn't work for me with 3.10.) +@section platforms-android-gradlew Using gradlew wrappers instead of a system installation + +It's possible to bundle Gradle in the project itself as opposed to requiring a +pre-existing system installation. It has the downside of having a bit more +boilerplate files in your project, though. + +First, add the following to your `build.gradle` file: + +@code{.gradle} +task wrapper(type: Wrapper) { + gradleVersion = '4.0' +} +@endcode + +Then run this on a system that has Gradle installed: + +@code{.sh} +gradle wrapper +@endcode + +This will generate the following files that you can then add to version +control: + +- `gradlew` shell script for Unix-like systems +- `gradle.bat` batch script for Windows +- `gradle/` directory with wrapper binaries + +With this in place, you can just use @cb{.sh} gradlew @ce instead of +@cb{.sh} gradle @ce. + @section platforms-android-troubleshooting Troubleshooting -@subsection platforms-android-troubleshooting-anativeactivity App can't launch +@subsection platforms-android-troubleshooting-cant-find Gradle CMake can't find dependencies + +Gradle by default searches only in the NDK install path. If you have your +dependencies installed somewhere else (this goes especially for the *native* +`corrade-rc` executable), you might want to point the `CMAKE_PREFIX_PATH` +environment variable to your install location: + +@code{.sh} +export CMAKE_PREFIX_PATH= +gradle build +@endcode + +If you have the dependencies installed in the NDK path, but it still fails, +check that you installed for the same SDK version as in `minSdkVersion` and all +ABIs mentioned in `abiFilters` inside your `build.gradle` file --- Gradle runs +CMake once for each entry in the list so it might happen that it finds them for +all but one ABI. See @ref platforms-android-multiple-abis above for more +information. + +@subsection platforms-android-troubleshooting-cant-launch App can't launch If your application can't launch (or it just blinks and then disappears), you can inspect @cb{.sh} adb logcat @ce output to see what went wrong, but be @@ -260,8 +431,14 @@ quick, the log is spitting out a lot of info all the time. Possible causes: - Mismatch between actual library name and library referenced from `AndroidManifest.xml`, causing Java to fail loading it -- The device having an ABI for which the app was not compiled (check the - @cb{.gradle} abiFilters @ce option in `build.gradle`) +- The device has an ABI for which the app was not compiled (check the + @cb{.gradle} abiFilters @ce option in `build.gradle`) or the app was + compiled with SDK version that's not supported by the device yet. See the + [official API level documentation](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) + for more information. +- The device doesn't support OpenGL ES 3.0 yet. Rebuild Magnum and its + dependencies with the `TARGET_GLES2` option enabled. See @ref building-features + for more information. - Loading fails with `ANativeActivity_onCreate` symbol not being found. If you are using @ref Platform::AndroidApplication, this issue should be prevented, otherwise you need to add `-u ANativeActivity_onCreate` to your @@ -276,8 +453,19 @@ quick, the log is spitting out a lot of info all the time. Possible causes: @subsection platforms-android-troubleshooting-term Gradle aborting due to termcap -Gradle is crashing in case @cb{.sh} $TERM @ce is set to `xterm-256color` or -`xterm-24`. Solution is to set @cb{.sh} TERM=xterm @ce. See +If you see the following output, Gradle is crashing because @cb{.sh} $TERM @ce +is set to `xterm-256color` or `xterm-24`: + +@code{.shell-session} +$ gradle build + +FAILURE: Build failed with an exception. + +* What went wrong: +Could not open terminal for stdout: could not get termcap entry +@endcode + +Solution is to set @cb{.sh} TERM=xterm @ce. See [gradle/gradle#4440](https://github.com/gradle/gradle/issues/4440) for more information. @@ -315,4 +503,5 @@ directory permissions such as it's often enough to just install such packages. In case of ArchLinux, all relevant packages are available in AUR. */ + } diff --git a/doc/platforms-gl.dox b/doc/platforms-gl.dox new file mode 100644 index 000000000..bf6f4bec7 --- /dev/null +++ b/doc/platforms-gl.dox @@ -0,0 +1,87 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-gl OpenGL and OpenGL ES platforms +@brief Information common for all platforms that support OpenGL and OpenGL ES + +@tableofcontents +@m_footernavigation + +@todoc desktop gles + +@section platforms-gl-best-practices OpenGL best practices + +Various links gathered around the web: + +- [Performance tuning applications for Intel Graphics for Linux and Chrome OS](http://software.intel.com/sites/default/files/Performance-tuning-applications-for-Intel-GEN-Graphics-for-Linux-and-Google-Chrome-OS.pdf) [PDF] +- [PowerVR Performance Recommendations](https://github.com/burningsun/pecker_framework/blob/master/参考资料/PowerVR.Performance%20Recommendations.pdf?raw=true) [PDF] +- [ATI Radeon HD 2000 programming guide](http://developer.amd.com/wordpress/media/2012/10/ATI_Radeon_HD_2000_programming_guide.pdf) [PDF] + +@section platforms-gl-es OpenGL ES + +@subsection platforms-gl-es-best-practices OpenGL ES best practices + +Various links gathered around the web: + +- [Writing Portable OpenGL ES 2.0](https://www.khronos.org/assets/uploads/developers/library/2011-siggraph-mobile/Writing-Portable-OpenGL-ES-2.0_Aug-11.pdf) [PDF] +- [Optimize OpenGL ES 2.0 Performance for Tegra](http://docs.nvidia.com/tegra/index.html#GLES2_Perf_Main.html) + +@subsection platforms-gl-es-differences Differences to desktop GL + +- Rendering to RGB textures doesn't work on many platforms, either due to + alignment issues or other factors. For example it is not possible to render + to @ref TextureFormat::RGB8 on iOS (but it works elsewhere); rendering to + @ref TextureFormat::RGB32F is not possible even on NVidia. Use RGBA formats + instead. +- While on desktop GL it's often permitted to upload a RGB image to a texture + with RGBA internal format, on mobile devices usually nothing happens. Be + sure to match the component count. +- Rendering to 16- and 32-bit float textures is only possible with OpenGL ES + 3.2 or with the @extension{EXT,color_buffer_half_float} and + @extension{EXT,color_buffer_float} extensions. You can work around that + issue by rendering to 32-bit unsigned integer textures and using the + @glsl floatBitsToUInt() @ce GLSL function instead. +- Linear filtering on 32-bit float textures is only possible with + @extension{OES,texture_float_linear} (it's not even on ES 3.2 yet). You can + work around that issue by using half-float texture formats or doing the + interpolation manually in a shader. + +@subsection platforms-gl-es-angle ANGLE + +[ANGLE](https://github.com/google/angle) is a layer that translates OpenGL ES +code to D3D, desktop GL or Vulkan, originally created for web browsers to +provide better WebGL experience without relying on buggy OpenGL drivers on +Windows. + +Related links: + +- [WebGL Insights --- ANGLE](https://books.google.cz/books?id=6crECQAAQBAJ&lpg=PP1&pg=PA3&redir_esc=y#v=onepage&q&f=true) + +*/ + +} + diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox new file mode 100644 index 000000000..da52612e1 --- /dev/null +++ b/doc/platforms-html5.dox @@ -0,0 +1,117 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-html5 HTML5 and WebGL +@brief Building, testing and deploying HTML5 and WebGL projects + +@tableofcontents +@m_footernavigation + +@todoc move stuff from Sdl2App and WindowlessEglApp +@todoc explain the css and js file, command-line args +@todoc testing, gl tests, coverage, travis setup +@todoc static plugins + +The following guide explains basic workflow of using +[Emscripten](http://kripken.github.io/emscripten-site/) for deploying HTML5 +apps using WebGL. + +See also @ref Platform::Sdl2Application for more information. + +@section platforms-html5-webgl Differences between WebGL and OpenGL ES + +WebGL is subset of OpenGL ES with some specific restrictions, namely +requirement for unique buffer target binding, aligned buffer offset and +stride and some other restrictions. The most prominent difference is that while +the following was enough on desktop: + +@snippet Magnum.cpp Buffer-webgl-nope + +On WebGL (even 2.0) you always have to initialize the buffers like this (and +other target hints for UBOs etc.): + +@snippet Magnum.cpp Buffer-webgl + +See @ref Buffer-webgl-restrictions "Buffer", @ref Mesh-webgl-restrictions "Mesh", +@ref Texture::setSubImage() "*Texture::setSubImage()", +@ref Mesh::addVertexBuffer(), @ref Renderer::setStencilFunction(), +@ref Renderer::setStencilMask() and @ref Renderer::setBlendFunction() +documentation for more information. The corresponding sections in official +WebGL specification provide even more detail: + +- [Differences Between WebGL and OpenGL ES 2.0](http://www.khronos.org/registry/webgl/specs/latest/1.0/#6) +- [Differences Between WebGL and OpenGL ES 3.0](https://www.khronos.org/registry/webgl/specs/latest/2.0/#5) + +@section platforms-html5-troubleshooting Troubleshooting + +@subsection platforms-html5-troubleshooting-bootstrap First Emscripten run takes long or fails + +Emscripten downloads and builds a lot of things on first startup or after +upgrade. That's expected and might take quite some time. If you are calling +Emscripten through the CMake toolchain, it might be attempting to bootstrap +itself multiple times, taking extreme amounts of time, or even fail during the +initial CMake compiler checks for various reasons such as + +@code{.shell-session} + File "/usr/lib/python2.7/subprocess.py", line 1025, in _execute_child + raise child_exception + OSError: [Errno 13] Permission denied +@endcode + +The CMake toolchain might interfere with the bootstrap operation, causing it to +fail. Solution is to wipe all Emscripten caches and trigger a rebuild of all +needed libraries by compiling a minimal project. The @cb{.sh} -s WASM=1 @ce +flag is needed in order to enable a rebuild of the `binaryen` tool as well: + +@code{.sh} +emcc --clear-cache +emcc --clear-ports +echo "int main() {}" > main.cpp +em++ -s WASM=1 main.cpp +@endcode + +@subsection platforms-html5-troubleshooting-corrade-not-found CMake can't find _CORRADE_MODULE_DIR + +If initial CMake configuration fails with + +@code{.shell-session} + Could NOT find Corrade (missing: _CORRADE_MODULE_DIR) +@endcode + +The solution is to explicitly pass `CMAKE_PREFIX_PATH` pointing to directory +where Corrade is installed, for example: + +@code{.sh} +mkdir build-emscripten && cd build-emscripte +cmake .. \ + -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/Emscripten-wasm.cmake \ + -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system/ \ + -G Ninja +@endcode +*/ + +} diff --git a/doc/platforms-ios.dox b/doc/platforms-ios.dox new file mode 100644 index 000000000..671d7cced --- /dev/null +++ b/doc/platforms-ios.dox @@ -0,0 +1,61 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-ios iOS +@brief Building, testing and deploying apps for Apple iOS platforms + +@tableofcontents +@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). + +See also @ref Platform::Sdl2Application for more information. + +@section platforms-ios-best-practices Best practices + +Official Apple documentation: + +- [Best Practices for Working with Vertex Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html) +- [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html) +- [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3) + +@section platforms-ios-troubleshooting Troubleshooting + +- GLSL @glsl texelFetch() @ce returns zero results if you have a texture with + integer type and the filtering is not @ref Sampler::Filter::Nearest. Yes, + it shouldn't matter, but it does. + +@todoc CMake -G Xcode, testsuite integration, bundling, controlling xcode properties from cmake +@todoc CORRADE_TESTSUITE_BUNDLE_IDENTIFIER_PREFIX +@todoc alternatives - including *.a files manually in your xcode project +@todoc move stuff from Sdl2App +@todoc static plugins +@todoc travis setup +*/ + +} diff --git a/doc/platforms-linux.dox b/doc/platforms-linux.dox new file mode 100644 index 000000000..a6e72f86f --- /dev/null +++ b/doc/platforms-linux.dox @@ -0,0 +1,39 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-linux Linux +@brief Tips and tricks for Linux platforms + +@tableofcontents +@m_footernavigation + +@todoc packages +@todoc desktop ES +@todoc tests, mesa softpipe +*/ + +} diff --git a/doc/platforms-macos.dox b/doc/platforms-macos.dox new file mode 100644 index 000000000..6adce7e08 --- /dev/null +++ b/doc/platforms-macos.dox @@ -0,0 +1,59 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-macos macOS +@brief Tips and tricks for macOS + +@tableofcontents +@m_footernavigation + +@todoc homebrew +@todoc travis setup +@todoc bundling, dmg cpack + +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). + +@section platforms-macos-opengl-best-practices Best practices + +Official Apple documentation: + +- [Best Practices for Working with Vertex Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_vertexdata/opengl_vertexdata.html) +- [Best Practices for Working with Texture Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_texturedata/opengl_texturedata.html) + +@section platforms-macos-troubleshooting Troubleshooting + +- @ref AbstractShaderProgram::validate() expects that the shader has a + properly configured framebuffer bound along with proper @ref Renderer + setup. That is often hard to achieve, so the function cannot be portably + used for shader validity testing. +- `GL_TIMESTAMP` used by @ref TimeQuery::timestamp() is not implemented on + macOS and gives zero results. + +*/ + +} diff --git a/doc/platforms-windows.dox b/doc/platforms-windows.dox new file mode 100644 index 000000000..08ade06b5 --- /dev/null +++ b/doc/platforms-windows.dox @@ -0,0 +1,44 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { + +/** @page platforms-windows Windows +@brief Tips and tricks for Windows platforms + +@tableofcontents +@m_footernavigation + +See @ref Platform::Sdl2Application for more information about WinRT. + +@todoc DLL paths +@todoc vcpkg +@todoc desktop ES +@todoc mingw, clang, clang/c2... +@todoc "unicode" +@todoc colored console output +*/ + +} diff --git a/doc/platforms.dox b/doc/platforms.dox index 349cf1fbd..d7dd8089e 100644 --- a/doc/platforms.dox +++ b/doc/platforms.dox @@ -28,7 +28,13 @@ namespace Magnum { /** @page platforms Platform-specific guides @brief General information, tips and troubleshooting for particular platforms -- @subpage platforms-android --- @copybrief android +- @subpage platforms-gl --- @copybrief platforms-gl +- @subpage platforms-linux --- @copybrief platforms-linux +- @subpage platforms-windows --- @copybrief platforms-windows +- @subpage platforms-macos --- @copybrief platforms-macos +- @subpage platforms-ios --- @copybrief platforms-ios +- @subpage platforms-android --- @copybrief platforms-android +- @subpage platforms-html5 --- @copybrief platforms-html5 */ diff --git a/doc/snippets/Magnum.cpp b/doc/snippets/Magnum.cpp index 138753cb4..9edf33929 100644 --- a/doc/snippets/Magnum.cpp +++ b/doc/snippets/Magnum.cpp @@ -376,10 +376,16 @@ CORRADE_INTERNAL_ASSERT_OUTPUT(buffer.unmap()); } #endif +{ +/* [Buffer-webgl-nope] */ +Buffer vertices, indices; +/* [Buffer-webgl-nope] */ +} + { /* [Buffer-webgl] */ -Buffer vertices{Buffer::TargetHint::Array}; -Buffer indices{Buffer::TargetHint::ElementArray}; +Buffer vertices{Buffer::TargetHint::Array}, + indices{Buffer::TargetHint::ElementArray}; /* [Buffer-webgl] */ } diff --git a/doc/tips.dox b/doc/tips.dox index c3279f5ce..ec248c227 100644 --- a/doc/tips.dox +++ b/doc/tips.dox @@ -29,7 +29,6 @@ namespace Magnum { - @subpage method-chaining --- @copybrief method-chaining - @subpage portability --- @copybrief portability -- @subpage best-practices --- @copybrief best-practices - @subpage compilation-speedup --- @copybrief compilation-speedup - @subpage troubleshooting --- @copybrief troubleshooting diff --git a/src/Magnum/Buffer.h b/src/Magnum/Buffer.h index 00099c1cf..c5afc43ed 100644 --- a/src/Magnum/Buffer.h +++ b/src/Magnum/Buffer.h @@ -180,13 +180,19 @@ Buffers in @ref MAGNUM_TARGET_WEBGL "WebGL" need to be bound only to one unique target, i.e., @ref Buffer bound to @ref Buffer::TargetHint::Array cannot be later rebound to @ref Buffer::TargetHint::ElementArray. However, Magnum by default uses any sufficient target when binding the buffer internally (e.g. for -setting data). To avoid GL errors, set target hint to desired target, either in -constructor or using @ref Buffer::setTargetHint(): +setting data). To avoid GL errors, the following, while completely fine on +desktop, is not sufficient on WebGL: + +@snippet Magnum.cpp Buffer-webgl-nope + +You have to set target hint to desired target, either in constructor or using +@ref Buffer::setTargetHint() like this (and similarly for other bufffer types +such as UBOs): @snippet Magnum.cpp Buffer-webgl -To ease up the development, @ref Mesh checks proper target hint when adding -vertex and index buffers in WebGL. +To simplify debugging, @ref Mesh checks proper target hint when adding vertex +and index buffers in WebGL. @section Buffer-performance-optimizations Performance optimizations