From ef0113f55813b9bad74863693a6af73c16fa97c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 17 Dec 2020 15:10:18 +0100 Subject: [PATCH] doc: introduce \requires_vk_feature, add useful info to the group pages. --- doc/Doxyfile | 3 ++- doc/Doxyfile-mcss | 3 ++- doc/Doxyfile-public | 3 ++- doc/coding-style.dox | 3 ++- doc/vulkan.dox | 48 ++++++++++++++++++++++++++++++++++---------- 5 files changed, 45 insertions(+), 15 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index bdcab4f62..f560d9702 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -305,7 +305,8 @@ ALIASES = \ "def_vk{1}=VK_\1" \ "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\"" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring a specific Vulkan extension\"" \ + "requires_vk_feature=@xrefitem requires-vk-feature \"Requires Vulkan feature\" \"Functionality requiring a specific Vulkan feature\"" \ "vk_extension{2}= \1_\2" \ "fn_al{1}=`al\1()`" \ "fn_alc{1}=`alc\1()`" \ diff --git a/doc/Doxyfile-mcss b/doc/Doxyfile-mcss index fdfda237a..9ad0c567d 100644 --- a/doc/Doxyfile-mcss +++ b/doc/Doxyfile-mcss @@ -62,7 +62,8 @@ ALIASES = \ "def_vk{1}=@m_class{m-doc-external} VK_\1" \ "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\"" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring a specific Vulkan extension\"" \ + "requires_vk_feature=@xrefitem requires-vk-feature \"Requires Vulkan feature\" \"Functionality requiring a specific Vulkan feature\"" \ "vk_extension{2}=@m_class{m-doc-external} \1_\2" \ "fn_al{1}=@m_class{m-doc-external} al\1()" \ "fn_alc{1}=@m_class{m-doc-external} alc\1()" \ diff --git a/doc/Doxyfile-public b/doc/Doxyfile-public index 4460f654f..e811b6338 100644 --- a/doc/Doxyfile-public +++ b/doc/Doxyfile-public @@ -58,7 +58,8 @@ ALIASES = \ "def_vk{1}=@m_class{m-doc-external} VK_\1" \ "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\"" \ + "requires_vk_extension=@xrefitem requires-vk-extension \"Requires Vulkan extension\" \"Functionality requiring a specific Vulkan extension\"" \ + "requires_vk_feature=@xrefitem requires-vk-feature \"Requires Vulkan feature\" \"Functionality requiring a specific Vulkan feature\"" \ "vk_extension{2}=@m_class{m-doc-external} \1_\2" \ "fn_al{1}=@m_class{m-doc-external} al\1()" \ "fn_alc{1}=@m_class{m-doc-external} alc\1()" \ diff --git a/doc/coding-style.dox b/doc/coding-style.dox index 556b3ccdc..3066a1221 100644 --- a/doc/coding-style.dox +++ b/doc/coding-style.dox @@ -253,7 +253,8 @@ for specific extensions not part of the core OpenGL ES specification and WebGL specification. When there is more than just a single platform, first come desktop requirements, then ES requirements and WebGL requirements last. -For Vulkan, the command is @c \@requires_vk_extension: +For Vulkan, the command is @c \@requires_vkXX, @c \@requires_vk_extension, and +because Vulkan contain feature bits, also @c \@requires_vk_feature. @snippet coding-style.h requires_vk_extension diff --git a/doc/vulkan.dox b/doc/vulkan.dox index 5416fd05e..d0c8eb79f 100644 --- a/doc/vulkan.dox +++ b/doc/vulkan.dox @@ -55,22 +55,48 @@ is usually supported everywhere, even if the drivers don't have Vulkan 1.2). - @subpage requires-vk11 - @subpage requires-vk12 - @subpage requires-vk-extension +- @subpage requires-vk-feature */ /** @page requires-vk11 Functionality requiring Vulkan 1.1 - * @m_footernavigation - * @m_since_latest - */ +@m_footernavigation +@m_since_latest + +APIs listed here require a particular Vulkan version to be supported by the +instance / device or, if specified, an extension to be supported and enabled on +the instance / device using @ref Vk::InstanceCreateInfo::addEnabledExtensions() +/ @ref Vk::DeviceCreateInfo::addEnabledExtensions(). +*/ /** @page requires-vk12 Functionality requiring Vulkan 1.2 - * @m_footernavigation - * @m_since_latest - */ - -/** @page requires-vk-extension Functionality requiring specific Vulkan extension - * @m_footernavigation - * @m_since_latest - */ +@m_footernavigation +@m_since_latest + +APIs listed here require a particular Vulkan version to be supported by the +instance / device or, if specified, an extension to be supported and enabled on +the instance / device using @ref Vk::InstanceCreateInfo::addEnabledExtensions() +/ @ref Vk::DeviceCreateInfo::addEnabledExtensions(). +*/ + +/** @page requires-vk-extension Functionality requiring a specific Vulkan extension +@m_footernavigation +@m_since_latest + +APIs listed here require a Vulkan extension to be supported and enabled on the +instance / device using @ref Vk::InstanceCreateInfo::addEnabledExtensions() / +@ref Vk::DeviceCreateInfo::addEnabledExtensions(). +*/ + +/** +@page requires-vk-feature Functionality requiring a specific Vulkan feature +@m_footernavigation +@m_since_latest + +APIs listed here require a Vulkan feature to be supported and enabled on the +device using @ref Vk::DeviceCreateInfo::setEnabledFeatures(). Note that some +features are coming from extensions and thus require also the corresponding +extension to be enabled. +*/ }