跳到主要内容

:material-chevron-right-circle: vkCmdClearColorImage

函数原型​

void vkCmdClearColorImage(
    VkCommandBuffer commandBuffer,
    VkImage         image,
    VkImageLayout   imageLayout,
    const VkClearColorValue* pColor,
    uint32_t        rangeCount,
    const VkImageSubresourceRange* pRanges);

描述​

清除图像颜色内容（通常是纹理或颜色附件）。

参数​

  • commandBuffer : 录制指令的命令缓冲区。
  • image : 要被清除颜色的目标图像（texture、color attachment 等）。
  • imageLayout : 图像在清除操作时的当前布局，必须是VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL或VK_IMAGE_LAYOUT_GENERAL 。
  • pColor : 要填充进图像的颜色值。
  • rangeCount : 图像子区域范围的数量。
  • pRanges : 图像子区域范围。

补充​

VkClearColorValue 结构体定义：

typedef union VkClearColorValue {
    float       float32[4];
    int32_t     int32[4];
    uint32_t    uint32[4];
} VkClearColorValue;

选哪种格式由图像的格式决定（如 RGBA8 用 uint32，RGBA32F 用 float32）。

VkImageSubresourceRange 结构体定义：

typedef struct VkImageSubresourceRange {
    VkImageAspectFlags    aspectMask;		// 通常为 VK_IMAGE_ASPECT_COLOR_BIT（也可能是 DEPTH_BIT/STENCIL_BIT）
    uint32_t              baseMipLevel;		// 从哪个 mip 层级开始清除（通常是 0）
    uint32_t              levelCount;		// 清除几个 mip 层级（通常是 1 或 VK_REMAINING_MIP_LEVELS）
    uint32_t              baseArrayLayer;	// 从哪个 array layer 开始
    uint32_t              layerCount;		// 清除多少个 array layer（如 1，或 VK_REMAINING_ARRAY_LAYERS）
} VkImageSubresourceRange;

返回值​

无

代码示例​

// 清除整张图像为红色
VkClearColorValue clearColor = {{1.0f, 0.0f, 0.0f, 1.0f}}; // 红色

VkImageSubresourceRange range = {};
range.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
range.baseMipLevel = 0;
range.levelCount = 1;
range.baseArrayLayer = 0;
range.layerCount = 1;

vkCmdClearColorImage(
    commandBuffer,
    image,
    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
    &clearColor,
    1,
    &range);