Vk: doc++.

Especially relations between {Buffer,Image}Usage, ImageLayout and
other APIs.

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 */

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,
 

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
 };

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)

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<const AttachmentReference> 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<const AttachmentReference> attachments, Containers::ArrayView<const AttachmentReference> 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 */