From 98a69fc5683957576b0db0e8fbc2d120f105e7ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 11 Dec 2020 12:20:19 +0100 Subject: [PATCH] Vk: rethink "creation" docs. Although the APIs don't look like that right now, in many cases creation of a particular Vulkan object isn't all that's there for it. So change the section names from a generic "Usage" to "Creation". --- doc/snippets/MagnumVk.cpp | 72 ++++++++++++++--------------- src/Magnum/Vk/Buffer.h | 12 ++--- src/Magnum/Vk/CommandPool.h | 10 ++-- src/Magnum/Vk/Device.h | 12 ++--- src/Magnum/Vk/DeviceProperties.h | 4 +- src/Magnum/Vk/ExtensionProperties.h | 6 +-- src/Magnum/Vk/Image.h | 12 ++--- src/Magnum/Vk/Instance.h | 13 +++--- src/Magnum/Vk/LayerProperties.h | 5 +- src/Magnum/Vk/Memory.h | 8 ++-- src/Magnum/Vk/RenderPass.h | 20 ++++---- src/Magnum/Vk/Shader.h | 8 ++-- 12 files changed, 92 insertions(+), 90 deletions(-) diff --git a/doc/snippets/MagnumVk.cpp b/doc/snippets/MagnumVk.cpp index 3184110df..0410e3020 100644 --- a/doc/snippets/MagnumVk.cpp +++ b/doc/snippets/MagnumVk.cpp @@ -121,17 +121,17 @@ Vk::Device device{instance, std::move(info)}; { Vk::Device device{NoCreate}; -/* [Buffer-usage] */ +/* [Buffer-creation] */ Vk::Buffer buffer{device, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024}, Vk::MemoryFlag::DeviceLocal }; -/* [Buffer-usage] */ +/* [Buffer-creation] */ } { Vk::Device device{NoCreate}; -/* [Buffer-usage-custom-allocation] */ +/* [Buffer-creation-custom-allocation] */ Vk::Buffer buffer{device, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024}, NoAllocate @@ -145,40 +145,40 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{ }}; buffer.bindMemory(memory, 0); -/* [Buffer-usage-custom-allocation] */ +/* [Buffer-creation-custom-allocation] */ } { -/* [CommandPool-usage] */ +/* [CommandPool-creation] */ Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::CommandPool graphicsCommandPool{device, Vk::CommandPoolCreateInfo{ device.properties().pickQueueFamily(Vk::QueueFlag::Graphics) }}; -/* [CommandPool-usage] */ +/* [CommandPool-creation] */ -/* [CommandPool-usage-allocate] */ +/* [CommandPool-allocation] */ Vk::CommandBuffer commandBuffer = graphicsCommandPool.allocate(); // fill the buffer, submit … -/* [CommandPool-usage-allocate] */ +/* [CommandPool-allocation] */ } { Vk::Instance instance; -/* [Device-usage-construct-queue] */ +/* [Device-creation-construct-queue] */ Vk::Queue queue{NoCreate}; Vk::Device device{instance, Vk::DeviceCreateInfo{Vk::pickDevice(instance)} .addQueues(Vk::QueueFlag::Graphics, {0.0f}, {queue}) }; -/* [Device-usage-construct-queue] */ +/* [Device-creation-construct-queue] */ } { Vk::Instance instance; Vk::DeviceProperties properties{NoCreate}; using namespace Containers::Literals; -/* [Device-usage-extensions] */ +/* [Device-creation-extensions] */ Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)} DOXYGEN_IGNORE() .addEnabledExtensions< // predefined extensions @@ -186,13 +186,13 @@ Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)} Vk::Extensions::KHR::device_group>() .addEnabledExtensions({"VK_NV_mesh_shader"_s}) // can be plain strings too }; -/* [Device-usage-extensions] */ +/* [Device-creation-extensions] */ } { Vk::Instance instance; using namespace Containers::Literals; -/* [Device-usage-check-supported] */ +/* [Device-creation-check-supported] */ Vk::DeviceProperties properties = Vk::pickDevice(instance); Vk::ExtensionProperties extensions = properties.enumerateExtensionProperties(); @@ -202,7 +202,7 @@ if(extensions.isSupported()) if(extensions.isSupported("VK_NV_mesh_shader"_s)) info.addEnabledExtensions({"VK_NV_mesh_shader"_s}); DOXYGEN_IGNORE() -/* [Device-usage-check-supported] */ +/* [Device-creation-check-supported] */ } { @@ -246,17 +246,17 @@ if(device.isExtensionEnabled()) { { Vk::Device device{NoCreate}; -/* [Image-usage] */ +/* [Image-creation] */ Vk::Image image{device, Vk::ImageCreateInfo2D{ Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1 }, Vk::MemoryFlag::DeviceLocal }; -/* [Image-usage] */ +/* [Image-creation] */ } { Vk::Device device{NoCreate}; -/* [Image-usage-custom-allocation] */ +/* [Image-creation-custom-allocation] */ Vk::Image image{device, Vk::ImageCreateInfo2D{ Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1 }, NoAllocate @@ -270,34 +270,34 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{ }}; image.bindMemory(memory, 0); -/* [Image-usage-custom-allocation] */ +/* [Image-creation-custom-allocation] */ } { int argc{}; const char** argv{}; -/* [Instance-usage-minimal] */ +/* [Instance-creation-minimal] */ Vk::Instance instance{{argc, argv}}; -/* [Instance-usage-minimal] */ +/* [Instance-creation-minimal] */ } { int argc{}; const char** argv{}; -/* [Instance-usage] */ +/* [Instance-creation] */ using namespace Containers::Literals; Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv} .setApplicationInfo("My Vulkan Application"_s, Vk::version(1, 2, 3)) }; -/* [Instance-usage] */ +/* [Instance-creation] */ } { int argc{}; const char** argv{}; using namespace Containers::Literals; -/* [Instance-usage-layers-extensions] */ +/* [Instance-creation-layers-extensions] */ Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv} DOXYGEN_IGNORE() .addEnabledLayers({"VK_LAYER_KHRONOS_validation"_s}) @@ -306,14 +306,14 @@ Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv} Vk::Extensions::KHR::external_fence_capabilities>() .addEnabledExtensions({"VK_KHR_xcb_surface"_s}) // can be plain strings too }; -/* [Instance-usage-layers-extensions] */ +/* [Instance-creation-layers-extensions] */ } { int argc{}; const char** argv{}; using namespace Containers::Literals; -/* [Instance-usage-check-supported] */ +/* [Instance-creation-check-supported] */ /* Query layer and extension support */ Vk::LayerProperties layers = Vk::enumerateLayerProperties(); Vk::InstanceExtensionProperties extensions = @@ -329,7 +329,7 @@ if(extensions.isSupported()) DOXYGEN_IGNORE() Vk::Instance instance{info}; -/* [Instance-usage-check-supported] */ +/* [Instance-creation-check-supported] */ } { @@ -375,7 +375,7 @@ if(instance.isExtensionEnabled()) { { Vk::Device device{NoCreate}; Containers::ArrayView vertexData, indexData; -/* [Memory-usage] */ +/* [Memory-allocation] */ /* Create buffers without allocating them */ Vk::Buffer vertices{device, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, vertexData.size()}, @@ -404,7 +404,7 @@ const UnsignedLong indicesOffset = verticesRequirements.alignedSize(alignment); /* Bind the respective sub-ranges to the buffers */ vertices.bindMemory(memory, 0); indices.bindMemory(memory, indicesOffset); -/* [Memory-usage] */ +/* [Memory-allocation] */ /* [Memory-mapping] */ /* The memory gets unmapped again at the end of scope */ @@ -419,7 +419,7 @@ indices.bindMemory(memory, indicesOffset); { Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; -/* [RenderPass-usage] */ +/* [RenderPass-creation] */ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} .setAttachments({ VK_FORMAT_R8G8B8A8_SRGB, @@ -430,12 +430,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} .setDepthStencilAttachment(1) ) }; -/* [RenderPass-usage] */ +/* [RenderPass-creation] */ } { Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; -/* [RenderPass-usage-load-store] */ +/* [RenderPass-creation-load-store] */ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} .setAttachments({ {VK_FORMAT_R8G8B8A8_SRGB, Vk::AttachmentLoadOperation::Clear, {}}, @@ -443,12 +443,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} }) DOXYGEN_IGNORE() }; -/* [RenderPass-usage-load-store] */ +/* [RenderPass-creation-load-store] */ } { Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; -/* [RenderPass-usage-layout] */ +/* [RenderPass-creation-layout] */ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} .setAttachments({ {VK_FORMAT_R8G8B8A8_SRGB, @@ -465,12 +465,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} .setDepthStencilAttachment({1, Vk::ImageLayout::ColorAttachment}) ) }; -/* [RenderPass-usage-layout] */ +/* [RenderPass-creation-layout] */ } { Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; -/* [Shader-usage] */ +/* [Shader-creation] */ Vk::ShaderCreateInfo info{ CORRADE_INTERNAL_ASSERT_EXPRESSION(Utility::Directory::read("shader.spv")) }; @@ -478,7 +478,7 @@ Vk::ShaderCreateInfo info{ DOXYGEN_IGNORE() Vk::Shader shader{device, info}; -/* [Shader-usage] */ +/* [Shader-creation] */ } { diff --git a/src/Magnum/Vk/Buffer.h b/src/Magnum/Vk/Buffer.h index e3f71d0d6..70952c1bc 100644 --- a/src/Magnum/Vk/Buffer.h +++ b/src/Magnum/Vk/Buffer.h @@ -97,8 +97,8 @@ CORRADE_ENUMSET_OPERATORS(BufferUsages) @brief Buffer creation info @m_since_latest -Wraps a @type_vk_keyword{BufferCreateInfo}. See @ref Buffer for usage -information. +Wraps a @type_vk_keyword{BufferCreateInfo}. See +@ref Vk-Buffer-creation "Buffer creation" for usage information. */ class MAGNUM_VK_EXPORT BufferCreateInfo { public: @@ -178,25 +178,25 @@ CORRADE_ENUMSET_OPERATORS(BufferCreateInfo::Flags) Wraps a @type_vk_keyword{Buffer} and its memory. -@section Vk-Buffer-usage Basic usage +@section Vk-Buffer-creation Buffer creation Pass a @ref BufferCreateInfo with desired usage and size to the @ref Buffer constructor together with specifying @ref MemoryFlags for the allocation. -@snippet MagnumVk.cpp Buffer-usage +@snippet MagnumVk.cpp Buffer-creation @attention At this point, a dedicated allocation is used, subsequently accessible through @ref dedicatedMemory(). This behavior may change in the future. -@section Vk-Buffer-usage-custom-allocation Custom memory allocation +@subsection Vk-Buffer-creation-custom-allocation Custom memory allocation Using @ref Buffer(Device&, const BufferCreateInfo&, NoAllocateT), the buffer will be created without any memory bound. Buffer memory requirements can be then queried using @ref memoryRequirements() and an allocated memory bound with @ref bindMemory(). See @ref Memory for further details about memory allocation. -@snippet MagnumVk.cpp Buffer-usage-custom-allocation +@snippet MagnumVk.cpp Buffer-creation-custom-allocation Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer ownership of the @ref Memory to the buffer instance, making it subsequently diff --git a/src/Magnum/Vk/CommandPool.h b/src/Magnum/Vk/CommandPool.h index 2d2b5c38f..2570a61d7 100644 --- a/src/Magnum/Vk/CommandPool.h +++ b/src/Magnum/Vk/CommandPool.h @@ -44,8 +44,8 @@ namespace Magnum { namespace Vk { @brief Command pool creation info @m_since_latest -Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See @ref CommandPool for usage -information. +Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See +@ref Vk-CommandPool-creation "Command pool creation" for usage information. */ class MAGNUM_VK_EXPORT CommandPoolCreateInfo { public: @@ -180,20 +180,20 @@ CORRADE_ENUMSET_OPERATORS(CommandPoolResetFlags) Wraps a @type_vk_keyword{CommandPool} and handles allocation of @ref CommandBuffer "CommandBuffer"s. -@section Vk-CommandPool-usage Usage +@section Vk-CommandPool-creation Command pool creation and buffer allocation A @ref CommandPoolCreateInfo doesn't need many inputs --- the only required is queue family index coming from @ref DeviceProperties of the device it's created on: -@snippet MagnumVk.cpp CommandPool-usage +@snippet MagnumVk.cpp CommandPool-creation After that, you can allocate command buffers as follows. The command buffers are freed at the end of their instance lifetime, you can also put all allocated buffers back to initial state by calling @ref reset(), or alternatively reset each buffer separately using @ref CommandBuffer::reset(). -@snippet MagnumVk.cpp CommandPool-usage-allocate +@snippet MagnumVk.cpp CommandPool-allocation */ class MAGNUM_VK_EXPORT CommandPool { public: diff --git a/src/Magnum/Vk/Device.h b/src/Magnum/Vk/Device.h index 484d5961c..f8ca10a2d 100644 --- a/src/Magnum/Vk/Device.h +++ b/src/Magnum/Vk/Device.h @@ -53,8 +53,8 @@ namespace Implementation { @brief Device creation info @m_since_latest -Wraps a @type_vk_keyword{DeviceCreateInfo}. See @ref Device for usage -information. +Wraps a @type_vk_keyword{DeviceCreateInfo}. See +@ref Vk-Device-creation "Device creation" for usage information. */ class MAGNUM_VK_EXPORT DeviceCreateInfo { public: @@ -294,7 +294,7 @@ CORRADE_ENUMSET_OPERATORS(DeviceCreateInfo::Flags) Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function pointers. -@section Vk-Device-usage Usage +@section Vk-Device-creation Device creation With an @ref Instance ready, a device has to be picked first. Commonly it's done by calling @ref pickDevice() and letting the library choose. This @@ -311,7 +311,7 @@ That's done by creating an empty @ref Queue instance and then referencing it from @ref DeviceCreateInfo::addQueues(). After the device is constructed, the queue gets populated and is ready to be used. -@snippet MagnumVk.cpp Device-usage-construct-queue +@snippet MagnumVk.cpp Device-creation-construct-queue In the above snippet, we requested a graphics queue via a convenience API. The information about available queues and other device properties is stored in a @@ -326,12 +326,12 @@ both string names as well as predefined *device* extensions from the @ref Extensions namespace. Later on, presence of predefined extensions can be checked with @ref isExtensionEnabled(). -@snippet MagnumVk.cpp Device-usage-extensions +@snippet MagnumVk.cpp Device-creation-extensions Usually you'll be first checking for extension availability instead, which is again accessible through the @ref DeviceProperties instance: -@snippet MagnumVk.cpp Device-usage-check-supported +@snippet MagnumVk.cpp Device-creation-check-supported With both @ref Instance and @ref Device created, you can proceed to setting up a @ref CommandPool. diff --git a/src/Magnum/Vk/DeviceProperties.h b/src/Magnum/Vk/DeviceProperties.h index 93dce9eec..a6853bb31 100644 --- a/src/Magnum/Vk/DeviceProperties.h +++ b/src/Magnum/Vk/DeviceProperties.h @@ -253,8 +253,8 @@ of @type_vk_keyword{PhysicalDeviceProperties}, @type_vk_keyword{PhysicalDeviceQueueFamilyProperties} and @type_vk_keyword{PhysicalDeviceMemoryProperties}. -See the @ref Vk-Device-usage "Device class docs" for an example of using this -class for enumerating available devices and picking one of them. +See the @ref Vk-Device-creation "Device creation docs" for an example of using +this class for enumerating available devices and picking one of them. @see @ref pickDevice(), @ref enumerateDevices() */ diff --git a/src/Magnum/Vk/ExtensionProperties.h b/src/Magnum/Vk/ExtensionProperties.h index 28a27b8ee..99aaaf8fc 100644 --- a/src/Magnum/Vk/ExtensionProperties.h +++ b/src/Magnum/Vk/ExtensionProperties.h @@ -48,9 +48,9 @@ namespace Magnum { namespace Vk { Provides a searchable container of Vulkan device extensions enumerated with @ref DeviceProperties::enumerateExtensionProperties(). -See the @ref Vk-Device-usage "Device class docs" for an example of using this -class for checking available extensions before enabling them on a device. See -@ref Vk-Instance-usage "Instance class docs" for the same but using +See the @ref Vk-Device-creation "Device creation docs" for an example of using +this class for checking available extensions before enabling them on a device. +See @ref Vk-Instance-creation "Instance creation docs" for the same but using @ref InstanceExtensionProperties. @see @type_vk_keyword{ExtensionProperties} diff --git a/src/Magnum/Vk/Image.h b/src/Magnum/Vk/Image.h index f5617cee2..5f332694d 100644 --- a/src/Magnum/Vk/Image.h +++ b/src/Magnum/Vk/Image.h @@ -225,8 +225,8 @@ enum class ImageLayout: Int { @brief Image creation info @m_since_latest -Wraps a @type_vk_keyword{ImageCreateInfo}. See @ref Image for usage -information. +Wraps a @type_vk_keyword{ImageCreateInfo}. See +@ref Vk-Image-creation "Image creation" for usage information. @see @ref ImageCreateInfo1D, @ref ImageCreateInfo2D, @ref ImageCreateInfo3D, @ref ImageCreateInfo1DArray, @ref ImageCreateInfo2DArray, @ref ImageCreateInfoCubeMap, @ref ImageCreateInfoCubeMapArray @@ -525,26 +525,26 @@ class ImageCreateInfoCubeMapArray: public ImageCreateInfo { Wraps a @type_vk_keyword{Image} and its memory. -@section Vk-Image-usage Basic usage +@section Vk-Image-creation Image creation Pass one of the @ref ImageCreateInfo subclasses depending on desired image type with desired usage, format, size and other propoerties to the @ref Image constructor together with specifying @ref MemoryFlags for memory allocation. -@snippet MagnumVk.cpp Image-usage +@snippet MagnumVk.cpp Image-creation @attention At this point, a dedicated allocation is used, subsequently accessible through @ref dedicatedMemory(). This behavior may change in the future. -@section Vk-Image-usage-custom-allocation Custom memory allocation +@subsection Vk-Image-creation-custom-allocation Custom memory allocation Using @ref Image(Device&, const ImageCreateInfo&, NoAllocateT), the image will be created without any memory attached. Image memory requirements can be subsequently queried using @ref memoryRequirements() and an allocated memory bound with @ref bindMemory(). See @ref Memory for further details about memory allocation. -@snippet MagnumVk.cpp Image-usage-custom-allocation +@snippet MagnumVk.cpp Image-creation-custom-allocation Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer ownership of the @ref Memory to the image instance, making it subsequently diff --git a/src/Magnum/Vk/Instance.h b/src/Magnum/Vk/Instance.h index 0c01980fc..684d0b485 100644 --- a/src/Magnum/Vk/Instance.h +++ b/src/Magnum/Vk/Instance.h @@ -52,7 +52,8 @@ namespace Implementation { @m_since_latest Wraps a @type_vk_keyword{InstanceCreateInfo} and -@type_vk_keyword{ApplicationInfo}. See @ref Instance for usage information. +@type_vk_keyword{ApplicationInfo}. See +@ref Vk-Instance-creation "Instance creation" for usage information. */ class MAGNUM_VK_EXPORT InstanceCreateInfo { public: @@ -244,19 +245,19 @@ CORRADE_ENUMSET_OPERATORS(InstanceCreateInfo::Flags) Wraps a @type_vk_keyword{Instance} and stores instance-specific Vulkan function pointers. -@section Vk-Instance-usage Usage +@section Vk-Instance-creation Instance creation While an @ref Instance can be default-constructed without much fuss, it's recommended to pass a @ref InstanceCreateInfo with at least the `argc` / `argv` pair, which allows you to use various `--magnum-*` @ref Vk-Instance-command-line "command-line options": -@snippet MagnumVk.cpp Instance-usage-minimal +@snippet MagnumVk.cpp Instance-creation-minimal In addition to command-line arguments, setting application info isn't strictly required either, but may be beneficial for the driver: -@snippet MagnumVk.cpp Instance-usage +@snippet MagnumVk.cpp Instance-creation @@ -277,14 +278,14 @@ both string names as well as predefined *instance* extensions from the @ref Extensions namespace. Later on, presence of predefined extensions can be checked with @ref isExtensionEnabled(). -@snippet MagnumVk.cpp Instance-usage-layers-extensions +@snippet MagnumVk.cpp Instance-creation-layers-extensions However, with the above approach, if any layer or extension isn't available, the instance creation will abort. The recommended workflow is thus first checking layer and extension availability using @ref enumerateLayerProperties() and @ref enumerateInstanceExtensionProperties(): -@snippet MagnumVk.cpp Instance-usage-check-supported +@snippet MagnumVk.cpp Instance-creation-check-supported Next step after creating a Vulkan instance is picking and creating a @ref Device. diff --git a/src/Magnum/Vk/LayerProperties.h b/src/Magnum/Vk/LayerProperties.h index a3b669f4e..bf9534773 100644 --- a/src/Magnum/Vk/LayerProperties.h +++ b/src/Magnum/Vk/LayerProperties.h @@ -51,8 +51,9 @@ and the assumption is that no drivers currently use rely on these anymore. See [§ 37.3.1](https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/chap38.html#extendingvulkan-layers-devicelayerdeprecation) for more information. -See the @ref Vk-Instance-usage "Instance class docs" for an example of using -this class for checking available layers before enabling them on an instance. +See the @ref Vk-Instance-creation "Instance creation docs" for an example of +using this class for checking available layers before enabling them on an +instance. @see @ref ExtensionProperties, @ref enumerateInstanceExtensionProperties(), @type_vk_keyword{LayerProperties} diff --git a/src/Magnum/Vk/Memory.h b/src/Magnum/Vk/Memory.h index 483cc2da5..407794f8c 100644 --- a/src/Magnum/Vk/Memory.h +++ b/src/Magnum/Vk/Memory.h @@ -201,8 +201,8 @@ class MAGNUM_VK_EXPORT MemoryRequirements { @brief Memory allocation info @m_since_latest -Wraps a @type_vk_keyword{MemoryAllocateInfo}. See @ref Memory for usage -information. +Wraps a @type_vk_keyword{MemoryAllocateInfo}. See +@ref Vk-Memory-allocation "Memory allocation" for usage information. */ class MAGNUM_VK_EXPORT MemoryAllocateInfo { public: @@ -262,7 +262,7 @@ class MAGNUM_VK_EXPORT MemoryAllocateInfo { Wraps a @type_vk_keyword{DeviceMemory} and handles its allocation and mapping. -@section Vk-Memory-usage Usage +@section Vk-Memory-allocation Memory allocation By default, the memory will get allocated for you during the creation of @ref Buffer, @ref Image and other objects. In case you want to handle the @@ -283,7 +283,7 @@ tag to constructors of these objects), it consists of these steps: The following example allocates a single block memory for two buffers, one containing vertex and the other index data: -@snippet MagnumVk.cpp Memory-usage +@snippet MagnumVk.cpp Memory-allocation @section Vk-Memory-mapping Memory mapping diff --git a/src/Magnum/Vk/RenderPass.h b/src/Magnum/Vk/RenderPass.h index 298364c90..36f21e668 100644 --- a/src/Magnum/Vk/RenderPass.h +++ b/src/Magnum/Vk/RenderPass.h @@ -800,8 +800,8 @@ class MAGNUM_VK_EXPORT SubpassDependency { @m_since_latest Wraps a @type_vk_keyword{RenderPassCreateInfo2} / -@type_vk_keyword{RenderPassCreateInfo}. See @ref RenderPass for usage -information. +@type_vk_keyword{RenderPassCreateInfo}. See +@ref Vk-RenderPass-creation "Render pass creation" for usage information. @section Vk-RenderPassCreateInfo-compatibility Compatibility with VkRenderPassCreateInfo @@ -1011,12 +1011,12 @@ descriptions, subpasses and their dependencies. The render pass description is independent of any specific image views used for attachments, these two are connected together in a framebuffer. -@section Vk-RenderPass-usage Basic usage +@section Vk-RenderPass-creation Render pass creation -A render pass is a set of attachments, described by @ref AttachmentDescription -instances, subpasses operating on those attachments, described by a -@ref SubpassDescription using @ref AttachmentReference instances, and subpass -dependencies, described by @ref SubpassDependency. +@ref RenderPassCreateInfo is a set of attachments, described by +@ref AttachmentDescription instances, subpasses operating on those attachments, +described by a @ref SubpassDescription using @ref AttachmentReference +instances, and subpass dependencies, described by @ref SubpassDependency. A render pass has to have at least one subpass. It's common to have just one subpass but while the subpass isn't required to operate on any attachments, @@ -1028,7 +1028,7 @@ on a color and a combined depth/stencil attachment. The main parameter an @ref RenderPassCreateInfo::setAttachments() array, and it's actually @ref AttachmentReference instances: -@snippet MagnumVk.cpp RenderPass-usage +@snippet MagnumVk.cpp RenderPass-creation The above again does a conservative estimate that you'd want to preserve the attachment contents between render passes. Usually you'd want to clear the @@ -1039,7 +1039,7 @@ passing appropriate @ref AttachmentLoadOperation / conveniently the zero values, which means you can use @cpp {} @ce instead of typing them out in full: -@snippet MagnumVk.cpp RenderPass-usage-load-store +@snippet MagnumVk.cpp RenderPass-creation-load-store Vulkan makes heavy use of image layouts for optimal memory access and in all the cases above, @ref ImageLayout::General is used as an implicit @@ -1051,7 +1051,7 @@ more optimal by explicitly specifying both a concrete initial and final layout in the @ref AttachmentDescription constructors and in each @link AttachmentReference @endlink: -@snippet MagnumVk.cpp RenderPass-usage-layout +@snippet MagnumVk.cpp RenderPass-creation-layout */ class MAGNUM_VK_EXPORT RenderPass { public: diff --git a/src/Magnum/Vk/Shader.h b/src/Magnum/Vk/Shader.h index 8bf9230cf..34f5f5e0b 100644 --- a/src/Magnum/Vk/Shader.h +++ b/src/Magnum/Vk/Shader.h @@ -44,8 +44,8 @@ namespace Magnum { namespace Vk { @brief Shader creation info @m_since_latest -Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See @ref Shader for usage -information. +Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See +@ref Vk-Shader-creation "Shader creation" for usage information. */ class MAGNUM_VK_EXPORT ShaderCreateInfo { public: @@ -173,7 +173,7 @@ CORRADE_ENUMSET_OPERATORS(ShaderCreateInfo::Flags) Wraps a @type_vk_keyword{ShaderModule}. -@section Vk-Shader-usage Usage +@section Vk-Shader-creation Shader creation The @ref ShaderCreateInfo structure takes a single required parameter, which is the SPIR-V binary. Besides accepting a @ref Corrade::Containers::ArrayView, @@ -182,7 +182,7 @@ to which any container is convertible, it can also take ownership of a keeping a loaded file in scope until it's consumed by the @ref Shader constructor: -@snippet MagnumVk.cpp Shader-usage +@snippet MagnumVk.cpp Shader-creation */ class MAGNUM_VK_EXPORT Shader { public: