From 048a9a6a0b5d59681c2c007156ea65b144494a12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 11 Mar 2021 13:14:05 +0100 Subject: [PATCH] Vk: add a short human-readable description to each Vulkan object. --- src/Magnum/Vk/CommandBuffer.h | 4 +++- src/Magnum/Vk/Device.h | 3 ++- src/Magnum/Vk/Fence.h | 3 ++- src/Magnum/Vk/Instance.h | 4 +++- src/Magnum/Vk/Memory.h | 1 + src/Magnum/Vk/Pipeline.h | 6 +++++- src/Magnum/Vk/Queue.h | 10 ++++++---- src/Magnum/Vk/Sampler.h | 3 ++- src/Magnum/Vk/Shader.h | 3 ++- 9 files changed, 26 insertions(+), 11 deletions(-) diff --git a/src/Magnum/Vk/CommandBuffer.h b/src/Magnum/Vk/CommandBuffer.h index 0fb488259..517d6addf 100644 --- a/src/Magnum/Vk/CommandBuffer.h +++ b/src/Magnum/Vk/CommandBuffer.h @@ -175,7 +175,9 @@ CORRADE_ENUMSET_OPERATORS(CommandBufferResetFlags) @brief Command buffer @m_since_latest -Wraps a @type_vk_keyword{CommandBuffer}. +Wraps a @type_vk_keyword{CommandBuffer}. Command buffers are used to record +all work done on a Vulkan device such as pipeline setup, draws, compute +dispatch or data transfers. @section Vk-CommandBuffer-allocation Command buffer allocation and recycling diff --git a/src/Magnum/Vk/Device.h b/src/Magnum/Vk/Device.h index 4b5ef53d5..84b4f8c45 100644 --- a/src/Magnum/Vk/Device.h +++ b/src/Magnum/Vk/Device.h @@ -54,7 +54,8 @@ namespace Implementation { @m_since_latest Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function -pointers. +pointers. A device provides an abstraction over a physical GPU or a CPU with +Vulkan capabilities. @section Vk-Device-creation Device creation diff --git a/src/Magnum/Vk/Fence.h b/src/Magnum/Vk/Fence.h index e695fe770..09e9558a9 100644 --- a/src/Magnum/Vk/Fence.h +++ b/src/Magnum/Vk/Fence.h @@ -45,7 +45,8 @@ namespace Magnum { namespace Vk { @brief Fence @m_since_latest -Wraps a @type_vk_keyword{Fence}. +Wraps a @type_vk_keyword{Fence}, which is used for synchronizing the CPU to a +queue execution done on a Vulkan device. @section Vk-Fence-creation Fence creation diff --git a/src/Magnum/Vk/Instance.h b/src/Magnum/Vk/Instance.h index 7e1eec334..dbbf3b0b8 100644 --- a/src/Magnum/Vk/Instance.h +++ b/src/Magnum/Vk/Instance.h @@ -52,7 +52,9 @@ namespace Implementation { @m_since_latest Wraps a @type_vk_keyword{Instance} and stores instance-specific Vulkan function -pointers. +pointers. An instance provides device enumeration and management of Vulkan +layers that enable additional functionality such as command validation or +tracing / debugging. @section Vk-Instance-creation Instance creation diff --git a/src/Magnum/Vk/Memory.h b/src/Magnum/Vk/Memory.h index 2e4920dd7..c4042598d 100644 --- a/src/Magnum/Vk/Memory.h +++ b/src/Magnum/Vk/Memory.h @@ -119,6 +119,7 @@ MAGNUM_VK_EXPORT Debug& operator<<(Debug& debug, MemoryFlags value); @m_since_latest Wraps a @type_vk_keyword{DeviceMemory} and handles its allocation and mapping. +Device memory is backing Vulkan buffers, images and other objects. @section Vk-Memory-allocation Memory allocation diff --git a/src/Magnum/Vk/Pipeline.h b/src/Magnum/Vk/Pipeline.h index 694958db8..7595bafc5 100644 --- a/src/Magnum/Vk/Pipeline.h +++ b/src/Magnum/Vk/Pipeline.h @@ -76,7 +76,11 @@ MAGNUM_VK_EXPORT Debug& operator<<(Debug& debug, PipelineBindPoint value); @brief Pipeline @m_since_latest -Wraps a @type_vk_keyword{Pipeline}. +Wraps a @type_vk_keyword{Pipeline}. A pipeline contains all state for execution +of either rasterization commands or a compute dispatch and among other things +contains shaders, pipeline layout specifying how uniform buffers, samplers and +other resources are bound, or a render pass describing how framebuffer +attachments get used. @section Vk-Pipeline-creation-rasterization Rasterization pipeline creation diff --git a/src/Magnum/Vk/Queue.h b/src/Magnum/Vk/Queue.h index 97240bc6a..7664f1cfd 100644 --- a/src/Magnum/Vk/Queue.h +++ b/src/Magnum/Vk/Queue.h @@ -43,10 +43,12 @@ namespace Magnum { namespace Vk { @brief Queue @m_since_latest -Wraps a @type_vk_keyword{Queue}. See @ref Vk-Device-creation for information -about how queues are created and retrieved from a device and -@ref Vk-CommandBuffer-usage for an overview of recording and submitting -command buffers to a queue. +Wraps a @type_vk_keyword{Queue}, which is used to submit command buffers for +execution on the device. + +See @ref Vk-Device-creation for information about how queues are created and +retrieved from a device and @ref Vk-CommandBuffer-usage for an overview of +recording and submitting command buffers to a queue. @see @ref DeviceCreateInfo::addQueues(), @ref submit() */ class MAGNUM_VK_EXPORT Queue { diff --git a/src/Magnum/Vk/Sampler.h b/src/Magnum/Vk/Sampler.h index 26ca1d36c..b9ff8e237 100644 --- a/src/Magnum/Vk/Sampler.h +++ b/src/Magnum/Vk/Sampler.h @@ -42,7 +42,8 @@ namespace Magnum { namespace Vk { @brief Sampler @m_since_latest -Wraps a @type_vk_keyword{Sampler}. +Wraps a @type_vk_keyword{Sampler}, which describes how shaders perform +texturing. @section Vk-Sampler-creation Sampler creation diff --git a/src/Magnum/Vk/Shader.h b/src/Magnum/Vk/Shader.h index 5b0ee47fe..100ae29f3 100644 --- a/src/Magnum/Vk/Shader.h +++ b/src/Magnum/Vk/Shader.h @@ -129,7 +129,8 @@ CORRADE_ENUMSET_OPERATORS(ShaderStages) @brief Shader @m_since_latest -Wraps a @type_vk_keyword{ShaderModule}. +Wraps a @type_vk_keyword{ShaderModule}, which contains a SPIR-V binary with one +or more shader entrypoints. @section Vk-Shader-creation Shader creation