[VK] Fixed reading stencil components from a depth-stencil texture in Vulkan.

Vulkan cannot copy combined depth-stencil components into a buffer from an image directly.
Instead, copy the stencil components into the first part of the buffer
and then the depth component into the second part.
Then perform two ConvertImageBuffer() calls to extract each component separately into the output buffer.

Also ignore VKSwapChain::Present() when nothing has been rendered since last call.

TODO:
  This also needs to be fixed for WriteTexture().
  And the copy texture/buffer commands will need to address this as well,
  likely with a built-in compute shader similar to D3D11,
  but only specifically for depth-and-stencil formats.

Author: LukasBanana

include/LLGL/ImageFlags.h

@@ -139,6 +139,8 @@ If this is less than 2, no multi-threading is used. If this is equal to \c LLGL_
 the number of threads will be determined by the workload and the available CPU cores the system supports (e.g. 4 on a quad-core processor).
 Note that this does not guarantee the maximum number of threads the system supports if the workload does not demand it. By default 0.
 \param[in] copyUnchangedImage Specifies whether to copy the source buffer into the destination buffer if no conversion was necessary. By default false.
+\param[in] depthMask Specifies a bitmask for the depth components. This determines what depth bits will be overrideen in the destination buffer. By default 0xFFFFFFFF.
+\param[in] stencilMask Specifies a bitmask for the stencil components. This determines what stencil bits will be overrideen in the destination buffer. By default 0xFFFFFFFF.
 
 \return Number of bytes that have been written to the destination buffer.
 If this is 0, no conversion was necessary and the destination buffer is not modified.
@@ -160,7 +162,9 @@ LLGL_EXPORT std::size_t ConvertImageBuffer(
     const MutableImageView& dstImageView,
     const Extent3D&         extent,
     unsigned                threadCount         = 0,
-    bool                    copyUnchangedImage  = false
+    bool                    copyUnchangedImage  = false,
+    std::uint32_t           depthMask           = ~0u,
+    std::uint32_t           stencilMask         = ~0u
 );
 
 /**

sources/Core/ImageFlags.cpp

@@ -520,25 +520,110 @@ static void WriteRGBAFormattedVariant(
     TransferRGBAFormattedVariantColor(dstFormat, dataType, dstBuffer, idx, value);
 }
 
+// Worker thread procedure for the "ConvertImageBufferFormat" function
+static void ConvertImageBufferFormatWorker(
+    const ImageView&                srcImageView,
+    const MutableImageView&         dstImageView,
+    const ImageOperationMemoryInfo& memoryInfo,
+    const Extent3D&                 extent,
+    std::size_t                     begin,
+    std::size_t                     end)
+{
+    VariantConstBuffer  srcBuffer = srcImageView.data;
+    VariantBuffer       dstBuffer = dstImageView.data;
+
+    ApplyPaddingOffset(srcBuffer, dstBuffer, begin, memoryInfo, extent);
+
+    const std::uint32_t layerSize = extent.width * extent.height;
+
+    /* Initialize default variant color (0, 0, 0, 1) */
+    VariantColor colorValue{ UninitializeTag{} };
+
+    SetVariantMinMax(srcImageView.dataType, colorValue.r, true);
+    SetVariantMinMax(srcImageView.dataType, colorValue.g, true);
+    SetVariantMinMax(srcImageView.dataType, colorValue.b, true);
+    SetVariantMinMax(srcImageView.dataType, colorValue.a, false);
+
+    for_subrange(i, begin, end)
+    {
+        /* Apply source and destination stride when passing an edge */
+        AdvancePaddingOffsetAtEdge(srcBuffer, dstBuffer, i, begin, memoryInfo, extent.width, layerSize);
+
+        /* Read RGBA variant from source buffer */
+        ReadRGBAFormattedVariant(srcImageView.format, srcImageView.dataType, srcBuffer, i, colorValue);
+
+        /* Write RGBA variant to destination buffer */
+        WriteRGBAFormattedVariant(dstImageView.format, dstImageView.dataType, dstBuffer, i, colorValue);
+    }
+}
+
+static std::size_t ConvertImageBufferFormat(
+    const ImageView&        srcImageView,
+    const MutableImageView& dstImageView,
+    const Extent3D&         extent,
+    unsigned                threadCount)
+{
+    LLGL_ASSERT(srcImageView.dataType == dstImageView.dataType);
+
+    /* Validate destination buffer size */
+    const std::size_t numPixels = extent.width * extent.height * extent.depth;
+
+    ImageOperationMemoryInfo memoryInfo = {};
+    GetImageOperationMemoryInfo(memoryInfo, srcImageView, dstImageView, extent);
+
+    LLGL_ASSERT(
+        dstImageView.dataSize >= memoryInfo.dstImageSize,
+        "destination image buffer is too small to convert image format; expected %zu, but %zu was specified",
+        memoryInfo.dstImageSize, dstImageView.dataSize
+    );
+
+    /* Get variant buffer for source and destination images */
+    DoConcurrentRange(
+        std::bind(
+            ConvertImageBufferFormatWorker,
+            std::cref(srcImageView),
+            std::cref(dstImageView),
+            std::cref(memoryInfo),
+            std::cref(extent),
+            std::placeholders::_1,
+            std::placeholders::_2
+        ),
+        numPixels,
+        threadCount
+    );
+
+    return memoryInfo.dstImageSize;
+}
+
+static float UnpackD24UNorm(std::uint32_t value)
+{
+    return (static_cast<float>(value) / static_cast<float>(0x00FFFFFFu));
+}
+
 static void ReadDepthStencilValue(
     ImageFormat srcFormat, DataType dataType, const VariantConstBuffer& srcBuffer, std::size_t idx, DepthStencilValue& value)
 {
     if (srcFormat == ImageFormat::Depth && dataType == DataType::UInt16)
     {
-        /* Read D16UNorm format: Decompress 16-bit float */
-        value.depth = DecompressFloat16(srcBuffer.uint16[idx]);
+        /* Read D16UNorm format: Decode 16-bit unsigned normalized depth */
+        value.depth = static_cast<float>(srcBuffer.uint16[idx]) / static_cast<float>(0x0000FFFFu);
     }
-    else if (srcFormat == ImageFormat::DepthStencil && dataType == DataType::UInt32)
+    else if (srcFormat == ImageFormat::Depth && dataType == DataType::Float16)
     {
-        /* Read D24UNormS8UInt format: Decompress 24-bit float and 8-bit unsigned integer */
-        value.depth   = static_cast<float>(srcBuffer.uint32[idx] & 0x00FFFFFFu) / static_cast<float>(0x00FFFFFFu);
-        value.stencil = srcBuffer.uint32[idx] >> 24;
+        /* Read R16Float format: Decompress 16-bit float */
+        value.depth = DecompressFloat16(srcBuffer.uint16[idx]);
     }
     else if (srcFormat == ImageFormat::Depth && dataType == DataType::Float32)
     {
         /* Read D32Float format: Copy 32-bit float */
         value.depth = srcBuffer.real32[idx];
     }
+    else if (srcFormat == ImageFormat::DepthStencil && dataType == DataType::UInt32)
+    {
+        /* Read D24UNormS8UInt format: Decode 24-bit unsigned normalized depth and 8-bit unsigned stencil */
+        value.depth   = UnpackD24UNorm(srcBuffer.uint32[idx] & 0x00FFFFFF);
+        value.stencil = (srcBuffer.uint32[idx] >> 24);
+    }
     else if (srcFormat == ImageFormat::DepthStencil && dataType == DataType::Float32)
     {
         /* Read D32FloatS8X24UInt format: Copy 32-bit float and 8-bit unsigned integer */
@@ -557,25 +642,34 @@ static void ReadDepthStencilValue(
     }
 }
 
+static std::uint32_t PackD24UNorm(float value)
+{
+    return static_cast<std::uint32_t>(value * static_cast<float>(0x00FFFFFFu));
+}
+
 static void WriteDepthStencilValue(
     ImageFormat dstFormat, DataType dataType, VariantBuffer& dstBuffer, std::size_t idx, const DepthStencilValue& value)
 {
     if (dstFormat == ImageFormat::Depth && dataType == DataType::UInt16)
     {
-        /* Write D16UNorm format: Compress 16-bit float */
-        dstBuffer.uint16[idx] = CompressFloat16(value.depth);
+        /* Write D16UNorm format: Encode 16-bit unsigned normalized depth */
+        dstBuffer.uint16[idx] = static_cast<std::uint16_t>(value.depth * static_cast<float>(0x0000FFFFu));
     }
-    else if (dstFormat == ImageFormat::DepthStencil && dataType == DataType::UInt32)
+    else if (dstFormat == ImageFormat::Depth && dataType == DataType::Float16)
     {
-        /* Write D24UNormS8UInt format: Decompress 24-bit float and 8-bit unsigned integer */
-        const std::uint32_t depth24 = static_cast<std::uint32_t>(value.depth * static_cast<float>(0x00FFFFFFu));
-        dstBuffer.uint32[idx] = ((value.stencil & 0x000000FFu)) << 24 | (depth24 & 0x00FFFFFFu);
+        /* Write R16Float format: Compress 16-bit float */
+        dstBuffer.uint16[idx] = CompressFloat16(value.depth);
     }
     else if (dstFormat == ImageFormat::Depth && dataType == DataType::Float32)
     {
         /* Write D32Float format: Copy 32-bit float */
         dstBuffer.real32[idx] = value.depth;
     }
+    else if (dstFormat == ImageFormat::DepthStencil && dataType == DataType::UInt32)
+    {
+        /* Write D24UNormS8UInt format: Encode 24-bit unsigned normalized depth and 8-bit unsigned stencil */
+        dstBuffer.uint32[idx] = (value.stencil << 24) | (PackD24UNorm(value.depth) & 0x00FFFFFF);
+    }
     else if (dstFormat == ImageFormat::DepthStencil && dataType == DataType::Float32)
     {
         /* Read D32FloatS8X24UInt format: Copy 32-bit float and 8-bit unsigned integer */
@@ -594,12 +688,31 @@ static void WriteDepthStencilValue(
     }
 }
 
-// Worker thread procedure for the "ConvertImageBufferFormat" function
-static void ConvertImageBufferFormatWorker(
+static float UInt32AsFloat32(std::uint32_t value)
+{
+    return *reinterpret_cast<const float*>(&value);
+}
+
+static std::uint32_t Float32AsUInt32(float value)
+{
+    return *reinterpret_cast<const std::uint32_t*>(&value);
+}
+
+static void MergeDepthStencilValues(
+    DepthStencilValue& dst, const DepthStencilValue& src, std::uint32_t srcDepthMask, std::uint32_t srcStencilMask)
+{
+    dst.depth   = UInt32AsFloat32((Float32AsUInt32(dst.depth) & ~srcDepthMask) | (Float32AsUInt32(src.depth) & srcDepthMask));
+    dst.stencil = (dst.stencil & ~srcStencilMask) | (src.stencil & srcStencilMask);
+}
+
+// Worker thread procedure for the "ConvertDepthStencilImageBufferFormat" function
+static void ConvertDepthStencilImageBufferFormatWorker(
     const ImageView&                srcImageView,
     const MutableImageView&         dstImageView,
     const ImageOperationMemoryInfo& memoryInfo,
     const Extent3D&                 extent,
+    std::uint32_t                   depthMask,
+    std::uint32_t                   stencilMask,
     std::size_t                     begin,
     std::size_t                     end)
 {
@@ -610,54 +723,36 @@ static void ConvertImageBufferFormatWorker(
 
     const std::uint32_t layerSize = extent.width * extent.height;
 
-    if (IsDepthOrStencilFormat(srcImageView.format))
-    {
-        /* Initialize default depth-stencil value (0, 0) */
-        DepthStencilValue depthStencilValue{ 0.0f, 0u };
+    /* Initialize default depth-stencil value (0, 0) */
+    DepthStencilValue depthStencilValueSrc{ 0.0f, 0u };
+    DepthStencilValue depthStencilValueDst{ 0.0f, 0u };
 
-        for_subrange(i, begin, end)
-        {
-            /* Apply source and destination stride when passing an edge */
-            AdvancePaddingOffsetAtEdge(srcBuffer, dstBuffer, i, begin, memoryInfo, extent.width, layerSize);
-
-            /* Read depth-stencil value from source buffer */
-            ReadDepthStencilValue(srcImageView.format, srcImageView.dataType, srcBuffer, i, depthStencilValue);
-
-            /* Write depth-stencil value to destination buffer */
-            WriteDepthStencilValue(dstImageView.format, dstImageView.dataType, dstBuffer, i, depthStencilValue);
-        }
-    }
-    else
+    for_subrange(i, begin, end)
     {
-        /* Initialize default variant color (0, 0, 0, 1) */
-        VariantColor colorValue{ UninitializeTag{} };
+        /* Apply source and destination stride when passing an edge */
+        AdvancePaddingOffsetAtEdge(srcBuffer, dstBuffer, i, begin, memoryInfo, extent.width, layerSize);
 
-        SetVariantMinMax(srcImageView.dataType, colorValue.r, true);
-        SetVariantMinMax(srcImageView.dataType, colorValue.g, true);
-        SetVariantMinMax(srcImageView.dataType, colorValue.b, true);
-        SetVariantMinMax(srcImageView.dataType, colorValue.a, false);
+        /* Read depth-stencil value from source buffer */
+        ReadDepthStencilValue(srcImageView.format, srcImageView.dataType, srcBuffer, i, depthStencilValueSrc);
+        ReadDepthStencilValue(dstImageView.format, dstImageView.dataType, VariantConstBuffer{ dstBuffer.uint8 }, i, depthStencilValueDst);
 
-        for_subrange(i, begin, end)
-        {
-            /* Apply source and destination stride when passing an edge */
-            AdvancePaddingOffsetAtEdge(srcBuffer, dstBuffer, i, begin, memoryInfo, extent.width, layerSize);
+        /* Apply masking */
+        MergeDepthStencilValues(depthStencilValueDst, depthStencilValueSrc, depthMask, stencilMask);
 
-            /* Read RGBA variant from source buffer */
-            ReadRGBAFormattedVariant(srcImageView.format, srcImageView.dataType, srcBuffer, i, colorValue);
-
-            /* Write RGBA variant to destination buffer */
-            WriteRGBAFormattedVariant(dstImageView.format, dstImageView.dataType, dstBuffer, i, colorValue);
-        }
+        /* Write depth-stencil value to destination buffer */
+        WriteDepthStencilValue(dstImageView.format, dstImageView.dataType, dstBuffer, i, depthStencilValueDst);
     }
 }
 
-static std::size_t ConvertImageBufferFormat(
+static std::size_t ConvertDepthStencilImageBufferFormat(
     const ImageView&        srcImageView,
     const MutableImageView& dstImageView,
     const Extent3D&         extent,
+    std::uint32_t           depthMask,
+    std::uint32_t           stencilMask,
     unsigned                threadCount)
 {
-    LLGL_ASSERT(IsDepthOrStencilFormat(srcImageView.format) || srcImageView.dataType == dstImageView.dataType);
+    LLGL_ASSERT(IsDepthOrStencilFormat(srcImageView.format));
 
     /* Validate destination buffer size */
     const std::size_t numPixels = extent.width * extent.height * extent.depth;
@@ -674,11 +769,13 @@ static std::size_t ConvertImageBufferFormat(
     /* Get variant buffer for source and destination images */
     DoConcurrentRange(
         std::bind(
-            ConvertImageBufferFormatWorker,
+            ConvertDepthStencilImageBufferFormatWorker,
             std::cref(srcImageView),
             std::cref(dstImageView),
             std::cref(memoryInfo),
             std::cref(extent),
+            depthMask,
+            stencilMask,
             std::placeholders::_1,
             std::placeholders::_2
         ),
@@ -726,7 +823,9 @@ LLGL_EXPORT std::size_t ConvertImageBuffer(
     const MutableImageView& dstImageView,
     const Extent3D&         extent,
     unsigned                threadCount,
-    bool                    copyUnchangedImage)
+    bool                    copyUnchangedImage,
+    std::uint32_t           depthMask,
+    std::uint32_t           stencilMask)
 {
     /* Validate input parameters */
     ValidateSourceImageView(srcImageView);
@@ -736,7 +835,7 @@ LLGL_EXPORT std::size_t ConvertImageBuffer(
     if (IsDepthOrStencilFormat(srcImageView.format))
     {
         /* Convert depth-stencil image format */
-        return ConvertImageBufferFormat(srcImageView, dstImageView, extent, threadCount);
+        return ConvertDepthStencilImageBufferFormat(srcImageView, dstImageView, extent, depthMask, stencilMask, threadCount);
     }
     else if (srcImageView.dataType != dstImageView.dataType && srcImageView.format != dstImageView.format)
     {