跳到主要内容

:material-chevron-right-circle: vkCmdClearDepthStencilImage

函数原型​

void vkCmdClearDepthStencilImage(
    VkCommandBuffer                             commandBuffer,
    VkImage                                     image,
    VkImageLayout                               imageLayout,
    const VkClearDepthStencilValue*             pDepthStencil,
    uint32_t                                    rangeCount,
    const VkImageSubresourceRange*              pRanges);

描述​

清除深度和/或模板（stencil）图像。

参数​

  • commandBuffer : 录制指令的命令缓冲区。
  • image : 要清除的目标图像，必须是具有 VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT 的 VkImage。
  • imageLayout : 图像在清除操作时的当前布局，必须是VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL、VK_IMAGE_LAYOUT_GENERAL、VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL中的一个 。
  • pDepthStencil : 指向 VkClearDepthStencilValue 结构体，包含要清除的深度和模板值。
  • rangeCount : 图像子区域范围的数量。
  • pRanges : 图像子区域范围。

补充​

VkClearDepthStencilValue 结构体定义：

typedef struct VkClearDepthStencilValue {
    float    depth;   // 清除的深度值，通常是 1.0
    uint32_t stencil; // 清除的模板值，通常是 0
} VkClearDepthStencilValue;

返回值​

无

代码示例​

VkClearDepthStencilValue clearValue = {
    .depth = 1.0f,
    .stencil = 0
};

VkImageSubresourceRange range = {
    .aspectMask = VK_IMAGE_ASPECT_DEPTH_BIT | VK_IMAGE_ASPECT_STENCIL_BIT,
    .baseMipLevel = 0,
    .levelCount = 1,
    .baseArrayLayer = 0,
    .layerCount = 1
};

// 确保 image 已过渡到 VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL
vkCmdClearDepthStencilImage(
    commandBuffer,
    depthStencilImage,
    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
    &clearValue,
    1,
    &range
);