diff --git a/doc/platforms-macos.dox b/doc/platforms-macos.dox index 3194c9959..94d4d9a61 100644 --- a/doc/platforms-macos.dox +++ b/doc/platforms-macos.dox @@ -35,10 +35,6 @@ namespace Magnum { @todoc code coverage -With Apple decision to focus on Metal, macOS OpenGL support is stuck on version -4.1 (i.e., two versions before compute shaders are available). Moreover, OpenGL -is deprecated since macOS 10.14. - See also @ref platforms-ios. @section platforms-macos-bundle Bundle creation @@ -246,7 +242,33 @@ sudo rm -rf /Library/Developer/CommandLineTools sudo xcode-select --install @endcode -@subsection platforms-macos-troubleshooting-gl Mac-specific OpenGL behavior +@section platforms-macos-vulkan Vulkan on macOS + +Vulkan on macOS is implemented on top of Metal, and there are two possible +ways: + +- Using [MoltenVK](https://github.com/KhronosGroup/MoltenVK) directly. The + library can supplement a Vulkan loader as well, which means you don't need + two libraries, however this way you lose the possibility to have multiple + devices (for example a SwiftShader software rendering). MoltenVK is + directly available in Homebrew as `molten-vk`. +- Using [Vulkan Loader](https://github.com/KhronosGroup/Vulkan-Loader) + together with MoltenVK and possibly other device implementations. That way + you'll get the benefits of a standard loader and device selection. The + loader isn't available in Homebrew so you need to either install the whole + several-hunred-megabyte SDK or [build it from source](https://github.com/KhronosGroup/Vulkan-Loader/blob/master/BUILD.md#building-on-macos). + +Magnum's own [FindVulkan.cmake](https://github.com/mosra/magnum/blob/master/modules/FindVulkan.cmake) +will look for the Vulkan Loader first and if not found, falls back to searching +for MoltenVK. + +@section platforms-macos-gl OpenGL on macOS + +With Apple decision to focus on Metal, macOS OpenGL support is stuck on version +4.1 (i.e., two versions before compute shaders are available). Moreover, OpenGL +is deprecated since macOS 10.14. + +These are known macOS-specific OpenGL issues: - @ref GL::AbstractShaderProgram::validate() expects that the shader has a properly configured framebuffer bound along with proper @ref GL::Renderer diff --git a/doc/platforms-vk.dox b/doc/platforms-vk.dox new file mode 100644 index 000000000..ba6d7235b --- /dev/null +++ b/doc/platforms-vk.dox @@ -0,0 +1,100 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, + 2020, 2021 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-vk Vulkan platforms +@brief Information common for all platforms with Vulkan support + +@tableofcontents +@m_footernavigation + +See also @ref platforms-macos-vulkan. + +@section platforms-vk-sdk Do I need the Vulkan SDK? + +A common misconception is that one *needs* the huge several-hundred-megabyte +[LunarG SDK](https://vulkan.lunarg.com/sdk/home) in order to use Vulkan. No, +not necessarily. Magnum has its own standalone Vulkan headers, so the only +thing needed is the actual Vulkan loader library: + +- On Linux distributions it's a system package (`libvulkan-dev` on Ubuntu, + `vulkan-icd-loader` on ArchLinux) +- On macOS easiest is to get MoltenVK (`molten-vk` in Homebrew), but + @ref platforms-macos-vulkan "using the loader is also possible" +- On Windows you can either [build the loader yourself](https://github.com/KhronosGroup/Vulkan-Loader/blob/master/BUILD.md#building-on-windows), + get it as a package from MinGW, or you have to install the SDK, sorry. + +Apart from the loader library, the SDK contains also various layers, +extra tools and shader compilers. While layers are useful for validation and +shader compiler libraries can be useful for building the +@ref ShaderTools::GlslangConverter "GlslangShaderConverter" and +@ref ShaderTools::SpirvToolsConverter "SpirvToolsShaderConverter" plugins, +these are commonly available in package managers as well: + +- Validation layers are `vulkan-validationlayers` on Ubuntu and + `vulkan-validation-layers` on ArchLinux. On macOS you'll need to either + build them yourself or get the SDK, Homebrew provides neither the loader + (to have the layers loadable) nor the layers. Same on Windows. +- For shader compilers, on Ubuntu, ArchLinux, Homebrew, Vcpkg and MinGW you + can get the `glslang` and `spirv-tools` packages +- The SDK additionally ships with the [shaderc](https://github.com/google/shaderc) + library that wraps Glslang and SPIRV-Tools in an arguably better interface, + but all its extra features, especially @cpp #include @ce support, are + provided by the @ref ShaderTools::GlslangConverter "GlslangShaderConverter" + and @ref ShaderTools::SpirvToolsConverter "SpirvToolsShaderConverter" + plugins already anyway. + +If you only need to build against *some* Vulkan library without running +anything (for example for CI compilation tests), the following is sufficient. +Build as a static library and supply to CMake via `Vulkan_LIBRARY`: + +@include libvulkan.cpp + +@section platforms-vk-best-practices Vulkan best practices + +NVidia tutorials and tips: + +- [Engaging the Voyage to Vulkan](https://developer.nvidia.com/engaging-voyage-vulkan) +- [Vulkan Shader Resource Binding](https://developer.nvidia.com/vulkan-shader-resource-binding) +- [Vulkan Memory Management](https://developer.nvidia.com/vulkan-memory-management) +- [Transitioning from OpenGL to Vulkan](https://developer.nvidia.com/transitioning-opengl-vulkan) +- [OpenGL like Vulkan](https://developer.nvidia.com/opengl-vulkan) +- [What’s your Vulkan Memory Type?](https://developer.nvidia.com/what%E2%80%99s-your-vulkan-memory-type) +- [Tips and Tricks: Vulkan Dos and Don’ts](https://developer.nvidia.com/blog/vulkan-dos-donts/) +- [Vulkan Device Generated Commands](https://developer.nvidia.com/blog/new-vulkan-device-generated-commands/) + +ARM best practices: + +- [Vulkan Best Practice for Mobile Developers](https://github.com/ARM-software/vulkan_best_practice_for_mobile_developers) + +Various useful links: + +- [Yet another blog explaining Vulkan synchronization](http://themaister.net/blog/2019/08/14/yet-another-blog-explaining-vulkan-synchronization/) +- [Writing an efficient Vulkan renderer](https://zeux.io/2020/02/27/writing-an-efficient-vulkan-renderer/) + +*/ + +} diff --git a/doc/platforms.dox b/doc/platforms.dox index 1947f0d6c..c9a4303b7 100644 --- a/doc/platforms.dox +++ b/doc/platforms.dox @@ -28,6 +28,7 @@ namespace Magnum { /** @page platforms Platform-specific guides @brief General information, tips and troubleshooting for particular platforms +- @subpage platforms-vk --- @copybrief platforms-vk - @subpage platforms-gl --- @copybrief platforms-gl - @subpage platforms-linux --- @copybrief platforms-linux - @subpage platforms-windows --- @copybrief platforms-windows diff --git a/doc/snippets/libvulkan.cpp b/doc/snippets/libvulkan.cpp new file mode 120000 index 000000000..3c2623992 --- /dev/null +++ b/doc/snippets/libvulkan.cpp @@ -0,0 +1 @@ +../../package/ci/libvulkan.cpp \ No newline at end of file