v1.144:

HIGHLIGHTS:
- resolved inability to use read-only depth or stencil and keeping the other subresource writable
- added ability to separate depth and stencil in a barrier
- introduced "PlaneBits" concept, which is also needed for video

BREAKING CHANGES:
- "attachmentContentType" renamed to "planes"
- "ClearDesc::planes" must be set to "PlaneBits::COLOR" explicitly for color only clears
- no changes in barriers unless depth and stencil separation needed
- removed "ResourceViewBits", use extended "Texture1DViewType" ("Texture2DViewType") instead
- no more API changes planned \O/

DETAILS:
- NRI: introduced "PlaneBits"
- NRI: extended "Texture1DViewType" and "Texture2DViewType" to include read-only depth and/or stencil
- NRI: removed "ResourceViewBits" (there was not a "resource" concept), replaced with extended view types
- NRI: "AttachmentContentType" replaced with "PlaneBits"
- NRI: added "PlaneBits" to "TextureBarrierDesc"
- D3D11/D3D12/VK: improvements around "ClearAttachments"
- VK: "ClearAttachments" behavior matched D3D
- Helper: added "planes" to "TextureUploadDesc"
- Validation: improved "ClearAttachments" validation
- Validation: added detection of a mismatched D3D/VK behavior related to read-only depth-stencil usage

Include/Extensions/NRIHelper.h

@@ -23,6 +23,7 @@ NRI_STRUCT(TextureUploadDesc)
     NRI_OPTIONAL const NRI_NAME(TextureSubresourceUploadDesc)* subresources; // if provided, must include ALL subresources = layerNum * mipNum
     NRI_NAME(Texture)* texture;
     NRI_NAME(AccessLayoutStage) after;
+    NRI_NAME(PlaneBits) planes;
 };
 
 NRI_STRUCT(BufferUploadDesc)

Include/NRI.h

@@ -25,8 +25,8 @@ Non-goals:
 #include <stddef.h>
 
 #define NRI_VERSION_MAJOR 1
-#define NRI_VERSION_MINOR 143
-#define NRI_VERSION_DATE "29 August 2024"
+#define NRI_VERSION_MINOR 144
+#define NRI_VERSION_DATE "30 August 2024"
 
 #ifdef _WIN32
     #define NRI_CALL __fastcall

Include/NRIDescs.h

@@ -181,6 +181,16 @@ NRI_ENUM
     MAX_NUM
 );
 
+NRI_ENUM_BITS
+(
+    PlaneBits, uint8_t,
+
+    ALL                             = 0,
+    COLOR                           = NRI_SET_BIT(0),
+    DEPTH                           = NRI_SET_BIT(1),
+    STENCIL                         = NRI_SET_BIT(2)
+);
+
 NRI_ENUM_BITS
 (
     FormatSupportBits, uint16_t,
@@ -365,6 +375,9 @@ NRI_ENUM
     SHADER_RESOURCE_STORAGE_1D_ARRAY,
     COLOR_ATTACHMENT,
     DEPTH_STENCIL_ATTACHMENT,
+    DEPTH_READONLY_STENCIL_ATTACHMENT,
+    DEPTH_ATTACHMENT_STENCIL_READONLY,
+    DEPTH_STENCIL_READONLY,
 
     MAX_NUM
 );
@@ -381,6 +394,9 @@ NRI_ENUM
     SHADER_RESOURCE_STORAGE_2D_ARRAY,
     COLOR_ATTACHMENT,
     DEPTH_STENCIL_ATTACHMENT,
+    DEPTH_READONLY_STENCIL_ATTACHMENT,
+    DEPTH_ATTACHMENT_STENCIL_READONLY,
+    DEPTH_STENCIL_READONLY,
     SHADING_RATE_ATTACHMENT,
 
     MAX_NUM
@@ -452,15 +468,6 @@ NRI_ENUM_BITS
     ACCELERATION_STRUCTURE_BUILD_READ   = NRI_SET_BIT(7)
 );
 
-NRI_ENUM_BITS
-(
-    ResourceViewBits, uint8_t,
-
-    NONE                                = 0,
-    READONLY_DEPTH                      = NRI_SET_BIT(0),
-    READONLY_STENCIL                    = NRI_SET_BIT(1)
-);
-
 // Resources
 NRI_STRUCT(TextureDesc)
 {
@@ -492,7 +499,6 @@ NRI_STRUCT(Texture1DViewDesc)
     NRI_NAME(Mip_t) mipNum;
     NRI_NAME(Dim_t) layerOffset;
     NRI_NAME(Dim_t) layerNum;
-    NRI_NAME(ResourceViewBits) flags;
 };
 
 NRI_STRUCT(Texture2DViewDesc)
@@ -504,7 +510,6 @@ NRI_STRUCT(Texture2DViewDesc)
     NRI_NAME(Mip_t) mipNum;
     NRI_NAME(Dim_t) layerOffset;
     NRI_NAME(Dim_t) layerNum;
-    NRI_NAME(ResourceViewBits) flags;
 };
 
 NRI_STRUCT(Texture3DViewDesc)
@@ -912,18 +917,6 @@ NRI_ENUM
     MAX_NUM
 );
 
-NRI_ENUM
-(
-    AttachmentContentType, uint8_t,
-
-    COLOR,
-    DEPTH,
-    STENCIL,
-    DEPTH_STENCIL,
-
-    MAX_NUM
-);
-
 NRI_ENUM_BITS
 (
     ColorWriteBits, uint8_t,
@@ -952,7 +945,7 @@ NRI_UNION(ClearValue)
 NRI_STRUCT(ClearDesc)
 {
     NRI_NAME(ClearValue) value;
-    NRI_NAME(AttachmentContentType) attachmentContentType;
+    NRI_NAME(PlaneBits) planes;
     uint32_t colorAttachmentIndex;
 };
 
@@ -1209,6 +1202,7 @@ NRI_STRUCT(TextureBarrierDesc)
     NRI_NAME(Mip_t) mipNum;
     NRI_NAME(Dim_t) layerOffset;
     NRI_NAME(Dim_t) layerNum;
+    NRI_NAME(PlaneBits) planes;
 };
 
 NRI_STRUCT(BarrierGroupDesc)

Resources/Version.h

@@ -4,7 +4,7 @@
 #define STR(x) STR_HELPER(x)
 
 #define VERSION_MAJOR                   1
-#define VERSION_MINOR                   143
+#define VERSION_MINOR                   144
 #define VERSION_BUILD                   0
 #define VERSION_REVISION                0
 

Source/D3D11/CommandBufferD3D11.cpp

@@ -96,6 +96,8 @@ Result CommandBufferD3D11::Begin(const DescriptorPool* descriptorPool) {
     m_IndexBuffer = nullptr;
     m_VertexBuffer = nullptr;
 
+    ResetAttachments();
+
     // Dynamic state
     m_SamplePositionsState.Reset();
     m_StencilRef = 0;
@@ -170,24 +172,23 @@ void CommandBufferD3D11::SetShadingRate(const ShadingRateDesc& shadingRateDesc)
 }
 
 void CommandBufferD3D11::ClearAttachments(const ClearDesc* clearDescs, uint32_t clearDescNum, const Rect* rects, uint32_t rectNum) {
-    if (!rects || !rectNum) {
+    if (!clearDescNum)
+        return;
+
+    if (!rectNum) {
         for (uint32_t i = 0; i < clearDescNum; i++) {
             const ClearDesc& clearDesc = clearDescs[i];
 
-            switch (clearDesc.attachmentContentType) {
-                case AttachmentContentType::COLOR:
-                    m_DeferredContext->ClearRenderTargetView(m_RenderTargets[clearDesc.colorAttachmentIndex], &clearDesc.value.color32f.x);
-                    break;
-                case AttachmentContentType::DEPTH:
-                    m_DeferredContext->ClearDepthStencilView(m_DepthStencil, D3D11_CLEAR_DEPTH, clearDesc.value.depthStencil.depth, 0);
-                    break;
-                case AttachmentContentType::STENCIL:
-                    m_DeferredContext->ClearDepthStencilView(m_DepthStencil, D3D11_CLEAR_STENCIL, 0.0f, clearDesc.value.depthStencil.stencil);
-                    break;
-                case AttachmentContentType::DEPTH_STENCIL:
-                    m_DeferredContext->ClearDepthStencilView(
-                        m_DepthStencil, D3D11_CLEAR_DEPTH | D3D11_CLEAR_STENCIL, clearDesc.value.depthStencil.depth, clearDesc.value.depthStencil.stencil);
-                    break;
+            if (clearDesc.planes & PlaneBits::COLOR)
+                m_DeferredContext->ClearRenderTargetView(m_RenderTargets[clearDesc.colorAttachmentIndex], &clearDesc.value.color32f.x);
+            else {
+                uint32_t clearFlags = 0;
+                if (clearDescs[i].planes & PlaneBits::DEPTH)
+                    clearFlags |= D3D11_CLEAR_DEPTH;
+                if (clearDescs[i].planes & PlaneBits::STENCIL)
+                    clearFlags |= D3D11_CLEAR_STENCIL;
+
+                m_DeferredContext->ClearDepthStencilView(m_DepthStencil, clearFlags, clearDesc.value.depthStencil.depth, clearDesc.value.depthStencil.stencil);
             }
         }
     } else {
@@ -202,20 +203,14 @@ void CommandBufferD3D11::ClearAttachments(const ClearDesc* clearDescs, uint32_t
             FLOAT color[4] = {};
             for (uint32_t i = 0; i < clearDescNum; i++) {
                 const ClearDesc& clearDesc = clearDescs[i];
-                switch (clearDesc.attachmentContentType) {
-                    case AttachmentContentType::COLOR:
-                        m_DeferredContext->ClearView(m_RenderTargets[clearDesc.colorAttachmentIndex], &clearDesc.value.color32f.x, rectsD3D, rectNum);
-                        break;
-                    case AttachmentContentType::DEPTH:
-                    case AttachmentContentType::DEPTH_STENCIL:
-                        color[0] = clearDesc.value.depthStencil.depth;
-                        m_DeferredContext->ClearView(m_DepthStencil, color, rectsD3D, rectNum);
-                        break;
-                    case AttachmentContentType::STENCIL:
-                        color[0] = clearDesc.value.depthStencil.stencil;
-                        m_DeferredContext->ClearView(m_DepthStencil, color, rectsD3D, rectNum);
-                        break;
-                }
+
+                if (clearDesc.planes & PlaneBits::COLOR)
+                    m_DeferredContext->ClearView(m_RenderTargets[clearDesc.colorAttachmentIndex], &clearDesc.value.color32f.x, rectsD3D, rectNum);
+                else if (clearDesc.planes & PlaneBits::DEPTH) {
+                    color[0] = clearDesc.value.depthStencil.depth;
+                    m_DeferredContext->ClearView(m_DepthStencil, color, rectsD3D, rectNum);
+                } else
+                    CHECK(false, "Bad or unsupported plane");
             }
         } else
             CHECK(false, "'ClearView' emulation for 11.0 is not implemented!");

Source/D3D11/CommandBufferD3D11.h

@@ -24,6 +24,14 @@ struct CommandBufferD3D11 final : public CommandBufferHelper {
         return m_DeferredContext;
     }
 
+    inline void ResetAttachments() {
+        m_RenderTargetNum = 0;
+        for (size_t i = 0; i < m_RenderTargets.size(); i++)
+            m_RenderTargets[i] = nullptr;
+
+        m_DepthStencil = nullptr;
+    }
+
     Result Create(ID3D11DeviceContext* precreatedContext);
     void Submit();
     StdAllocator<uint8_t>& GetStdAllocator() const;
@@ -37,9 +45,6 @@ struct CommandBufferD3D11 final : public CommandBufferHelper {
         SET_D3D_DEBUG_OBJECT_NAME(m_CommandList, name);
     }
 
-    inline void EndRendering() {
-    }
-
     Result Begin(const DescriptorPool* descriptorPool);
     Result End();
     void SetViewports(const Viewport* viewports, uint32_t viewportNum);

Source/D3D11/CommandBufferD3D11.hpp

@@ -44,7 +44,7 @@ static void NRI_CALL CmdBeginRendering(CommandBuffer& commandBuffer, const Attac
 }
 
 static void NRI_CALL CmdEndRendering(CommandBuffer& commandBuffer) {
-    ((CommandBufferD3D11&)commandBuffer).EndRendering();
+    ((CommandBufferD3D11&)commandBuffer).ResetAttachments();
 }
 
 static void NRI_CALL CmdSetViewports(CommandBuffer& commandBuffer, const Viewport* viewports, uint32_t viewportNum) {

Source/D3D11/CommandBufferEmuD3D11.cpp

@@ -215,7 +215,7 @@ void CommandBufferEmuD3D11::Submit() {
                 commandBuffer.BeginRendering(attachmentsDesc);
             } break;
             case END_RENDERING: {
-                commandBuffer.EndRendering();
+                commandBuffer.ResetAttachments();
             } break;
             case BIND_VERTEX_BUFFERS: {
                 uint32_t baseSlot;

Source/D3D11/DescriptorD3D11.cpp

@@ -119,18 +119,23 @@ Result DescriptorD3D11::Create(const Texture1DViewDesc& textureViewDesc) {
 
             m_Type = DescriptorTypeDX11::NO_SHADER_VISIBLE;
         } break;
-        case Texture1DViewType::DEPTH_STENCIL_ATTACHMENT: {
+        case Texture1DViewType::DEPTH_STENCIL_ATTACHMENT:
+        case Texture1DViewType::DEPTH_READONLY_STENCIL_ATTACHMENT:
+        case Texture1DViewType::DEPTH_ATTACHMENT_STENCIL_READONLY:
+        case Texture1DViewType::DEPTH_STENCIL_READONLY: {
             D3D11_DEPTH_STENCIL_VIEW_DESC desc = {};
             desc.ViewDimension = D3D11_DSV_DIMENSION_TEXTURE1DARRAY;
             desc.Texture1DArray.MipSlice = textureViewDesc.mipOffset;
             desc.Texture1DArray.FirstArraySlice = textureViewDesc.layerOffset;
             desc.Texture1DArray.ArraySize = remainingLayers;
             desc.Format = format;
 
-            if (textureViewDesc.flags & ResourceViewBits::READONLY_DEPTH)
-                desc.Flags |= D3D11_DSV_READ_ONLY_DEPTH;
-            if (textureViewDesc.flags & ResourceViewBits::READONLY_STENCIL)
-                desc.Flags |= D3D11_DSV_READ_ONLY_STENCIL;
+            if (textureViewDesc.viewType == Texture1DViewType::DEPTH_READONLY_STENCIL_ATTACHMENT)
+                desc.Flags = D3D11_DSV_READ_ONLY_DEPTH;
+            else if (textureViewDesc.viewType == Texture1DViewType::DEPTH_ATTACHMENT_STENCIL_READONLY)
+                desc.Flags = D3D11_DSV_READ_ONLY_STENCIL;
+            else if (textureViewDesc.viewType == Texture1DViewType::DEPTH_STENCIL_READONLY)
+                desc.Flags = D3D11_DSV_READ_ONLY_DEPTH | D3D11_DSV_READ_ONLY_STENCIL;
 
             hr = m_Device->CreateDepthStencilView(texture, &desc, (ID3D11DepthStencilView**)&m_Descriptor);
 
@@ -269,7 +274,10 @@ Result DescriptorD3D11::Create(const Texture2DViewDesc& textureViewDesc) {
 
             break;
         }
-        case Texture2DViewType::DEPTH_STENCIL_ATTACHMENT: {
+        case Texture2DViewType::DEPTH_STENCIL_ATTACHMENT:
+        case Texture2DViewType::DEPTH_READONLY_STENCIL_ATTACHMENT:
+        case Texture2DViewType::DEPTH_ATTACHMENT_STENCIL_READONLY:
+        case Texture2DViewType::DEPTH_STENCIL_READONLY: {
             D3D11_DEPTH_STENCIL_VIEW_DESC desc = {};
             if (textureDesc.sampleNum > 1) {
                 desc.ViewDimension = D3D11_DSV_DIMENSION_TEXTURE2DMSARRAY;
@@ -283,10 +291,12 @@ Result DescriptorD3D11::Create(const Texture2DViewDesc& textureViewDesc) {
             }
             desc.Format = format;
 
-            if (textureViewDesc.flags & ResourceViewBits::READONLY_DEPTH)
-                desc.Flags |= D3D11_DSV_READ_ONLY_DEPTH;
-            if (textureViewDesc.flags & ResourceViewBits::READONLY_STENCIL)
-                desc.Flags |= D3D11_DSV_READ_ONLY_STENCIL;
+            if (textureViewDesc.viewType == Texture2DViewType::DEPTH_READONLY_STENCIL_ATTACHMENT)
+                desc.Flags = D3D11_DSV_READ_ONLY_DEPTH;
+            else if (textureViewDesc.viewType == Texture2DViewType::DEPTH_ATTACHMENT_STENCIL_READONLY)
+                desc.Flags = D3D11_DSV_READ_ONLY_STENCIL;
+            else if (textureViewDesc.viewType == Texture2DViewType::DEPTH_STENCIL_READONLY)
+                desc.Flags = D3D11_DSV_READ_ONLY_DEPTH | D3D11_DSV_READ_ONLY_STENCIL;
 
             hr = m_Device->CreateDepthStencilView(texture, &desc, (ID3D11DepthStencilView**)&m_Descriptor);
 

Source/D3D11/DeviceD3D11.cpp

@@ -341,7 +341,7 @@ void DeviceD3D11::FillDesc() {
     m_Desc.bufferMaxSize = D3D11_REQ_RESOURCE_SIZE_IN_MEGABYTES_EXPRESSION_C_TERM * 1024ull * 1024ull;
     m_Desc.pushConstantsMaxSize = D3D11_REQ_IMMEDIATE_CONSTANT_BUFFER_ELEMENT_COUNT * 16;
 
-    m_Desc.boundDescriptorSetMaxNum = D3D11_COMMONSHADER_INPUT_RESOURCE_SLOT_COUNT;
+    m_Desc.boundDescriptorSetMaxNum = BOUND_DESCRIPTOR_SET_MAX_NUM;
     m_Desc.perStageDescriptorSamplerMaxNum = D3D11_COMMONSHADER_SAMPLER_SLOT_COUNT;
     m_Desc.perStageDescriptorConstantBufferMaxNum = D3D11_COMMONSHADER_CONSTANT_BUFFER_API_SLOT_COUNT;
     m_Desc.perStageDescriptorStorageBufferMaxNum = m_Version >= 1 ? D3D11_1_UAV_SLOT_COUNT : D3D11_PS_CS_UAV_REGISTER_COUNT;

Source/D3D11/TextureD3D11.h

@@ -40,6 +40,7 @@ struct TextureD3D11 {
     }
 
     inline uint32_t GetSubresourceIndex(const TextureRegionDesc& regionDesc) const {
+        // https://learn.microsoft.com/en-us/windows/win32/direct3d12/subresources#plane-slice
         return regionDesc.mipOffset + regionDesc.layerOffset * m_Desc.mipNum;
     }