diff --git a/src/Magnum/Vk/BufferCreateInfo.h b/src/Magnum/Vk/BufferCreateInfo.h index b97b85668..59e3a277d 100644 --- a/src/Magnum/Vk/BufferCreateInfo.h +++ b/src/Magnum/Vk/BufferCreateInfo.h @@ -49,10 +49,19 @@ Wraps a @type_vk_keyword{BufferUsageFlagBits}. @m_enum_values_as_keywords */ enum class BufferUsage: UnsignedInt { - /** Source of a transfer command */ + /** + * Source of a transfer command. + * @see @ref CommandBuffer::copyBuffer(), + * @ref CommandBuffer::copyBufferToImage() + */ TransferSource = VK_BUFFER_USAGE_TRANSFER_SRC_BIT, - /** Destination of a transfer command */ + /** + * Destination of a transfer command. + * @see @ref CommandBuffer::fillBuffer(), + * @ref CommandBuffer::copyBuffer(), + * @ref CommandBuffer::copyImageToBuffer() + */ TransferDestination = VK_BUFFER_USAGE_TRANSFER_DST_BIT, /** Suitable for creating a uniform texel buffer view */ @@ -67,10 +76,16 @@ enum class BufferUsage: UnsignedInt { /** Suitable for a storage buffer */ StorageBuffer = VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, - /** Suitable for an index buffer */ + /** + * Suitable for an index buffer. + * @see @ref Mesh::setIndexBuffer() + */ IndexBuffer = VK_BUFFER_USAGE_INDEX_BUFFER_BIT, - /** Suitable for a vertex buffer */ + /** + * Suitable for a vertex buffer. + * @see @ref Mesh::addVertexBuffer() + */ VertexBuffer = VK_BUFFER_USAGE_VERTEX_BUFFER_BIT, /** Suitable for a indirect draw buffer */ diff --git a/src/Magnum/Vk/Image.h b/src/Magnum/Vk/Image.h index 23d1a9435..138646647 100644 --- a/src/Magnum/Vk/Image.h +++ b/src/Magnum/Vk/Image.h @@ -47,6 +47,7 @@ namespace Implementation { struct DeviceState; } @brief Image layout @m_since_latest +Wraps @type_vk_keyword{ImageLayout}. @see @ref ImageCreateInfo @m_enum_values_as_keywords */ @@ -97,6 +98,8 @@ enum class ImageLayout: Int { * While this layout will always work, it's recommended to pick a * stricter layout where appropriate, as it may result in better * performance. + * + * @see @ref ImageUsage::Storage */ General = VK_IMAGE_LAYOUT_GENERAL, @@ -109,6 +112,7 @@ enum class ImageLayout: Int { * usable for anything else. * * Only valid for images created with @ref ImageUsage::ColorAttachment. + * @see @ref SubpassDescription::setColorAttachments() */ ColorAttachment = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, @@ -118,6 +122,7 @@ enum class ImageLayout: Int { * * Only valid for images created with * @ref ImageUsage::DepthStencilAttachment. + * @see @ref SubpassDescription::setDepthStencilAttachment() */ DepthStencilAttachment = VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, @@ -136,6 +141,8 @@ enum class ImageLayout: Int { * anything else. * * Only valid for images created with @ref ImageUsage::TransferSource. + * @see @ref CommandBuffer::copyImage(), + * @ref CommandBuffer::copyImageToBuffer() */ TransferSource = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, @@ -144,6 +151,12 @@ enum class ImageLayout: Int { * anything else. * * Only valid for images created with @ref ImageUsage::TransferDestination. + * @see @ref CommandBuffer::clearColorImage(), + * @ref CommandBuffer::clearDepthStencilImage(), + * @ref CommandBuffer::clearDepthImage(), + * @ref CommandBuffer::clearStencilImage(), + * @ref CommandBuffer::copyImage(), + * @ref CommandBuffer::copyBufferToImage() */ TransferDestination = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, diff --git a/src/Magnum/Vk/ImageCreateInfo.h b/src/Magnum/Vk/ImageCreateInfo.h index 4a278d0ca..0e0a656a2 100644 --- a/src/Magnum/Vk/ImageCreateInfo.h +++ b/src/Magnum/Vk/ImageCreateInfo.h @@ -58,14 +58,22 @@ enum class ImageUsage: UnsignedInt { /** * Source of a transfer command * - * @see @ref ImageLayout::TransferSource + * @see @ref ImageLayout::TransferSource, + * @ref CommandBuffer::copyImage(), + * @ref CommandBuffer::copyImageToBuffer() */ TransferSource = VK_IMAGE_USAGE_TRANSFER_SRC_BIT, /** * Destination of a transfer command * - * @see @ref ImageLayout::TransferDestination + * @see @ref ImageLayout::TransferDestination, + * @ref CommandBuffer::clearColorImage(), + * @ref CommandBuffer::clearDepthStencilImage(), + * @ref CommandBuffer::clearDepthImage(), + * @ref CommandBuffer::clearStencilImage(), + * @ref CommandBuffer::copyImage(), + * @ref CommandBuffer::copyBufferToImage() */ TransferDestination = VK_IMAGE_USAGE_TRANSFER_DST_BIT, @@ -84,6 +92,7 @@ enum class ImageUsage: UnsignedInt { * Not all pixel formats support shader storage, with some requiring the * @ref DeviceFeature::ShaderStorageImageExtendedFormats feature. See * @ref PixelFormat for more information. + * @see @ref ImageLayout::General */ Storage = VK_IMAGE_USAGE_STORAGE_BIT, @@ -92,7 +101,8 @@ enum class ImageUsage: UnsignedInt { * * Not all pixel formats support color attachment, see @ref PixelFormat for * more information. - * @see @ref ImageLayout::ColorAttachment + * @see @ref ImageLayout::ColorAttachment, + * @ref SubpassDescription::setColorAttachments() */ ColorAttachment = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, @@ -103,7 +113,8 @@ enum class ImageUsage: UnsignedInt { * @ref PixelFormat::Depth32F and @ref PixelFormat::Depth24UnormStencil8UI * / @ref PixelFormat::Depth32FStencil8UI is guaranteed to support * depth/stencil attachment. - * @see @ref ImageLayout::DepthStencilAttachment + * @see @ref ImageLayout::DepthStencilAttachment, + * @ref SubpassDescription::setDepthStencilAttachment() */ DepthStencilAttachment = VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, @@ -113,7 +124,8 @@ enum class ImageUsage: UnsignedInt { /** * Input attachment in a shader or framebuffer * - * @see @ref ImageLayout::ShaderReadOnly + * @see @ref ImageLayout::ShaderReadOnly, + * @ref SubpassDescription::setInputAttachments() */ InputAttachment = VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT }; diff --git a/src/Magnum/Vk/Mesh.h b/src/Magnum/Vk/Mesh.h index e1e3a30e9..32ffb82dc 100644 --- a/src/Magnum/Vk/Mesh.h +++ b/src/Magnum/Vk/Mesh.h @@ -276,7 +276,8 @@ class MAGNUM_VK_EXPORT Mesh { * @param binding Binding corresponding to a particular * @ref MeshLayout::addBinding() call * @param buffer A @ref Buffer instance or a raw Vulkan buffer - * handle + * handle. Expected to have been created with + * @ref BufferUsage::VertexBuffer. * @param offset Offset into the buffer, in bytes * @return Reference to self (for method chaining) * @@ -297,7 +298,8 @@ class MAGNUM_VK_EXPORT Mesh { /** * @brief Set an index buffer * @param buffer A @ref Buffer instance or a raw Vulkan buffer - * handle + * handle. Expected to have been created with + * @ref BufferUsage::IndexBuffer. * @param offset Offset into the buffer, in bytes * @param indexType Index type * @return Reference to self (for method chaining) diff --git a/src/Magnum/Vk/RenderPassCreateInfo.h b/src/Magnum/Vk/RenderPassCreateInfo.h index 1d26a764e..009dfecbe 100644 --- a/src/Magnum/Vk/RenderPassCreateInfo.h +++ b/src/Magnum/Vk/RenderPassCreateInfo.h @@ -358,9 +358,8 @@ class MAGNUM_VK_EXPORT AttachmentReference { * @brief Constructor * @param attachment Attachment index from the list passed to * @ref RenderPassCreateInfo::setAttachments() - * @param layout Image layout. Should correspond to what's - * passed to @p initialLayout and @p finalLayout in - * @ref AttachmentDescription constructor. + * @param layout Image layout. Should correspond to where the + * reference is used in a @ref SubpassDescription. * * The following @type_vk{AttachmentReference2} fields are pre-filled * in addition to `sType`, everything else is zero-filled: @@ -563,8 +562,10 @@ class MAGNUM_VK_EXPORT SubpassDescription { * Attachments that are being read from in this subpass. The elements * correspond to shader input attachment indices, i.e. a shader input * attachment index @cpp 5 @ce will read from the attachment specified - * at offset @cpp 5 @ce in this list. Use a default-constructed - * @ref AttachmentReference to specify that given input will be unused. + * at offset @cpp 5 @ce in this list. Attachment references should use + * either @ref ImageLayout::General or @ref ImageLayout::ShaderReadOnly; + * use a default-constructed @ref AttachmentReference to specify that + * given input will be unused. */ SubpassDescription& setInputAttachments(Containers::ArrayView attachments) &; /** @overload */ @@ -585,9 +586,11 @@ class MAGNUM_VK_EXPORT SubpassDescription { * * The elements correspond to shader color attachment indices, i.e. a * shader output attachment index @cpp 5 @ce will write from the - * attachment specified at offset @cpp 5 @ce in this list. Use a - * default-constructed @ref AttachmentReference to specify that given - * output will be unused. + * attachment specified at offset @cpp 5 @ce in this list. Attachment + * references should use either @ref ImageLayout::General or + * @ref ImageLayout::ColorAttachment; use a default-constructed + * @ref AttachmentReference to specify that given output will be + * unused. */ #ifdef DOXYGEN_GENERATING_OUTPUT SubpassDescription& setColorAttachments(Containers::ArrayView attachments, Containers::ArrayView resolveAttachments = {}) &; @@ -610,9 +613,11 @@ class MAGNUM_VK_EXPORT SubpassDescription { * @return Reference to self (for method chaining) * * Depth/stencil attachment that is being written to in this subpass. - * Calling this function with a default-constructed - * @ref AttachmentReference is equivalent to not calling it at all, and - * both mean there's no depth/stencil attachment. + * The attachment reference should use either @ref ImageLayout::General + * or @ref ImageLayout::DepthStencilAttachment; calling this function + * with a default-constructed @ref AttachmentReference is equivalent to + * not calling it at all, and both mean there's no depth/stencil + * attachment. */ SubpassDescription& setDepthStencilAttachment(AttachmentReference attachment) &; /** @overload */