Few improvements to render pass API

3 files changed, 57 insertions, 5 deletions

diff --git a/Graphics/GraphicsEngine/interface/RenderPass.h b/Graphics/GraphicsEngine/interface/RenderPass.h
index 0f12c66d..e9f3027d 100644
--- a/Graphics/GraphicsEngine/interface/RenderPass.h
+++ b/Graphics/GraphicsEngine/interface/RenderPass.h
@@ -40,30 +40,46 @@ DILIGENT_BEGIN_NAMESPACE(Diligent)
 static const struct INTERFACE_ID IID_RenderPass =
     { 0xb818dec7, 0x174d, 0x447a, { 0xa8, 0xe4, 0x94, 0xd2, 0x1c, 0x57, 0xb4, 0xa } };
 
+
 /// Render pass attachment load operation
+/// Vulkan counterpart: [VkAttachmentLoadOp](https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VkAttachmentLoadOp).
+/// D3D12 counterpart: [D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE](https://docs.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_render_pass_beginning_access_type).
 DILIGENT_TYPED_ENUM(ATTACHMENT_LOAD_OP, Uint8)
 {
     /// The previous contents of the texture within the render area will be preserved.
+    /// Vulkan counterpart: VK_ATTACHMENT_LOAD_OP_LOAD.
+    /// D3D12 counterpart: D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE_PRESERVE.
     ATTACHMENT_LOAD_OP_LOAD = 0,
 
     /// The contents within the render area will be cleared to a uniform value, which is
-    /// specified when a render pass instance is begun
+    /// specified when a render pass instance is begun.
+    /// Vulkan counterpart: VK_ATTACHMENT_LOAD_OP_CLEAR.
+    /// D3D12 counterpart: D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE_CLEAR.
     ATTACHMENT_LOAD_OP_CLEAR,
 
     /// The previous contents within the area need not be preserved; the contents of
     /// the attachment will be undefined inside the render area.
-    ATTACHMENT_LOAD_OP_DONT_CARE
+    /// Vulkan counterpart: VK_ATTACHMENT_LOAD_OP_DONT_CARE.
+    /// D3D12 counterpart: D3D12_RENDER_PASS_BEGINNING_ACCESS_TYPE_DISCARD.
+    ATTACHMENT_LOAD_OP_DISCARD
 };
 
+
 /// Render pass attachment store operation
+/// Vulkan counterpart: [VkAttachmentStoreOp](https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VkAttachmentStoreOp).
+/// D3D12 counterpart: [D3D12_RENDER_PASS_ENDING_ACCESS_TYPE](https://docs.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_render_pass_ending_access_type).
 DILIGENT_TYPED_ENUM(ATTACHMENT_STORE_OP, Uint8)
 {
     /// The contents generated during the render pass and within the render area are written to memory.
+    /// Vulkan counterpart: VK_ATTACHMENT_STORE_OP_STORE.
+    /// D3D12 counterpart: D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_PRESERVE.
     ATTACHMENT_STORE_OP_STORE = 0,
 
     /// The contents within the render area are not needed after rendering, and may be discarded;
     /// the contents of the attachment will be undefined inside the render area.
-    ATTACHMENT_STORE_OP_DONT_CARE
+    /// Vulkan counterpart: VK_ATTACHMENT_STORE_OP_DONT_CARE.
+    /// D3D12 counterpart: D3D12_RENDER_PASS_ENDING_ACCESS_TYPE_DISCARD.
+    ATTACHMENT_STORE_OP_DISCARD
 };
 
 
diff --git a/Graphics/GraphicsEngine/src/FramebufferBase.cpp b/Graphics/GraphicsEngine/src/FramebufferBase.cpp
index d3d06702..89b1aa5f 100644
--- a/Graphics/GraphicsEngine/src/FramebufferBase.cpp
+++ b/Graphics/GraphicsEngine/src/FramebufferBase.cpp
@@ -97,6 +97,10 @@ void ValidateFramebufferDesc(const FramebufferDesc& Desc)
             if (AttchRef.AttachmentIndex == ATTACHMENT_UNUSED)
                 continue;
 
+            // If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments
+            // or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not
+            // VK_ATTACHMENT_UNUSED, it must be less than attachmentCount
+            // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-attachment-00834
             if (AttchRef.AttachmentIndex >= Desc.AttachmentCount)
             {
                 LOG_FRAMEBUFFER_ERROR_AND_THROW("The attachment index (", AttchRef.AttachmentIndex, ") of input attachment reference ", input_attachment,
@@ -125,6 +129,10 @@ void ValidateFramebufferDesc(const FramebufferDesc& Desc)
             if (AttchRef.AttachmentIndex == ATTACHMENT_UNUSED)
                 continue;
 
+            // If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments
+            // or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not
+            // VK_ATTACHMENT_UNUSED, it must be less than attachmentCount
+            // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-attachment-00834
             if (AttchRef.AttachmentIndex >= Desc.AttachmentCount)
             {
                 LOG_FRAMEBUFFER_ERROR_AND_THROW("The attachment index (", AttchRef.AttachmentIndex, ") of render target attachment reference ", rt_attachment,
@@ -155,6 +163,10 @@ void ValidateFramebufferDesc(const FramebufferDesc& Desc)
                 if (AttchRef.AttachmentIndex == ATTACHMENT_UNUSED)
                     continue;
 
+                // If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments
+                // or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not
+                // VK_ATTACHMENT_UNUSED, it must be less than attachmentCount
+                // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-attachment-00834
                 if (AttchRef.AttachmentIndex >= Desc.AttachmentCount)
                 {
                     LOG_FRAMEBUFFER_ERROR_AND_THROW("The attachment index (", AttchRef.AttachmentIndex, ") of resolve attachment reference ", rslv_attachment,
@@ -183,6 +195,10 @@ void ValidateFramebufferDesc(const FramebufferDesc& Desc)
             const auto& AttchRef = *Subpass.pDepthStencilAttachment;
             if (AttchRef.AttachmentIndex != ATTACHMENT_UNUSED)
             {
+                // If the attachment member of any element of pInputAttachments, pColorAttachments, pResolveAttachments
+                // or pDepthStencilAttachment, or any element of pPreserveAttachments in any element of pSubpasses is not
+                // VK_ATTACHMENT_UNUSED, it must be less than attachmentCount
+                // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-attachment-00834
                 if (AttchRef.AttachmentIndex >= Desc.AttachmentCount)
                 {
                     LOG_FRAMEBUFFER_ERROR_AND_THROW("The attachment index (", AttchRef.AttachmentIndex, ") of depth-stencil attachment reference of subpass ", i,
diff --git a/Graphics/GraphicsEngine/src/RenderPassBase.cpp b/Graphics/GraphicsEngine/src/RenderPassBase.cpp
index a77ef404..f060c8a0 100644
--- a/Graphics/GraphicsEngine/src/RenderPassBase.cpp
+++ b/Graphics/GraphicsEngine/src/RenderPassBase.cpp
@@ -38,13 +38,33 @@ void ValidateRenderPassDesc(const RenderPassDesc& Desc)
 #define LOG_RENDER_PASS_ERROR_AND_THROW(...) LOG_ERROR_AND_THROW("Render pass '", (Desc.Name ? Desc.Name : ""), "': ", ##__VA_ARGS__)
 
     if (Desc.AttachmentCount != 0 && Desc.pAttachments == nullptr)
+    {
+        // If attachmentCount is not 0, pAttachments must be a valid pointer to an
+        // array of attachmentCount valid VkAttachmentDescription structures.
+        // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-pAttachments-parameter
         LOG_RENDER_PASS_ERROR_AND_THROW("The attachment count (", Desc.AttachmentCount, ") is not zero, but pAttachments is null");
+    }
 
-    if (Desc.SubpassCount != 0 && Desc.pSubpasses == nullptr)
-        LOG_RENDER_PASS_ERROR_AND_THROW("The subpass count (", Desc.SubpassCount, ") is not zero, but pSubpasses is null");
+    if (Desc.SubpassCount == 0)
+    {
+        // subpassCount must be greater than 0.
+        // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-subpassCount-arraylength
+        LOG_RENDER_PASS_ERROR_AND_THROW("Render pass must have at least one subpass");
+    }
+    if (Desc.pSubpasses == nullptr)
+    {
+        // pSubpasses must be a valid pointer to an array of subpassCount valid VkSubpassDescription structures.
+        // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-pSubpasses-parameter
+        LOG_RENDER_PASS_ERROR_AND_THROW("pSubpasses must not be null");
+    }
 
     if (Desc.DependencyCount != 0 && Desc.pDependencies == nullptr)
+    {
+        // If dependencyCount is not 0, pDependencies must be a valid pointer to an array of
+        // dependencyCount valid VkSubpassDependency structures.
+        // https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VUID-VkRenderPassCreateInfo-pDependencies-parameter
         LOG_RENDER_PASS_ERROR_AND_THROW("The dependency count (", Desc.DependencyCount, ") is not zero, but pDependencies is null");
+    }
 
     for (Uint32 i = 0; i < Desc.AttachmentCount; ++i)
     {