From e22f73df3391f3339e05f57cbaf1701dcd1067f7 Mon Sep 17 00:00:00 2001 From: Stephan Seitz Date: Sat, 20 Jan 2024 16:51:46 +0100 Subject: [PATCH 1/3] docs: Add Doxygen configuration --- .gitmodules | 3 + Doxyfile | 58 ++++++++ docs/.gitignore | 2 + docs/RAII_Samples.dox | 256 +++++++++++++++++++++++++++++++++ docs/Samples.dox | 266 +++++++++++++++++++++++++++++++++++ docs/generate_samples_dox.py | 48 +++++++ docs/mainpage.dox | 10 ++ doxygen-awesome-css | 1 + 8 files changed, 644 insertions(+) create mode 100644 Doxyfile create mode 100644 docs/.gitignore create mode 100644 docs/RAII_Samples.dox create mode 100644 docs/Samples.dox create mode 100644 docs/generate_samples_dox.py create mode 100644 docs/mainpage.dox create mode 160000 doxygen-awesome-css diff --git a/.gitmodules b/.gitmodules index 68fd3dcee..06fc589bb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -13,3 +13,6 @@ [submodule "glfw"] path = glfw url = https://github.com/glfw/glfw +[submodule "doxygen-awesome-css"] + path = doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 000000000..9463baa96 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,58 @@ +PROJECT_NAME = Vulkan-Hpp +SEARCHENGINE = YES +GENERATE_TAGFILE = html/tagfile.xml # generate a tag file +DOT_IMAGE_FORMAT = svg +DOT_TRANSPARENT = YES +INTERACTIVE_SVG = YES +EXTRACT_ALL = YES +RECURSIVE = YES +INPUT = vulkan/vulkan.cppm \ +vulkan/vulkan.hpp \ +vulkan/vulkan_enums.hpp \ +vulkan/vulkan_extension_inspection.hpp \ +vulkan/vulkan_format_traits.hpp \ +vulkan/vulkan_funcs.hpp \ +vulkan/vulkan_hash.hpp \ +vulkan/vulkan_hpp_macros.hpp \ +vulkan/vulkan_to_string.hpp \ +vulkan/vulkan_handles.hpp \ +vulkan/vulkan_video.hpp \ +vulkan/vulkan_static_assertions.hpp \ +vulkan/vulkan_raii.hpp \ +vulkan/vulkan_structs.hpp \ +vulkan/vulkan_structs.hpp \ +Vulkan-Headers/include/vulkan/vulkan.h \ +Vulkan-Headers/include/vulkan/vulkan_core.h \ +Vulkan-Headers/include/vk_video \ +README.md \ +vk_raii_ProgrammingGuide.md \ +docs/mainpage.dox \ +docs/Samples.dox \ +docs/RAII_Samples.dox \ +samples +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXAMPLE_PATH = . samples + +PREDEFINED += VULKAN_HPP_NAMESPACE="vk" +PREDEFINED += VULKAN_HPP_RAII_NAMESPACE="raii" +PREDEFINED += VK_ENABLE_BETA_EXTENSIONS="1" + +EXCLUDE = vulkan/vulkan_shared.hpp vulkan/vulkansc_shared.hpp +#EXLUDE_PATTERNS = */vulkan/* +HAVE_DOT = NO +CLASS_GRAPH = NO +INHERIT_DOCS = NO +INCLUDE_PATH = include Vulkan-Headers/include/ +REFERENCES_LINK_SOURCE = YES +TEMPLATE_RELATIONS = YES +SOURCE_BROWSER = YES +REFERENCES_RELATION = NO +REFERENCED_BY_RELATION = NO + +GENERATE_TREEVIEW = YES +DISABLE_INDEX = NO +FULL_SIDEBAR = NO +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ + doxygen-awesome-css/doxygen-awesome-sidebar-only.css +HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..2ec816f3e --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +html +latex diff --git a/docs/RAII_Samples.dox b/docs/RAII_Samples.dox new file mode 100644 index 000000000..fa7057b4b --- /dev/null +++ b/docs/RAII_Samples.dox @@ -0,0 +1,256 @@ +/** +\cond +File generate using `python3 docs/generate_samples_dox.py -s RAII_Samples/ -o docs/RAII_Samples.dox` +\endcond +\page RAII_Samples RAII Samples +\subpage RAII_Samples_01_InitInstance + +\subpage RAII_Samples_02_EnumerateDevices + +\subpage RAII_Samples_03_InitDevice + +\subpage RAII_Samples_04_InitCommandBuffer + +\subpage RAII_Samples_05_InitSwapchain + +\subpage RAII_Samples_06_InitDepthBuffer + +\subpage RAII_Samples_07_InitUniformBuffer + +\subpage RAII_Samples_08_InitPipelineLayout + +\subpage RAII_Samples_09_InitDescriptorSet + +\subpage RAII_Samples_10_InitRenderPass + +\subpage RAII_Samples_11_InitShaders + +\subpage RAII_Samples_12_InitFrameBuffers + +\subpage RAII_Samples_13_InitVertexBuffer + +\subpage RAII_Samples_14_InitPipeline + +\subpage RAII_Samples_15_DrawCube + +\subpage RAII_Samples_16_Vulkan_1_1 + +\subpage RAII_Samples_CopyBlitImage + +\subpage RAII_Samples_CreateDebugUtilsMessenger + +\subpage RAII_Samples_DebugUtilsObjectName + +\subpage RAII_Samples_DrawTexturedCube + +\subpage RAII_Samples_DynamicUniform + +\subpage RAII_Samples_EnableValidationWithCallback + +\subpage RAII_Samples_EnumerateDevicesAdvanced + +\subpage RAII_Samples_Events + +\subpage RAII_Samples_ImmutableSampler + +\subpage RAII_Samples_InitTexture + +\subpage RAII_Samples_InputAttachment + +\subpage RAII_Samples_InstanceExtensionProperties + +\subpage RAII_Samples_InstanceLayerExtensionProperties + +\subpage RAII_Samples_InstanceLayerProperties + +\subpage RAII_Samples_InstanceVersion + +\subpage RAII_Samples_MultipleSets + +\subpage RAII_Samples_OcclusionQuery + +\subpage RAII_Samples_PhysicalDeviceExtensions + +\subpage RAII_Samples_PhysicalDeviceFeatures + +\subpage RAII_Samples_PhysicalDeviceGroups + +\subpage RAII_Samples_PhysicalDeviceMemoryProperties + +\subpage RAII_Samples_PhysicalDeviceProperties + +\subpage RAII_Samples_PhysicalDeviceQueueFamilyProperties + +\subpage RAII_Samples_PipelineCache + +\subpage RAII_Samples_PipelineDerivative + +\subpage RAII_Samples_PushConstants + +\subpage RAII_Samples_PushDescriptors + +\subpage RAII_Samples_RayTracing + +\subpage RAII_Samples_SecondaryCommandBuffer + +\subpage RAII_Samples_SeparateImageSampler + +\subpage RAII_Samples_SurfaceCapabilities + +\subpage RAII_Samples_SurfaceFormats + +\subpage RAII_Samples_Template + +\subpage RAII_Samples_TexelBuffer + + +\page RAII_Samples_01_InitInstance 01_InitInstance +\include RAII_Samples/01_InitInstance/01_InitInstance.cpp + +\page RAII_Samples_02_EnumerateDevices 02_EnumerateDevices +\include RAII_Samples/02_EnumerateDevices/02_EnumerateDevices.cpp + +\page RAII_Samples_03_InitDevice 03_InitDevice +\include RAII_Samples/03_InitDevice/03_InitDevice.cpp + +\page RAII_Samples_04_InitCommandBuffer 04_InitCommandBuffer +\include RAII_Samples/04_InitCommandBuffer/04_InitCommandBuffer.cpp + +\page RAII_Samples_05_InitSwapchain 05_InitSwapchain +\include RAII_Samples/05_InitSwapchain/05_InitSwapchain.cpp + +\page RAII_Samples_06_InitDepthBuffer 06_InitDepthBuffer +\include RAII_Samples/06_InitDepthBuffer/06_InitDepthBuffer.cpp + +\page RAII_Samples_07_InitUniformBuffer 07_InitUniformBuffer +\include RAII_Samples/07_InitUniformBuffer/07_InitUniformBuffer.cpp + +\page RAII_Samples_08_InitPipelineLayout 08_InitPipelineLayout +\include RAII_Samples/08_InitPipelineLayout/08_InitPipelineLayout.cpp + +\page RAII_Samples_09_InitDescriptorSet 09_InitDescriptorSet +\include RAII_Samples/09_InitDescriptorSet/09_InitDescriptorSet.cpp + +\page RAII_Samples_10_InitRenderPass 10_InitRenderPass +\include RAII_Samples/10_InitRenderPass/10_InitRenderPass.cpp + +\page RAII_Samples_11_InitShaders 11_InitShaders +\include RAII_Samples/11_InitShaders/11_InitShaders.cpp + +\page RAII_Samples_12_InitFrameBuffers 12_InitFrameBuffers +\include RAII_Samples/12_InitFrameBuffers/12_InitFrameBuffers.cpp + +\page RAII_Samples_13_InitVertexBuffer 13_InitVertexBuffer +\include RAII_Samples/13_InitVertexBuffer/13_InitVertexBuffer.cpp + +\page RAII_Samples_14_InitPipeline 14_InitPipeline +\include RAII_Samples/14_InitPipeline/14_InitPipeline.cpp + +\page RAII_Samples_15_DrawCube 15_DrawCube +\include RAII_Samples/15_DrawCube/15_DrawCube.cpp + +\page RAII_Samples_16_Vulkan_1_1 16_Vulkan_1_1 +\include RAII_Samples/16_Vulkan_1_1/16_Vulkan_1_1.cpp + +\page RAII_Samples_CopyBlitImage CopyBlitImage +\include RAII_Samples/CopyBlitImage/CopyBlitImage.cpp + +\page RAII_Samples_CreateDebugUtilsMessenger CreateDebugUtilsMessenger +\include RAII_Samples/CreateDebugUtilsMessenger/CreateDebugUtilsMessenger.cpp + +\page RAII_Samples_DebugUtilsObjectName DebugUtilsObjectName +\include RAII_Samples/DebugUtilsObjectName/DebugUtilsObjectName.cpp + +\page RAII_Samples_DrawTexturedCube DrawTexturedCube +\include RAII_Samples/DrawTexturedCube/DrawTexturedCube.cpp + +\page RAII_Samples_DynamicUniform DynamicUniform +\include RAII_Samples/DynamicUniform/DynamicUniform.cpp + +\page RAII_Samples_EnableValidationWithCallback EnableValidationWithCallback +\include RAII_Samples/EnableValidationWithCallback/EnableValidationWithCallback.cpp + +\page RAII_Samples_EnumerateDevicesAdvanced EnumerateDevicesAdvanced +\include RAII_Samples/EnumerateDevicesAdvanced/EnumerateDevicesAdvanced.cpp + +\page RAII_Samples_Events Events +\include RAII_Samples/Events/Events.cpp + +\page RAII_Samples_ImmutableSampler ImmutableSampler +\include RAII_Samples/ImmutableSampler/ImmutableSampler.cpp + +\page RAII_Samples_InitTexture InitTexture +\include RAII_Samples/InitTexture/InitTexture.cpp + +\page RAII_Samples_InputAttachment InputAttachment +\include RAII_Samples/InputAttachment/InputAttachment.cpp + +\page RAII_Samples_InstanceExtensionProperties InstanceExtensionProperties +\include RAII_Samples/InstanceExtensionProperties/InstanceExtensionProperties.cpp + +\page RAII_Samples_InstanceLayerExtensionProperties InstanceLayerExtensionProperties +\include RAII_Samples/InstanceLayerExtensionProperties/InstanceLayerExtensionProperties.cpp + +\page RAII_Samples_InstanceLayerProperties InstanceLayerProperties +\include RAII_Samples/InstanceLayerProperties/InstanceLayerProperties.cpp + +\page RAII_Samples_InstanceVersion InstanceVersion +\include RAII_Samples/InstanceVersion/InstanceVersion.cpp + +\page RAII_Samples_MultipleSets MultipleSets +\include RAII_Samples/MultipleSets/MultipleSets.cpp + +\page RAII_Samples_OcclusionQuery OcclusionQuery +\include RAII_Samples/OcclusionQuery/OcclusionQuery.cpp + +\page RAII_Samples_PhysicalDeviceExtensions PhysicalDeviceExtensions +\include RAII_Samples/PhysicalDeviceExtensions/PhysicalDeviceExtensions.cpp + +\page RAII_Samples_PhysicalDeviceFeatures PhysicalDeviceFeatures +\include RAII_Samples/PhysicalDeviceFeatures/PhysicalDeviceFeatures.cpp + +\page RAII_Samples_PhysicalDeviceGroups PhysicalDeviceGroups +\include RAII_Samples/PhysicalDeviceGroups/PhysicalDeviceGroups.cpp + +\page RAII_Samples_PhysicalDeviceMemoryProperties PhysicalDeviceMemoryProperties +\include RAII_Samples/PhysicalDeviceMemoryProperties/PhysicalDeviceMemoryProperties.cpp + +\page RAII_Samples_PhysicalDeviceProperties PhysicalDeviceProperties +\include RAII_Samples/PhysicalDeviceProperties/PhysicalDeviceProperties.cpp + +\page RAII_Samples_PhysicalDeviceQueueFamilyProperties PhysicalDeviceQueueFamilyProperties +\include RAII_Samples/PhysicalDeviceQueueFamilyProperties/PhysicalDeviceQueueFamilyProperties.cpp + +\page RAII_Samples_PipelineCache PipelineCache +\include RAII_Samples/PipelineCache/PipelineCache.cpp + +\page RAII_Samples_PipelineDerivative PipelineDerivative +\include RAII_Samples/PipelineDerivative/PipelineDerivative.cpp + +\page RAII_Samples_PushConstants PushConstants +\include RAII_Samples/PushConstants/PushConstants.cpp + +\page RAII_Samples_PushDescriptors PushDescriptors +\include RAII_Samples/PushDescriptors/PushDescriptors.cpp + +\page RAII_Samples_RayTracing RayTracing +\include RAII_Samples/RayTracing/RayTracing.cpp + +\page RAII_Samples_SecondaryCommandBuffer SecondaryCommandBuffer +\include RAII_Samples/SecondaryCommandBuffer/SecondaryCommandBuffer.cpp + +\page RAII_Samples_SeparateImageSampler SeparateImageSampler +\include RAII_Samples/SeparateImageSampler/SeparateImageSampler.cpp + +\page RAII_Samples_SurfaceCapabilities SurfaceCapabilities +\include RAII_Samples/SurfaceCapabilities/SurfaceCapabilities.cpp + +\page RAII_Samples_SurfaceFormats SurfaceFormats +\include RAII_Samples/SurfaceFormats/SurfaceFormats.cpp + +\page RAII_Samples_Template Template +\include RAII_Samples/Template/Template.cpp + +\page RAII_Samples_TexelBuffer TexelBuffer +\include RAII_Samples/TexelBuffer/TexelBuffer.cpp +*/ \ No newline at end of file diff --git a/docs/Samples.dox b/docs/Samples.dox new file mode 100644 index 000000000..93492ec31 --- /dev/null +++ b/docs/Samples.dox @@ -0,0 +1,266 @@ +/** +\cond +File generate using `python3 docs/generate_samples_dox.py` +\endcond +\page Samples Samples +\subpage Samples_01_InitInstance + +\subpage Samples_02_EnumerateDevices + +\subpage Samples_03_InitDevice + +\subpage Samples_04_InitCommandBuffer + +\subpage Samples_05_InitSwapchain + +\subpage Samples_06_InitDepthBuffer + +\subpage Samples_07_InitUniformBuffer + +\subpage Samples_08_InitPipelineLayout + +\subpage Samples_09_InitDescriptorSet + +\subpage Samples_10_InitRenderPass + +\subpage Samples_11_InitShaders + +\subpage Samples_12_InitFrameBuffers + +\subpage Samples_13_InitVertexBuffer + +\subpage Samples_14_InitPipeline + +\subpage Samples_15_DrawCube + +\subpage Samples_16_Vulkan_1_1 + +\subpage Samples_CopyBlitImage + +\subpage Samples_CreateDebugUtilsMessenger + +\subpage Samples_DebugUtilsObjectName + +\subpage Samples_DrawTexturedCube + +\subpage Samples_DynamicUniform + +\subpage Samples_EnableValidationWithCallback + +\subpage Samples_EnumerateDevicesAdvanced + +\subpage Samples_Events + +\subpage Samples_ImmutableSampler + +\subpage Samples_InitTexture + +\subpage Samples_InputAttachment + +\subpage Samples_InstanceExtensionProperties + +\subpage Samples_InstanceLayerExtensionProperties + +\subpage Samples_InstanceLayerProperties + +\subpage Samples_InstanceVersion + +\subpage Samples_MultipleSets + +\subpage Samples_OcclusionQuery + +\subpage Samples_PhysicalDeviceExtensions + +\subpage Samples_PhysicalDeviceFeatures + +\subpage Samples_PhysicalDeviceGroups + +\subpage Samples_PhysicalDeviceMemoryProperties + +\subpage Samples_PhysicalDeviceProperties + +\subpage Samples_PhysicalDeviceQueueFamilyProperties + +\subpage Samples_PipelineCache + +\subpage Samples_PipelineDerivative + +\subpage Samples_PushConstants + +\subpage Samples_PushDescriptors + +\subpage Samples_RayTracing + +\subpage Samples_SecondaryCommandBuffer + +\subpage Samples_SeparateImageSampler + +\subpage Samples_SharedHandles + +\subpage Samples_SurfaceCapabilities + +\subpage Samples_SurfaceFormats + +\subpage Samples_Template + +\subpage Samples_TexelBuffer + +\subpage Samples_utils + + +\page Samples_01_InitInstance 01_InitInstance +\include samples/01_InitInstance/01_InitInstance.cpp + +\page Samples_02_EnumerateDevices 02_EnumerateDevices +\include samples/02_EnumerateDevices/02_EnumerateDevices.cpp + +\page Samples_03_InitDevice 03_InitDevice +\include samples/03_InitDevice/03_InitDevice.cpp + +\page Samples_04_InitCommandBuffer 04_InitCommandBuffer +\include samples/04_InitCommandBuffer/04_InitCommandBuffer.cpp + +\page Samples_05_InitSwapchain 05_InitSwapchain +\include samples/05_InitSwapchain/05_InitSwapchain.cpp + +\page Samples_06_InitDepthBuffer 06_InitDepthBuffer +\include samples/06_InitDepthBuffer/06_InitDepthBuffer.cpp + +\page Samples_07_InitUniformBuffer 07_InitUniformBuffer +\include samples/07_InitUniformBuffer/07_InitUniformBuffer.cpp + +\page Samples_08_InitPipelineLayout 08_InitPipelineLayout +\include samples/08_InitPipelineLayout/08_InitPipelineLayout.cpp + +\page Samples_09_InitDescriptorSet 09_InitDescriptorSet +\include samples/09_InitDescriptorSet/09_InitDescriptorSet.cpp + +\page Samples_10_InitRenderPass 10_InitRenderPass +\include samples/10_InitRenderPass/10_InitRenderPass.cpp + +\page Samples_11_InitShaders 11_InitShaders +\include samples/11_InitShaders/11_InitShaders.cpp + +\page Samples_12_InitFrameBuffers 12_InitFrameBuffers +\include samples/12_InitFrameBuffers/12_InitFrameBuffers.cpp + +\page Samples_13_InitVertexBuffer 13_InitVertexBuffer +\include samples/13_InitVertexBuffer/13_InitVertexBuffer.cpp + +\page Samples_14_InitPipeline 14_InitPipeline +\include samples/14_InitPipeline/14_InitPipeline.cpp + +\page Samples_15_DrawCube 15_DrawCube +\include samples/15_DrawCube/15_DrawCube.cpp + +\page Samples_16_Vulkan_1_1 16_Vulkan_1_1 +\include samples/16_Vulkan_1_1/16_Vulkan_1_1.cpp + +\page Samples_CopyBlitImage CopyBlitImage +\include samples/CopyBlitImage/CopyBlitImage.cpp + +\page Samples_CreateDebugUtilsMessenger CreateDebugUtilsMessenger +\include samples/CreateDebugUtilsMessenger/CreateDebugUtilsMessenger.cpp + +\page Samples_DebugUtilsObjectName DebugUtilsObjectName +\include samples/DebugUtilsObjectName/DebugUtilsObjectName.cpp + +\page Samples_DrawTexturedCube DrawTexturedCube +\include samples/DrawTexturedCube/DrawTexturedCube.cpp + +\page Samples_DynamicUniform DynamicUniform +\include samples/DynamicUniform/DynamicUniform.cpp + +\page Samples_EnableValidationWithCallback EnableValidationWithCallback +\include samples/EnableValidationWithCallback/EnableValidationWithCallback.cpp + +\page Samples_EnumerateDevicesAdvanced EnumerateDevicesAdvanced +\include samples/EnumerateDevicesAdvanced/EnumerateDevicesAdvanced.cpp + +\page Samples_Events Events +\include samples/Events/Events.cpp + +\page Samples_ImmutableSampler ImmutableSampler +\include samples/ImmutableSampler/ImmutableSampler.cpp + +\page Samples_InitTexture InitTexture +\include samples/InitTexture/InitTexture.cpp + +\page Samples_InputAttachment InputAttachment +\include samples/InputAttachment/InputAttachment.cpp + +\page Samples_InstanceExtensionProperties InstanceExtensionProperties +\include samples/InstanceExtensionProperties/InstanceExtensionProperties.cpp + +\page Samples_InstanceLayerExtensionProperties InstanceLayerExtensionProperties +\include samples/InstanceLayerExtensionProperties/InstanceLayerExtensionProperties.cpp + +\page Samples_InstanceLayerProperties InstanceLayerProperties +\include samples/InstanceLayerProperties/InstanceLayerProperties.cpp + +\page Samples_InstanceVersion InstanceVersion +\include samples/InstanceVersion/InstanceVersion.cpp + +\page Samples_MultipleSets MultipleSets +\include samples/MultipleSets/MultipleSets.cpp + +\page Samples_OcclusionQuery OcclusionQuery +\include samples/OcclusionQuery/OcclusionQuery.cpp + +\page Samples_PhysicalDeviceExtensions PhysicalDeviceExtensions +\include samples/PhysicalDeviceExtensions/PhysicalDeviceExtensions.cpp + +\page Samples_PhysicalDeviceFeatures PhysicalDeviceFeatures +\include samples/PhysicalDeviceFeatures/PhysicalDeviceFeatures.cpp + +\page Samples_PhysicalDeviceGroups PhysicalDeviceGroups +\include samples/PhysicalDeviceGroups/PhysicalDeviceGroups.cpp + +\page Samples_PhysicalDeviceMemoryProperties PhysicalDeviceMemoryProperties +\include samples/PhysicalDeviceMemoryProperties/PhysicalDeviceMemoryProperties.cpp + +\page Samples_PhysicalDeviceProperties PhysicalDeviceProperties +\include samples/PhysicalDeviceProperties/PhysicalDeviceProperties.cpp + +\page Samples_PhysicalDeviceQueueFamilyProperties PhysicalDeviceQueueFamilyProperties +\include samples/PhysicalDeviceQueueFamilyProperties/PhysicalDeviceQueueFamilyProperties.cpp + +\page Samples_PipelineCache PipelineCache +\include samples/PipelineCache/PipelineCache.cpp + +\page Samples_PipelineDerivative PipelineDerivative +\include samples/PipelineDerivative/PipelineDerivative.cpp + +\page Samples_PushConstants PushConstants +\include samples/PushConstants/PushConstants.cpp + +\page Samples_PushDescriptors PushDescriptors +\include samples/PushDescriptors/PushDescriptors.cpp + +\page Samples_RayTracing RayTracing +\include samples/RayTracing/RayTracing.cpp + +\page Samples_SecondaryCommandBuffer SecondaryCommandBuffer +\include samples/SecondaryCommandBuffer/SecondaryCommandBuffer.cpp + +\page Samples_SeparateImageSampler SeparateImageSampler +\include samples/SeparateImageSampler/SeparateImageSampler.cpp + +\page Samples_SharedHandles SharedHandles +\include samples/SharedHandles/SharedHandles.cpp + +\page Samples_SurfaceCapabilities SurfaceCapabilities +\include samples/SurfaceCapabilities/SurfaceCapabilities.cpp + +\page Samples_SurfaceFormats SurfaceFormats +\include samples/SurfaceFormats/SurfaceFormats.cpp + +\page Samples_Template Template +\include samples/Template/Template.cpp + +\page Samples_TexelBuffer TexelBuffer +\include samples/TexelBuffer/TexelBuffer.cpp + +\page Samples_utils utils +\include samples/utils/utils.cpp +*/ \ No newline at end of file diff --git a/docs/generate_samples_dox.py b/docs/generate_samples_dox.py new file mode 100644 index 000000000..83653c7af --- /dev/null +++ b/docs/generate_samples_dox.py @@ -0,0 +1,48 @@ +""" +Generate Samples.dox RAII_Samples.dox +""" + +import argparse +from glob import glob +from os.path import isfile, join, basename +import sys + + +def main(): + + parser = argparse.ArgumentParser() + parser.add_argument('-s', '--sample-folder', help="Sample folder", default="samples") + parser.add_argument('-o', '--output-file', help="Output file", default="docs/Samples.dox") + args = parser.parse_args() + + with open(args.output_file, 'w') as f: + f.write(fr"""/** +\cond +File generate using `python3 {' '.join(sys.argv)}` +\endcond +\page {basename(args.output_file).replace('.dox', '')} {basename(args.output_file).replace('.dox', '').replace('_', ' ')} +""") # noqa + pages = [] + for sample in sorted(glob(join(args.sample_folder, '*'))): + file = join(sample, basename(sample) + '.cpp') + if isfile(file): + pages.append({ + 'file': file, + 'page': basename(args.output_file).replace('.dox', '') + '_' + basename(sample), + 'title': basename(sample), + }) + for page in pages: + f.write(f"""\\subpage {page['page']}\n\n""") + + for page in pages: + f.write(rf""" +\page {page['page']} {page['title']} +\include {page['file']} +""") + f.write(r"*/") + with open(args.output_file) as f: + print(f.read()) + + +if __name__ == '__main__': + main() diff --git a/docs/mainpage.dox b/docs/mainpage.dox new file mode 100644 index 000000000..e768afee1 --- /dev/null +++ b/docs/mainpage.dox @@ -0,0 +1,10 @@ +/** + +\mainpage Vulkan-Hpp + +- \ref README.md \n +- \ref vk_raii_ProgrammingGuide.md \n +- \ref Samples \n +- \ref RAII_Samples \n + +*/ diff --git a/doxygen-awesome-css b/doxygen-awesome-css new file mode 160000 index 000000000..df88fe4fd --- /dev/null +++ b/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit df88fe4fdd97714fadfd3ef17de0b4401f804052 From c8ffcb41544d616d403a4a3c5983600f1f9ff4a2 Mon Sep 17 00:00:00 2001 From: Stephan Seitz Date: Sat, 20 Jan 2024 16:52:01 +0100 Subject: [PATCH 2/3] docs: refactor code blocks to use ```cpp This format can be understood by doxygen for syntax highlighting. --- README.md | 62 +++++++++++------------ vk_raii_ProgrammingGuide.md | 98 +++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 4449a58dd..fcc1e3e33 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ The scoped enum feature adds type safety to the flags, but also prevents using t As solution Vulkan-Hpp provides a template class `vk::Flags` which brings the standard operations like `&=`, `|=`, `&` and `|` to our scoped enums. Except for the initialization with 0 this class behaves exactly like a normal bitmask with the improvement that it is impossible to set bits not specified by the corresponding enum by accident. Here are a few examples for the bitmask handling: -```c++ +```cpp vk::ImageUsageFlags iu1; // initialize a bitmask with no bit set vk::ImageUsageFlags iu2 = {}; // initialize a bitmask with no bit set vk::ImageUsageFlags iu3 = vk::ImageUsageFlagBits::eColorAttachment; // initialize with a single value @@ -112,7 +112,7 @@ PipelineShaderStageCreateInfo ci( {} /* pass a flag without any bits set */, ... When constructing a handle in Vulkan one usually has to create some `CreateInfo` struct which describes the new handle. This can result in quite lengthy code as can be seen in the following Vulkan C example: -```c++ +```cpp VkImageCreateInfo ci; ci.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO; ci.pNext = nullptr; @@ -140,7 +140,7 @@ Especially the first one is hard to detect. Vulkan-Hpp provides constructors for all CreateInfo objects which accept one parameter for each member variable. This way the compiler throws a compiler error if a value has been forgotten. In addition to this `sType` is automatically filled with the correct value and `pNext` set to a `nullptr` by default. Here's how the same code looks with a constructor: -```c++ +```cpp vk::ImageCreateInfo ci({}, vk::ImageType::e2D, vk::Format::eR8G8B8A8Unorm, { width, height, 1 }, 1, 1, vk::SampleCountFlagBits::e1, @@ -151,7 +151,7 @@ vk::Image image = device.createImage(ci); With constructors for CreateInfo structures one can also pass temporaries to Vulkan functions like this: -```c++ +```cpp vk::Image image = device.createImage({{}, vk::ImageType::e2D, vk::Format::eR8G8B8A8Unorm, { width, height, 1 }, 1, 1, vk::SampleCountFlagBits::e1, @@ -162,7 +162,7 @@ vk::Image image = device.createImage({{}, vk::ImageType::e2D, vk::Format::eR8G8B ### Designated Initializers Beginning with C++20, C++ supports designated initializers. As that feature requires to not have any user-declared or inherited constructors, you have to `#define VULKAN_HPP_NO_CONSTRUCTORS`, which removes all the structure and union constructors from vulkan.hpp. Instead you can then use aggregate initialization. The first few vk-lines in your source might then look like -```c++ +```cpp // initialize the vk::ApplicationInfo structure vk::ApplicationInfo applicationInfo{ .pApplicationName = AppName, .applicationVersion = 1, @@ -174,7 +174,7 @@ vk::ApplicationInfo applicationInfo{ .pApplicationName = AppName, vk::InstanceCreateInfo instanceCreateInfo{ .pApplicationInfo = & applicationInfo }; ``` instead of -```c++ +```cpp // initialize the vk::ApplicationInfo structure vk::ApplicationInfo applicationInfo( AppName, 1, EngineName, 1, VK_API_VERSION_1_1 ); @@ -190,7 +190,7 @@ The Vulkan API has several places where which require (count,pointer) as two fun Here are some code samples on how to use the ArrayProxy: -```c++ +```cpp vk::CommandBuffer c; // pass an empty array @@ -233,7 +233,7 @@ c.setScissor(0, vec); Vulkan-Hpp generates references for pointers to structs. This conversion allows passing temporary structs to functions which can result in shorter code. In case the input is optional and thus accepting a null pointer the parameter type will be a `vk::Optional const&` type. This type accepts either a reference to `T` or nullptr as input and thus allows optional temporary structs. -```c++ +```cpp // C VkImageSubresource subResource; subResource.aspectMask = 0; @@ -250,7 +250,7 @@ auto layout = device.getImageSubresourceLayout(image, { {} /* flags*/, 0 /* mipl Vulkan allows chaining of structures through the pNext pointer. Vulkan-Hpp has a variadic template class which allows constructing of such structure chains with minimal efforts. In addition to this it checks at compile time if the spec allows the construction of such a `pNext` chain. -```c++ +```cpp // This will compile successfully. vk::StructureChain c; vk::MemoryAllocateInfo &allocInfo = c.get(); @@ -264,7 +264,7 @@ vk::ImportMemoryFdInfoKHR &fdInfo = c.get(); Vulkan-Hpp provides a constructor for these chains similar to the CreateInfo objects which accepts a list of all structures part of the chain. The `pNext` field is automatically set to the correct value: -```c++ +```cpp vk::StructureChain c = { vk::MemoryAllocateInfo(size, type), vk::MemoryDedicatedAllocateInfo(image) @@ -276,7 +276,7 @@ In case that very same structure has to be re-added to the StructureChain again, Sometimes the user has to pass a preallocated structure chain to query information. For those cases there are two corresponding getter functions. One with a variadic template generating a structure chain of at least two elements to construct the return value: -```c++ +```cpp // Query vk::MemoryRequirements2HR and vk::MemoryDedicatedRequirementsKHR when calling Device::getBufferMemoryRequirements2KHR: auto result = device.getBufferMemoryRequirements2KHR({}); vk::MemoryRequirements2KHR &memReqs = result.get(); @@ -296,13 +296,13 @@ By default Vulkan-Hpp has exceptions enabled. This means that Vulkan-Hpp checks To create a device you can now just write: -```C++ +```cpp vk::Device device = physicalDevice.createDevice(createInfo); ``` Some functions allow more than just `vk::Result::eSuccess` to be considered as a success code. For those functions, we always return a `ResultValue`. An example is `acquireNextImage2KHR`, that can be used like this: -```C++ +```cpp vk::ResultValue result = device->acquireNextImage2KHR(acquireNextImageInfo); switch (result.result) { @@ -328,7 +328,7 @@ In case you don’t want to use the `vk::ArrayProxy` and return value transforma The first snippet shows how to use the API without exceptions and the return value transformation: -```c++ +```cpp // No exceptions, no return value transformation ShaderModuleCreateInfo createInfo(...); ShaderModule shader1; @@ -352,7 +352,7 @@ if (result != VK_SUCCESS) The second snippet shows how to use the API using return value transformation, but without exceptions. It’s already a little bit shorter than the original code: -```c++ +```cpp ResultValue shaderResult1 = device.createShaderModule({...} /* createInfo temporary */); if (shaderResult1.result != VK_SUCCESS) { @@ -375,13 +375,13 @@ if (result != VK_SUCCESS) A nicer way to unpack the result is provided by the structured bindings of C++17. They will allow us to get the result with a single line of code: -```c++ +```cpp auto [result, shaderModule2] = device.createShaderModule({...} /* createInfo temporary */); ``` Finally, the last code example is using exceptions and return value transformation. This is the default mode of the API. -```c++ +```cpp ShaderModule shader1; ShaderModule shader2; try { @@ -402,7 +402,7 @@ With C++17 and above, some functions are attributed with [[nodiscard]], resultin For the return value transformation, there's one special class of return values which require special handling: Enumerations. For enumerations you usually have to write code like this: -```c++ +```cpp std::vector properties; uint32_t propertyCount; Result result; @@ -424,7 +424,7 @@ properties.resize(propertyCount); Since writing this loop over and over again is tedious and error prone the C++ binding takes care of the enumeration so that you can just write: -```c++ +```cpp std::vector properties = physicalDevice.enumerateDeviceLayerProperties(); ``` @@ -446,7 +446,7 @@ This mechanism ensures correct destruction order even if the parent SharedHandle There are no functions which return a `vk::SharedHandle` directly yet. Instead, you can construct a `vk::SharedHandle` from a `vk::Handle`: -```c++ +```cpp vk::Buffer buffer = device.createBuffer(...); vk::SharedBuffer sharedBuffer(buffer, device); // sharedBuffer now owns the buffer @@ -454,14 +454,14 @@ vk::SharedBuffer sharedBuffer(buffer, device); // sharedBuffer now owns the buff There are several specializations of `vk::SharedHandle` for different handle types. For example, `vk::SharedImage` may take an additional argument to specify if the image is owned by swapchain: -```c++ +```cpp vk::Image image = swapchain.getImages(...)[0]; // get the first image from the swapchain vk::SharedImage sharedImage(image, device, SwapChainOwns::yes); // sharedImage now owns the image, but won't destroy it ``` There is also a specialization for `vk::SwapchainKHR` which takes an additional argument to specify a surface: -```c++ +```cpp vk::SwapchainKHR swapchain = device.createSwapchainKHR(...); vk::SharedSwapchainKHR sharedSwapchain(swapchain, device, surface); // sharedSwapchain now owns the swapchain and surface ``` @@ -473,7 +473,7 @@ You can create a `vk::SharedHandle` overload for your own handle type or own sha With this, provide a custom static destruction function `internalDestroy`, that takes in a parent handle and a handle to destroy. Don't forget to add a friend declaration for the base class. -```c++ +```cpp // Example of a custom shared device, that takes in an instance as a parent class shared_handle : public vk::SharedHandleBase> { @@ -504,13 +504,13 @@ The API will be extended to provide creation functions in the future. Sometimes it is required to use `std::vector` with custom allocators. Vulkan-Hpp supports vectors with custom allocators as input for `vk::ArrayProxy` and for functions which do return a vector. For the latter case, add your favorite custom allocator as template argument to the function call like this: -```c++ +```cpp std::vector properties = physicalDevice.enumerateDeviceLayerProperties(); ``` You can as well use a stateful custom allocator by providing it as an argument to those functions. Unfortunately, to make the compilers happy, you also need to explicitly set the Dispatch argument. To get the default there, a simple `{}` would suffice: -```c++ +```cpp MyStatefulCustomAllocator allocator; std::vector properties = physicalDevice.enumerateDeviceLayerProperties( allocator, {} ); ``` @@ -529,7 +529,7 @@ There are a couple of static assertions for each handle class and each struct in The Vulkan loader exposes only the Vulkan core functions and a limited number of extensions. To use Vulkan-Hpp with extensions it's required to have either a library which provides stubs to all used Vulkan functions or to tell Vulkan-Hpp to dispatch those functions pointers. Vulkan-Hpp provides a per-function dispatch mechanism by accepting a dispatch class as last parameter in each function call. The dispatch class must provide a callable type for each used Vulkan function. Vulkan-Hpp provides one implementation, ```DispatchLoaderDynamic```, which fetches all function pointers known to the library. -```c++ +```cpp // Providing a function pointer resolving vkGetInstanceProcAddr, just the few functions not depending an an instance or a device are fetched vk::DispatchLoaderDynamic dld( getInstanceProcAddr ); @@ -547,27 +547,27 @@ To use the `vk::DispatchLoaderDynamic` as the default dispatcher (means: you don Creating a full featured `vk::DispatchLoaderDynamic` is a two- to three-step process, where you have three choices for the first step: 1. Before any call into a vk-function you need to initialize the dynamic dispatcher by one of three methods - Let Vulkan-Hpp do all the work by internally using a little helper class `vk::DynamicLoader`: -```c++ +```cpp VULKAN_HPP_DEFAULT_DISPATCHER.init(); ``` - Use your own dynamic loader, which just needs to provide a templated function `getProcAddress` (compare with `vk::DynamicLoader` in vulkan.hpp): -```c++ +```cpp YourDynamicLoader ydl; VULKAN_HPP_DEFAULT_DISPATCHER.init(ydl); ``` Note that you need to keep that dynamic loader object alive until after the last call to a vulkan function in your program. For example by making it static, or storing it somewhere globally. - Use your own initial function pointer of type PFN_vkGetInstanceProcAddr: -```c++ +```cpp PFN_vkGetInstanceProcAddr vkGetInstanceProcAddr = your_own_function_pointer_getter(); VULKAN_HPP_DEFAULT_DISPATCHER.init(vkGetInstanceProcAddr); ``` 2. initialize it with a vk::Instance to get all the other function pointers: -```c++ +```cpp vk::Instance instance = vk::createInstance({}, nullptr); VULKAN_HPP_DEFAULT_DISPATCHER.init(instance); ``` 3. optionally initialize it with a vk::Device to get device-specific function pointers -```c++ +```cpp std::vector physicalDevices = instance.enumeratePhysicalDevices(); assert(!physicalDevices.empty()); vk::Device device = physicalDevices[0].createDevice({}, nullptr); diff --git a/vk_raii_ProgrammingGuide.md b/vk_raii_ProgrammingGuide.md index a99d1e488..f3679bcc2 100644 --- a/vk_raii_ProgrammingGuide.md +++ b/vk_raii_ProgrammingGuide.md @@ -10,28 +10,37 @@ vulkan_raii.hpp is a C++ layer on top of vulkan.hpp that follows the RAII-princi As a simple example, instead of creating a `vk::Device` +```cpp // create a vk::Device, given a vk::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo vk::Device device = physicalDevice.createDevice( deviceCreateInfo ); +``` and destroying it at some point +```cpp // destroy a vk::Device device.destroy(); +``` you would create a `vk::raii::Device` +```cpp // create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo vk::raii::Device device( physicalDevice, deviceCreateInfo ); +``` That `vk::raii::Device` is automatically destroyed, when its scope is left. Alternatively, you can use a creation function to create a `vk::raii::Device`: +```cpp // create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo vk::raii::Device device = physicalDevice.createDevice( deviceCreateInfo ); +``` Finally, if you have defined `VULKAN_HPP_NO_EXCPETIONS` and compile for at least C++23, the constructors as described above are not available (they would potentially throw an exception which is not allowed then) but you have to use the construction functions. Those functions then do not return the created object, but a `std::expected`: +```cpp // create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo // when VULKAN_HPP_NO_EXCPETIONS is defined and your using at least C++23 auto deviceExpected = physicalDevice.createDevice( deviceCreateInfo ); @@ -39,15 +48,18 @@ Finally, if you have defined `VULKAN_HPP_NO_EXCPETIONS` and compile for at least { device = std::move( *deviceExpected ); } +``` In the code snippets in this text, I will consistently use the constructor-approach. Other than the `vk::Device`, you can assign the `vk::raii::Device` to a smart pointer: +```cpp // create a smart-pointer to a vk::raii::Device, given a smart-pointer to a vk::raii::PhysicalDevice pPhysicalDevice and a vk::DeviceCreateInfo deviceCreateInfo std::unique_ptr pDevice; pDevice = std::make_unique( *pPhysicalDevice, deviceCreateInfo ); +``` Note that the vk::raii objects own the actual Vulkan resource. Therefore, all vk::raii objects that own destructable resources are just movable, but not copyable. Therefore, a few vk::raii objects, like vk::raii::PhysicalDevice are copyable as well. @@ -57,21 +69,27 @@ Similar to a `vk::Device`, a `vk::raii::Device` provides the functions related t That is, calling a device-related function is identical for both cases: +```cpp // call waitIdle from a vk::Device device.waitIdle(); // call waitIdle from a vk::raii::Device device.waitIdle(); +``` vk::raii goes one step further. In the vk namespace, most of the functions are members of `vk::Device`. In the vk::raii namespace functions strongly related to a non-dispatchable handle are members of the corresponding vi::raii object. For example, to bind memory to a buffer, in vk namespace you write +```cpp // bind vk::DeviceMemory memory to a vk::Buffer buffer, given vk::DeviceSize memoryOffset device.bindBufferMemory( buffer, memory, memoryOffset ); +``` In vk::raii namespace you write +```cpp // bind vk::raii::DeviceMemory memory to a vk::raii::Buffer buffer, given vk::DeviceSize memoryOffset buffer.bindMemory( *memory, memoryOffset ); +``` Note that `vk::raii::Buffer::bindMemory()`takes a `vk::DeviceMemory` as its first argument, not a `vk::raii::DeviceMemory`. From a vk::raii object you get to the corresponding vk object by just dereferencing the vk::raii object. @@ -81,42 +99,56 @@ Note that `vk::raii::Buffer::bindMemory()`takes a `vk::DeviceMemory` as its firs The very first step when using classes from the vk::raii namespace is to instantiate a `vk::raii::Context`. This class has no counterpart in either the vk namespace or the pure C-API of Vulkan. It is the handle to the few functions that are not bound to a `VkInstance` or a `VkDevice`: +```cpp // instantiate a vk::raii::Context vk::raii::Context context; +``` To use any of those "global" functions, your code would look like that: +```cpp // get the API version, using that context uint32_t apiVersion = context.enumerateInstanceVersion(); +``` ### 01 Create a vk::raii::Instance To pass that information on to a `vk::raii::Instance`, its constructor gets a reference to that `vk::raii::Context`: +```cpp // instantiate a vk::raii::Instance, given a vk::raii::Context context and a vk::InstanceCreateInfo instanceCreateInfo vk::raii::Instance instance( context, instanceCreateInfo ); +``` The `vk::raii::Instance` now holds all the instance-related functions. For example, to get all the `vk::PhysicalDeviceGroupProperties` for an instance, your call would look like this: +```cpp // get all vk::PhysicalDeviceGroupProperties from a vk::raii::Instance instance std::vector physicalDeviceGroupProperties = instance.enumeratePhysicalDeviceGroups(); +``` ### 02 Enumerate the vk::raii::PhysicalDevices Enumerating the physical devices of an instance is slightly different in vk::raii namespace as you might be used to from the vk-namespace or the pure C-API. As there might be multiple physical devices attached, you would instantiate a `vk::raii::PhysicalDevices` (note the trailing 's' here!), which essentially is a `std::vector` of `vk::raii::PhysicalDevice`s (note the trailing 's' here!): +```cpp // enumerate the vk::raii::PhysicalDevices, given a vk::raii::Instance instance vk::raii::PhysicalDevices physicalDevices( instance ); +``` As vk::raii::PhysicalDevices is just a `std::vector`, you can access any specific `vk::raii:PhysicalDevice` by indexing into that `std::vector`: +```cpp // get the vk::LayerProperties of the vk::raii::PhysicalDevice with index physicalDeviceIndex, given a vk::raii::PhysicalDevices physicalDevices std::vector layerProperties = physicalDevices[physicalDeviceIndex].enumerateDeviceLayerProperties(); +``` You can as well get one `vk::raii::PhysicalDevice` out of a `vk::raii::PhysicalDevices` like this: +```cpp // get the vk::raii::PhysicalDevice with index physicalDeviceIndex, given a vk::raii::PhysicalDevices physicalDevices object: vk::raii::PhysicalDevice physicalDevice( std::move( physicalDevices[physicalDeviceIndex] ) ); +``` Note, that even though the actual `VkPhysicalDevice` owned by a `vk::raii::PhysicalDevice` is not a destructible resource, for consistency reasons a `vk::raii::PhysicalDevice` is a movable but not copyable object just like all the other vk::raii objects. @@ -124,47 +156,61 @@ Note, that even though the actual `VkPhysicalDevice` owned by a `vk::raii::Physi To create a `vk::raii::Device`, you just instantiate an object of that class: +```cpp // create a vk::raii::Device, given a vk::raii::PhysicalDevice physicalDevice and a vk::DeviceCreateInfo deviceCreateInfo vk::raii::Device device( physicalDevice, deviceCreateInfo ); +``` For each instantiated `vk::raii::Device`, the device-specific Vulkan function pointers are resolved. That is, for multi-device programs, you automatically use the correct device-specific function pointers, and organizing a multi-device program is simplified: +```cpp // create a vk::raii::Device per vk::raii::PhysicalDevice, given a vk::raii::PhysicalDevices physicalDevices, and a corresponding array of vk::DeviceCreateInfo deviceCreateInfos std::vector devices; for ( size_t i = 0; i < physicalDevices.size(); i++ ) { devices.push_back( vk::raii::Device( physicalDevices[i], deviceCreateInfos[i] ) ); } +``` ### 04 Create a vk::raii::CommandPool and vk::raii::CommandBuffers Creating a `vk::raii::CommandPool` is simply done by instantiating such an object: +```cpp // create a vk::raii::CommandPool, given a vk::raii::Device device and a vk::CommandPoolCreateInfo commandPoolCreateInfo vk::raii::CommandPool commandPool( device, commandPoolCreateInfo ); +``` As the number of `vk::raii::CommandBuffer`s to allocate from a `vk::raii::CommandPool` is given by the member `commandBufferCount` of a `vk::CommandBufferAllocateInfo` structure, it can't be instantiated as a single object. Instead you get a `vk::raii::CommandBuffers` (note the trailing 's' here!), which essentially is a `std::vector` of `vk::raii::CommandBuffer`s (note the trailing 's' here!). +```cpp // create a vk::raii::CommandBuffers, given a vk::raii::Device device and a vk::CommandBufferAllocateInfo commandBufferAllocateInfo vk::raii::CommandBuffers commandBuffers( device, commandBufferAllocateInfo ); +``` Note, that the `vk::CommandBufferAllocateInfo` holds a `vk::CommandPool` member `commandPool`. To assign that from a `vk::raii::CommandPool` you can use the `operator*()`: +```cpp // assign vk::CommandBufferAllocateInfo::commandPool, given a vk::raii::CommandPool commandPool commandBufferAllocateInfo.commandPool = *commandPool; +``` As a `vk::raii::CommandBuffers` is just a `std::vector`, you can access any specific `vk::raii:CommandBuffer` by indexing into that `std::vector`: +```cpp // start recording of the vk::raii::CommandBuffer with index commandBufferIndex, given a vk::raii::CommandBuffers commandBuffers commandBuffers[commandBufferIndex].begin(); +``` You can as well get one `vk::raii::CommandBuffer` out of a `vk::raii::CommandBuffers` like this: +```cpp // get the vk::raii::CommandBuffer with index commandBufferIndex, given a vk::raii::CommandBuffers commandBuffers vk::raii::CommandBuffer commandBuffer( std::move( commandBuffers[commandBufferIndex] ) ); // start recording commandBuffer.begin(); +``` There is one important thing to note, regarding command pool and command buffer handling. When you destroy a `VkCommandPool`, all `VkCommandBuffer`s allocated from that pool are implicitly freed. That automatism does not work well with the raii-approach. As the `vk::raii::CommandBuffers` are independent objects, they are not automatically destroyed when the `vk::raii::CommandPool` they are created from is destroyed. Instead, their destructor would try to use an invalid `vk::raii::CommandPool`, which obviously is an error. @@ -174,18 +220,23 @@ To handle that correctly, you have to make sure, that all `vk::raii::CommandBuff To initialize a swap chain, you first instantiate a `vk::raii::SwapchainKHR`: +```cpp // create a vk::raii::SwapchainKHR, given a vk::raii::Device device and a vk::SwapchainCreateInfoKHR swapChainCreateInfo vk::raii::SwapchainKHR swapchain( device, swapChainCreateInfo ); +``` You can get an array of presentable images associated with that swap chain: +```cpp // get presentable images associated with vk::raii::SwapchainKHR swapchain std::vector images = swapchain.getImages(); +``` Note, that you don't get `vk::raii::Image`s here, but plain `VkImage`s. They are controlled by the swap chain, and you should not destroy them. But you can create `vk::raii::ImageView`s out of them: +```cpp // create a vk::raii::ImageView per VkImage, given a vk::raii::Device sevice, a vector of VkImages images and a vk::ImageViewCreateInfo imageViewCreateInfo std::vector imageViews; for ( auto image : images ) @@ -193,17 +244,21 @@ But you can create `vk::raii::ImageView`s out of them: imageViewCreatInfo.image = image; imageViews.push_back( vk::raii::ImageView( device, imageViewCreateInfo ) ); } +``` ### 06 Create a Depth Buffer For a depth buffer, you need an image and some device memory and bind the memory to that image. That is, you first create a vk::raii::Image +```cpp // create a vk::raii::Image image, given a vk::raii::Device device and a vk::ImageCreateInfo imageCreateInfo // imageCreateInfo.usage should hold vk::ImageUsageFlagBits::eDepthStencilAttachment vk::raii::Image depthImage( device, imageCreateInfo ); +``` To create the corresponding vk::raii::DeviceMemory, you should determine appropriate values for the vk::MemoryAllocateInfo. That is, get the memory requirements from the pDepthImage, and determine some memoryTypeIndex from the pPhysicalDevice's memory properties, requiring vk::MemoryPropertyFlagBits::eDeviceLocal. +```cpp // get the vk::MemoryRequirements of the pDepthImage vk::MemoryRequirements memoryRequirements = depthImage.getMemoryRequirements(); @@ -214,22 +269,28 @@ To create the corresponding vk::raii::DeviceMemory, you should determine appropr // create a vk::raii::DeviceMemory depthDeviceMemory for the depth buffer vk::MemoryAllocateInfo memoryAllocateInfo( memoryRequirements.size, memoryTypeIndex ); vk::raii::DeviceMemory depthDeviceMemory( device, memoryAllocateInfo ); +``` Then you can bind the depth memory to the depth image +```cpp // bind the pDepthMemory to the pDepthImage depthImage.bindMemory( *depthDeviceMemory, 0 ); +``` Finally, you can create an image view on that depth buffer image +```cpp // create a vk::raii::ImageView depthView, given a vk::ImageViewCreateInfo imageViewCreateInfo imageViewCreateInfo.image = *depthImage; vk::raii::ImageView depthImageView( device, imageViewCreateInfo ); +``` ### 07 Create a Uniform Buffer Initializing a uniform buffer is very similar to initializing a depth buffer as described above. You just instantiate a `vk::raii::Buffer` instead of a `vk::raii::Image`, and a `vk::raii::DeviceMemory`, and bind the memory to the buffer: +```cpp // create a vk::raii::Buffer, given a vk::raii::Device device and a vk::BufferCreateInfo bufferCreateInfo vk::raii::Buffer uniformBuffer( device, bufferCreateInfo ); @@ -246,17 +307,20 @@ Initializing a uniform buffer is very similar to initializing a depth buffer as // bind the vk::raii::DeviceMemory uniformDeviceMemory to the vk::raii::Buffer uniformBuffer uniformBuffer.bindMemory( *uniformDeviceMemory, 0 ); +``` ### 08 Create a vk::raii::PipelineLayout To initialize a Pipeline Layout you just have to instantiate a `vk::raii::DescriptorSetLayout` and a `vk::raii::PipelineLayout` using that `vk::raii::DescriptorSetLayout`: +```cpp // create a vk::raii::DescriptorSetLayout, given a vk::raii::Device device and a vk::DescriptorSetLayoutCreateInfo descriptorSetLayoutCreateInfo vk::raii::DescriptorSetLayout descriptorSetLayout( device, descriptorSetLayoutCreateInfo ); // create a vk::raii::PipelineLayout, given a vk::raii::Device device and a vk::raii::DescriptorSetLayout vk::PipelineLayoutCreateInfo pipelineLayoutCreateInfo( {}, *descriptorSetLayout ); vk::raii::PipelineLayout pipelineLayout( device, pipelineLayoutCreateInfo ); +``` ### 09 Create a vk::raii::DescriptorPool and vk::raii::DescriptorSets @@ -266,9 +330,11 @@ As a `vk::raii::DescriptorSet` object destroys itself in the destructor, you hav That is, an instantiation of a `vk::raii::DescriptorPool` would look like this: +```cpp // create a vk::raii::DescriptorPool, given a vk::raii::Device device and a vk::DescriptorPoolCreateInfo descriptorPoolCreateInfo assert( descriptorPoolCreateInfo.flags & vk::DescriptorPoolCreateFlagBits::eFreeDescriptorSet ); vk::raii::DescriptorPool descriptorPool( device, descriptorPoolCreateInfo ); +``` To actually instantiate a `vk::raii::DescriptorSet`, you need a `vk::raii::DescriptorPool`, as just described, and a `vk::raii::DescriptorSetLayout`, similar to the one described in the previous section. @@ -276,33 +342,42 @@ Moreover, as the number of `vk::raii::DescriptorSet`s to allocate from a `vk::ra When you want to create just one `vk::raii::DescriptorSet`, using just one `vk::raii::DescriptorSetLayout`, your code might look like this: +```cpp // create a vk::raii::DescriptorSets, holding a single vk::raii::DescriptorSet, given a vk::raii::Device device, a vk::raii::DescriptorPool descriptorPool, and a single vk::raii::DescriptorSetLayout descriptorSetLayout vk::DescriptorSetAllocateInfo descriptorSetAllocateInfo( *descriptorPool, *descriptorSetLayout ); vk::raii::DescriptorSets pDescriptorSets( device, descriptorSetAllocateInfo ); +``` And, again similar to the vk::raii::CommandBuffers handling described above, you can get one `vk::raii::DescriptorSet` out of a `vk::raii::DescriptorSets` like this: +```cpp // get the vk::raii::DescriptorSet with index descriptorSetIndex, given a vk::raii::DescriptorSets descriptorSets vk::raii::DescriptorSet descriptorSet( std::move( descriptorSets[descriptorSetIndex] ) ); +``` ### 10 Create a vk::raii::RenderPass Creating a `vk::raii::RenderPass` is pretty simple, given you already have a meaningful `vk::RenderPassCreateInfo`: +```cpp // create a vk::raii::RenderPass, given a vk::raii::Device device and a vk::RenderPassCreateInfo renderPassCreateInfo vk::raii::RenderPass renderPass( device, renderPassCreateInfo ); +``` ### 11 Create a vk::raii::ShaderModule Again, creating a `vk::raii::ShaderModule` is simple, given a `vk::ShaderModuleCreateInfo` with some meaningful code: +```cpp // create a vk::raii::ShaderModule, given a vk::raii::Device device and a vk::ShaderModuleCreateInfo shaderModuleCreateInfo vk::raii::ShaderModule shaderModule( device, shaderModuleCreateInfo ); +``` ### 12 Create vk::raii::Framebuffers If you have a `std::vector` as described in chapter 05 above, with one view per `VkImage` that you got from a `vk::raii::SwapchainKHR`; and one `vk::raii::ImageView` as described in chapter 06 above, which is a view on a `vk::raii::Image`, that is supposed to be a depth buffer, you can create a `vk::raii::Framebuffer` per swapchain image. +```cpp // create a vector of vk::raii::Framebuffer, given a vk::raii::ImageView depthImageView, a vector of vk::raii::ImageView swapchainImageViews, a vk::raii::RenderPass renderPass, a vk::raii::Devie device, and some width and height // use the depth image view as the second attachment for each vk::raii::Framebuffer std::array attachments; @@ -315,11 +390,13 @@ If you have a `std::vector` as described in chapter 05 abov vk::FramebufferCreateInfo framebufferCreateInfo( {}, *renderPass, attachments, width, height, 1 ); framebuffers.push_back( vk::raii::Framebuffer( device, framebufferCreateInfo ) ); } +``` ### 13 Initialize a Vertex Buffer To initialize a vertex buffer, you essentially have to combine some of the pieces described in the chapters before. First, you need to create a `vk::raii::Buffer` and a `vk::raii::DeviceMemory` and bind them: +```cpp // create a vk::raii::Buffer vertexBuffer, given a vk::raii::Device device and some vertexData in host memory vk::BufferCreateInfo bufferCreateInfo( {}, sizeof( vertexData ), vk::BufferUsageFlagBits::eVertexBuffer ); vk::raii::Buffer vertexBuffer( device, bufferCreateInfo ); @@ -334,21 +411,27 @@ To initialize a vertex buffer, you essentially have to combine some of the piece // copy the vertex data into the vertexDeviceMemory ... +``` Later on, you can bind that vertex buffer to a command buffer: +```cpp // bind a complete single vk::raii::Buffer vertexBuffer as a vertex buffer, given a vk::raii::CommandBuffer commandBuffer commandBuffer.bindVertexBuffer( 0, { *vertexBuffer }, { 0 } ); +``` ### 14 Initialize a Graphics Pipeline Initializing a graphics pipeline is not very raii-specific. Just instantiate it, provided you have a valid vk::GraphicsPipelineCreateInfo: +```cpp // create a vk::raii::Pipeline, given a vk::raii::Device device and a vk::GraphicsPipelineCreateInfo graphicsPipelineCreateInfo vk::raii::Pipeline graphicsPipeline( device, graphicsPipelineCreateInfo ); +``` The only thing to keep in mind here is the dereferencing of raii handles, like `pipelineLayout` or `renderPass` in the `vk::GraphicsPipelineCreateInfo`: +```cpp vk::GraphicsPipelineCreateInfo graphicsPipelineCreateInfo( {}, // flags pipelineShaderStageCreateInfos, // stages @@ -364,6 +447,7 @@ The only thing to keep in mind here is the dereferencing of raii handles, like ` *pipelineLayout, // layout *renderPass // renderPass ); +``` ### 15 Drawing a Cube @@ -371,14 +455,18 @@ Finally, we get all those pieces together and draw a cube. To do so, you need a `vk::raii::Semaphore`: +```cpp // create a vk::raii::Semaphore, given a vk::raii::Device vk::raii::Semaphore imageAcquiredSemphore( device, vk::SemaphoreCreateInfo() ); +``` That semaphore can be used, to acquire the next imageIndex from the `vk::raii::SwapchainKHR` swapchain: +```cpp vk::Result result; uint32_t imageIndex; std::tie( result, imageIndex ) = swapchain.acquireNextImage( timeout, *imageAcquiredSemaphore ); +``` Note, `vk::raii::SwapchainKHR::acquireNextImage` returns a `std::pair`, that can nicely be assigned onto two separate values using std::tie(). @@ -386,6 +474,7 @@ And also note, the returned `vk::Result` can not only be `vk::Result::eSuccess`, Next, you can record some commands into a `vk::raii::CommandBuffer`: +```cpp // open the commandBuffer for recording commandBuffer.begin( {} ); @@ -414,27 +503,36 @@ Next, you can record some commands into a `vk::raii::CommandBuffer`: // end the render pass and stop recording commandBuffer.endRenderPass(); commandBuffer.end(); +``` To submit that command buffer to a `vk::raii::Queue` graphicsQueue you might want to use a `vk::raii::Fence` +```cpp // create a vk::raii::Fence, given a vk::raii::Device device vk::raii::Fence fence( device, vk::FenceCreateInfo() ); +``` With that, you can fill a `vk::SubmitInfo` and submit the command buffer +```cpp vk::PipelineStageFlags waitDestinationStageMask( vk::PipelineStageFlagBits::eColorAttachmentOutput ); vk::SubmitInfo submitInfo( *imageAcquiredSemaphore, waitDestinationStageMask, *commandBuffer ); graphicsQueue.submit( submitInfo, *fence ); +``` At some later point, you can wait for that submit being ready by waiting for the fence +```cpp while ( vk::Result::eTimeout == device.waitForFences( { *fence }, VK_TRUE, timeout ) ) ; +``` And finally, you can use the `vk::raii::Queue` presentQueue to, well, present that image +```cpp vk::PresentInfoKHR presentInfoKHR( nullptr, *swapChain, imageIndex ); result = presentQueue.presentKHR( presentInfoKHR ); +``` Note here, again, that `result` can not only be `vk::Result::eSuccess`, but also `vk::Result::eSuboptimalKHR`, which should be handled accordingly. From bf6fcbdad5f75918067c41e2ba1df5332a74e572 Mon Sep 17 00:00:00 2001 From: Stephan Seitz Date: Sat, 20 Jan 2024 16:55:01 +0100 Subject: [PATCH 3/3] ci: Add publish-doxygen.yml workflow --- .github/workflows/publish-doxygen.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 .github/workflows/publish-doxygen.yml diff --git a/.github/workflows/publish-doxygen.yml b/.github/workflows/publish-doxygen.yml new file mode 100644 index 000000000..f1d06b39e --- /dev/null +++ b/.github/workflows/publish-doxygen.yml @@ -0,0 +1,15 @@ +name: Doxygen GitHub Pages Deploy Action + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: DenverCoder1/doxygen-github-pages-action@v1.3.0 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + folder: html