From a7ac8ea6fc1e77ea09fb8161ec9285e1a5328e96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 29 Nov 2020 18:04:21 +0100 Subject: [PATCH] doc: add info about adding new Vulkan versions / extensions. --- doc/developers.dox | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/doc/developers.dox b/doc/developers.dox index 8d92b6692..6e8563020 100644 --- a/doc/developers.dox +++ b/doc/developers.dox @@ -729,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",