Bootstrapping Vulkan support

CMakeLists.txt

@@ -77,6 +77,9 @@ option(WITH_SHADERCONVERTER "Build magnum-shaderconverter utility" OFF)
 # Magnum AL Info
 option(WITH_AL_INFO "Build magnum-al-info utility" OFF)
 
+# Magnum Vk Info
+option(WITH_VK_INFO "Build magnum-vk-info utility" OFF)
+
 # Plugins
 option(WITH_ANYIMAGEIMPORTER "Build AnyImageImporter plugin" OFF)
 option(WITH_ANYAUDIOIMPORTER "Build AnyAudioImporter plugin" OFF)
@@ -113,7 +116,7 @@ option(WITH_EGLCONTEXT "Build EglContext library" OFF)
 
 # Vulkan, everywhere except Emscripten
 if(NOT CORRADE_TARGET_EMSCRIPTEN)
-    option(WITH_VK "Build Vk library" OFF)
+    cmake_dependent_option(WITH_VK "Build Vk library" OFF "NOT WITH_VK_INFO" ON)
     cmake_dependent_option(TARGET_VK "Build libraries with Vulkan interoperability" ON "WITH_VK" OFF)
 endif()
 
@@ -198,6 +201,7 @@ option(BUILD_PLUGINS_STATIC "Build static plugins (default are dynamic)" OFF)
 option(BUILD_TESTS "Build unit tests" OFF)
 cmake_dependent_option(BUILD_GL_TESTS "Build unit tests for OpenGL code" OFF "BUILD_TESTS;TARGET_GL" OFF)
 cmake_dependent_option(BUILD_AL_TESTS "Build unit tests for OpenAL code" ON "BUILD_TESTS;WITH_AUDIO" OFF)
+cmake_dependent_option(BUILD_VK_TESTS "Build unit tests for Vulkan code" OFF "BUILD_TESTS;TARGET_VK" OFF)
 if(BUILD_TESTS)
     find_package(Corrade REQUIRED TestSuite)
     if(CORRADE_TARGET_IOS)
@@ -213,8 +217,10 @@ if(BUILD_TESTS)
     endif()
 endif()
 
-# OpenGLTester library, built by default only if GL tests are enabled
+# OpenGLTester / VulkanTester libraries, built by default only if GL / VK tests
+# are enabled
 cmake_dependent_option(WITH_OPENGLTESTER "Build OpenGLTester library" OFF "NOT BUILD_GL_TESTS" ON)
+cmake_dependent_option(WITH_VULKANTESTER "Build VulkanTester library" OFF "NOT BUILD_VK_TESTS" ON)
 
 # Dynamic linking is meaningless on Emscripten and too inconvenient on Android
 if(CORRADE_TARGET_EMSCRIPTEN OR CORRADE_TARGET_ANDROID)

doc/Doxyfile

@@ -303,6 +303,8 @@ ALIASES                = \
     "type_vk{1}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\1.html\">Vk\1</a>" \
     "val_vk{2}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\2.html\">VK_\1</a>" \
     "def_vk{1}=<a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1.html\">VK_\1</a>" \
+    "requires_vk11=@xrefitem requires-vk11 \"Requires Vulkan 1.1\" \"Functionality requiring Vulkan 1.1\"" \
+    "requires_vk12=@xrefitem requires-vk12 \"Requires Vulkan 1.2\" \"Functionality requiring Vulkan 1.2\"" \
     "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
     "vk_extension{2}= <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1_\2.html\">\1_\2</a>" \
     "fn_al{1}=`al\1()`" \
@@ -925,6 +927,7 @@ INPUT                  = ../src/Magnum \
                          ../src/Magnum/Text/fontconverter.cpp \
                          ../src/Magnum/TextureTools/distancefieldconverter.cpp \
                          ../src/Magnum/Trade/imageconverter.cpp \
+                         ../src/Magnum/Vk/vk-info.cpp \
                          . \
                          ../../magnum-plugins/src/Magnum \
                          ../../magnum-plugins/src/MagnumPlugins \
@@ -2253,7 +2256,7 @@ PREDEFINED             = DOXYGEN_GENERATING_OUTPUT \
     CORRADE_VISIBILITY_LOCAL= CORRADE_VISIBILITY_IMPORT= \
     CORRADE_IGNORE_DEPRECATED_PUSH= CORRADE_IGNORE_DEPRECATED_POP= \
     CORRADE_ENUMSET_OPERATORS(message)= MAGNUM_BUILD_DEPRECATED \
-    MAGNUM_TARGET_GL
+    MAGNUM_TARGET_GL MAGNUM_TARGET_VK
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doc/Doxyfile-mcss

@@ -60,6 +60,8 @@ ALIASES                = \
     "type_vk{1}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\1.html\">Vk\1</a>" \
     "val_vk{2}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\2.html\">VK_\1</a>" \
     "def_vk{1}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1.html\">VK_\1</a>" \
+    "requires_vk11=@xrefitem requires-vk11 \"Requires Vulkan 1.1\" \"Functionality requiring Vulkan 1.1\"" \
+    "requires_vk12=@xrefitem requires-vk12 \"Requires Vulkan 1.2\" \"Functionality requiring Vulkan 1.2\"" \
     "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
     "vk_extension{2}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1_\2.html\">\1_\2</a>" \
     "fn_al{1}=@m_class{m-doc-external} <a href=\"https://github.com/kcat/openal-soft/wiki/Programmer's-Guide#al\1\">al\1()</a>" \

doc/Doxyfile-public

@@ -56,6 +56,8 @@ ALIASES                = \
     "type_vk{1}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\1.html\">Vk\1</a>" \
     "val_vk{2}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/Vk\2.html\">VK_\1</a>" \
     "def_vk{1}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1.html\">VK_\1</a>" \
+    "requires_vk11=@xrefitem requires-vk11 \"Requires Vulkan 1.1\" \"Functionality requiring Vulkan 1.1\"" \
+    "requires_vk12=@xrefitem requires-vk12 \"Requires Vulkan 1.2\" \"Functionality requiring Vulkan 1.2\"" \
     "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring specific Vulkan extension\"" \
     "vk_extension{2}=@m_class{m-doc-external} <a href=\"https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_\1_\2.html\">\1_\2</a>" \
     "fn_al{1}=@m_class{m-doc-external} <a href=\"https://github.com/kcat/openal-soft/wiki/Programmer's-Guide#al\1\">al\1()</a>" \

doc/building.dox

@@ -565,6 +565,8 @@ code:
 -   `WITH_OPENGLTESTER` --- The @ref GL::OpenGLTester class. Requires
     `TARGET_GL` to be enabled; enables building of one of the windowless
     application libraries based on the target platform.
+-   `WITH_VULKANTESTER` --- The @ref Vk::VulkanTester class. Requires
+    `TARGET_VK` to be enabled.
 
 Magnum also contains a set of dependency-less plugins for importing essential
 file formats. Additional plugins are provided in a separate plugin repository,
@@ -608,6 +610,10 @@ There are also a few command-line utilities, also all disabled by default:
     executable, which provides information about the engine OpenGL
     capabilities. Requires `TARGET_GL` to be enabled; enables building of one
     of the windowless application libraries based on the target platform.
+-   `WITH_VK_INFO` --- Build the @ref magnum-vk-info "magnum-vk-info"
+    executable, which provides information about the engine Vulkan
+    capabilities. Requires `TARGET_VK` to be enabled; enables building of the
+    @ref Vk library.
 -   `WITH_AL_INFO` --- Build the @ref magnum-al-info "magnum-al-info"
     executable, which provides information about the engine OpenAL
     capabilities.
@@ -760,6 +766,9 @@ running CTest, e.g.:
 ctest -R GLTest # run only tests requiring OpenGL context
 @endcode
 
+Tests requiring Vulkan to work are also disabled by default, enable them with
+`BUILD_VK_TESTS`.
+
 @section building-doc Building documentation
 
 The documentation is generated using [Doxygen](http://doxygen.org) with the

doc/changelog.dox

@@ -40,6 +40,8 @@ See also:
 
 @subsection changelog-latest-new New features
 
+-   New @ref NoAllocate constructor tag, to be used by the @ref Vk library
+
 @subsubsection changelog-latest-new-debugtools DebugTools library
 
 -   Added @ref DebugTools::ColorMap::coolWarmSmooth() and
@@ -137,6 +139,26 @@ See also:
 -   @ref Trade::LightData got extended to support light attenuation and range
     parameters as well and spot light inner and outer angle
 
+@subsubsection changelog-latest-new-vk Vk library
+
+-   Boostrapping Vulkan support ([mosra/magnum#234](https://github.com/mosra/magnum/pull/234)), in particular:
+    -   @ref Vk::LayerProperties, @ref Vk::InstanceExtensionProperties and
+        @ref Vk::enumerateInstanceVersion() APIs for querying instance-level
+        properties
+    -   @ref Vk::DeviceProperties and @ref Vk::ExtensionProperties for querying
+        device-level properties
+    -   @ref Vk::Instance and @ref Vk::Device APIs for instance and device
+        creation and fetching instance/device-specific function pointers,
+        @ref Vk::Queue setup
+    -   @ref Vk::CommandPool and @ref Vk::CommandBuffer wrappers
+    -   Initial implementations of @ref Vk::Memory, @ref Vk::Buffer and
+        @ref Vk::Image
+    -   @ref Vk::Shader wrapper
+    -   New @ref magnum-vk-info "magnum-vk-info" utility, a Vulkan-specific
+        counterpart for @ref magnum-gl-info "magnum-gl-info"
+    -   @ref vulkan "Initial documentation", in particular @ref vulkan-support,
+        @ref vulkan-wrapping and @ref vulkan-mapping
+
 @subsection changelog-latest-changes Changes and improvements
 
 @subsubsection changelog-latest-changes-gl GL library
@@ -191,6 +213,11 @@ See also:
 -   @ref magnum-imageconverter "magnum-imageconverter" has a new `--in-place`
     option for converting images in-place
 
+@subsubsection changelog-latest-changes-vk Vk library
+
+-   @ref Vk::hasVkSamplerAddressMode() and @ref Vk::vkSamplerAddressMode() now
+    recognizes @ref SamplerWrapping::MirrorClampToEdge
+
 @subsection changelog-latest-buildsystem Build system
 
 -   Fixed compilation of the @ref GL library on macOS with ANGLE --- new code

doc/cmake.dox

@@ -231,6 +231,7 @@ There are also extensions to @ref Corrade::TestSuite::Tester for testing GPU
 code:
 
 -   `OpenGLTester` --- @ref GL::OpenGLTester class
+-   `VulkanTester` --- @ref Vk::VulkanTester class
 
 The library also contains a set of plugins for importing essential file
 formats. Additional plugins are provided in separate plugin repository, see
@@ -275,6 +276,7 @@ Lastly, a few utility executables are available:
 -   `shaderconverter` --- @ref magnum-shaderconverter "magnum-shaderconverter"
     executable
 -   `gl-info` --- @ref magnum-gl-info "magnum-gl-info" executable
+-   `vk-info` --- @ref magnum-vk-info "magnum-vk-info" executable
 -   `al-info` --- @ref magnum-al-info "magnum-al-info" executable
 
 Note that [each namespace](namespaces.html), all @ref Platform libraries and

doc/developers.dox

@@ -563,72 +563,56 @@ in inverse --- but usually @ref developers-deprecation "deprecate first".
 @section developers-gl-extensions Checklist for adding / removing GL versions and extensions
 
 1.  Install [flextGL](https://github.com/mosra/flextgl)
-2.  Go to `src/MagnumExternal/OpenGL/GL/`:
-    -   Update `extensions.txt` (bump a version or add/remove extensions)
-    -   Run @cb{.sh} .../flextGLgen.py -D . -t . extensions.txt @ce to generate
-        `flextGL.h`, `flextGL.cpp` and `flextGLPlatform.cpp` files
-3.  Go to `src/MagnumExternal/OpenGL/GLES2/`:
-    -   Update `extensions.txt` and `Emscripten/extensions.txt` (add/remove
+2.  Go to `src/MagnumExternal/OpenGL/`:
+    -   Update `GL/extensions.txt`, `GLES2/extensions.txt`,
+        `GLES2/Emscripten/extensions.txt`, `GLES3/extensions.txt`,
+        `GLES3/Emscripten/extensions.txt` (bump versions or add/remove
         extensions)
-    -   Run @cb{.sh} .../flextGLgen.py -D . -t . extensions.txt @ce to generate
-        `flextGL.h`, `flextGL.cpp`, `flextGLPlatform.cpp`,
-        `flextGLWindowsDesktop.h`, `flextGLWindowsDesktop.cpp`,
-        `flextGLPlatformWindowsDesktop.cpp` and `flextGLPlatformIOS.cpp` files.
-        Desktop GLES on Windows still links to the ancient `opengl32.dll`
-        which exports only OpenGL 1.1 symbols, so we have a special set of
-        headers that queries pointers for everything above OpenGL 1.1 (instead
-        of everything above OpenGL ES 2.0). iOS, on the other hand, doesn't
-        have any extension loader mechanism and all supported entrypoints are
-        exported from the library, so we set the function pointers to those
-        exported symbols in case the system GL header defines them.
-    -   Run @cb{.sh} .../flextGLgen.py -D . -t Emscripten/ Emscripten/extensions.txt @ce
-        to generate a stripped-down `flextGLEmscripten.h` file. Emscripten
-        doesn't have the ability to manually load extension pointers, thus it
-        has only header files.
-4.  Go to `src/MagnumExternal/OpenGL/GLES3/`:
-    -   Update `extensions.txt` and `Emscripten/extensions.txt` (bump a version
-        or add/remove extensions)
-    -   Run @cb{.sh} .../flextGLgen.py -D . -t . extensions.txt @ce to generate
-        `flextGL.h`, `flextGL.cpp`, `flextGLPlatform.cpp`,
-        `flextGLWindowsDesktop.h`, `flextGLWindowsDesktop.cpp`,
-        `flextGLPlatformWindowsDesktop.cpp` and `flextGLPlatformIOS.cpp` files.
-        See above why there are so many.
-    -   Run @cb{.sh} .../flextGLgen.py -D . -t Emscripten/ Emscripten/extensions.txt @ce
-        to generate a stripped-down `flextGLEmscripten.h` file. See above for
-        details.
-5.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
-6.  For every new added function, add an entry to `doc/opengl-mapping.dox`
-7.  For every new added limit query (various `GL_MIN_*` and `GL_MAX_*` macros
+    -   Run `./update-flextgl.sh` to update everything. Reason there is so many
+        variants of the files are the following:
+        -   Desktop GLES on Windows still links to the ancient `opengl32.dll`
+            which exports only OpenGL 1.1 symbols, so we have a special set of
+            headers that queries pointers for everything above OpenGL 1.1
+            (instead of everything above OpenGL ES 2.0).
+        -   iOS, on the other hand, doesn't have any extension loader mechanism
+            and all supported entrypoints are exported from the library, so we
+            set the function pointers to those exported symbols in case the
+            system GL header defines them.
+        -   Emscripten doesn't have the ability to manually load extension
+            pointers, thus it has only header files.
+3.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
+4.  For every new added function, add an entry to `doc/opengl-mapping.dox`
+5.  For every new added limit query (various `GL_MIN_*` and `GL_MAX_*` macros
     etc.), add an entry to the bottom of `doc/opengl-mapping.dox`
-8.  Add a table listing the new version and all new extensions in it to
+6.  Add a table listing the new version and all new extensions in it to
     `doc/opengl-support.dox` (take a list of them from the changelog in the
     official spec PDF). Some extensions might be already present in the general
     extension list, move them out of there.
-9.  Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` page
+7.  Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` page
     with @c \@m_footernavigation to `doc/opengl-support.dox`, mention it as a
     @c \@subpage at a correct position in the list
-10. Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` alias
+8.  Add a new `requires-glXY`, `requires-glesXY` or `requires-webglXY` alias
     to `Doxyfile`, `Doxyfile-mcss` and `Doxyfile-public`, copypaste it from
     existing and change the numbers
-11. Add new version enum value:
+9.  Add new version enum value:
     -   to `src/Magnum/GL/Version.h`
     -   to debug output in `src/Magnum/GL/Version.cpp`
     -   to @ref GL::Extension::extensions() in `src/Magnum/GL/Context.cpp`
     -   to @cpp GL::Context::tryCreate() @ce in `src/Magnum/GL/Context.cpp`
     -   to specify GLSL version in `src/Magnum/GL/Shader.cpp`
     -   to the list in `src/Magnum/Platform/gl-info.cpp`
     -   to the test in `src/Magnum/GL/Test/ContextTest.cpp`
-12. Add new extensions to `src/Magnum/GL/Extensions.h`
+10. Add new extensions to `src/Magnum/GL/Extensions.h`
     -   order them by extension ID that is mentioned in every extension spec
         file
     -   update the numbering to stay monotonic and unique, round up start index
         of next section to nearest ten to make the updates bearable
     -   in case there's a lot of new extensions, @cpp Implementation::ExtensionCount @ce
         might needed to be increased
     -   run `ContextTest` to verify everything is still okay
-13. Update existing extensions with version in which they become core (last
+11. Update existing extensions with version in which they become core (last
     parameter of the `_extension()` macro)
-14. Update extension list in `src/magnum/GL/Context.cpp` according to changes
+12. Update extension list in `src/magnum/GL/Context.cpp` according to changes
     in `src/Magnum/GL/Extensions.h`
 
 In order to remove GL functionality, be sure to touch all places mentioned
@@ -745,7 +729,42 @@ unless it doesn't affect public API at all.
 
 @section developers-vk-extensions Checklist for adding / removing Vulkan versions and extensions
 
-@todoc adapt from the GL section
+1.  Install [flextGL](https://github.com/mosra/flextgl)
+2.  Go to `src/MagnumExternal/Vulkan/`:
+    -   Update `extensions.txt` (bump a version or add/remove extensions)
+    -   Run `./update-flexgl.sh` to update everything
+3.  Check @cb{.sh} git diff @ce for suspicious changes and whitespace-at-EOL
+4.  For every new added function and `CreateInfo` structure, add an entry to
+    `doc/vulkan-mapping.dox`
+5.  Add a table listing the new version and all new extensions in it to
+    `doc/vulkan-support.dox` (take a list of them from the changelog in the
+    official spec PDF). Some extensions might be already present in the general
+    extension list, move them out of there.
+6.  Add a new `requires-vkXY` page with @c \@m_footernavigation to
+    `doc/vulkan-support.dox`, mention it as a @c \@subpage at a correct
+    position in the list
+7.  Add a new `requires-vkXY` alias to `Doxyfile`, `Doxyfile-mcss` and
+    `Doxyfile-public`, copypaste it from existing and change the numbers
+8.  Add new version enum value:
+    -   to `src/Magnum/Vk/Version.h`
+    -   to the list in `src/Magnum/Vk/vk-info.cpp`
+    -   to @ref Vk::InstanceExtension::extensions() and
+        @ref Vk::Extension::extensions() in `src/Magnum/Vk/Extensions.cpp`
+9.  Add new extensions to `src/Magnum/Vk/Extensions.h`
+    -   there's a separate list for instance and device extensions, ensure each
+        in the right list
+    -   order them by extension ID that is mentioned on every extension spec
+        page
+    -   update the numbering to stay monotonic and unique, round up start index
+        of next section to nearest ten to make the updates bearable
+    -   in case there's a lot of new extensions,
+        @cpp Implementation::InstanceExtensionCount @ce /
+        @cpp Implementation::DeviceExtensionCount @ce might needed to be
+        increased
+10. Add them alphabetically ordered to the correct list in
+    `src/Magnum/Vk/Extensions.cpp`
+11. Update existing extensions with version in which they become core (last
+    parameter of the `_extension()` macro)
 
 In order to remove Vulkan functionality, be sure to touch all places mentioned
 above, only in inverse --- but usually @ref developers-deprecation "deprecate first",

doc/features.dox

@@ -39,6 +39,7 @@ necessary to read through everything, pick only what you need.
 -   @subpage plugins --- @copybrief plugins
 -   @subpage file-formats --- @copybrief file-formats
 -   @subpage opengl-wrapping --- @copybrief opengl-wrapping
+-   @subpage vulkan-wrapping --- @copybrief vulkan-wrapping
 -   @subpage shaders --- @copybrief shaders
 -   @subpage scenegraph --- @copybrief scenegraph
 -   @subpage debug-tools --- @copybrief debug-tools