// Copyright 2021 HUAWEI, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

= VK_HUAWEI_invocation_mask
:toc: left
:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/



== Problem Statement

The rays to trace may be sparse in some use cases. 

For example, the scene only have a few regions to reflect. 

Providing an invocation mask image to the trace ray commands could potentially give the hardware the hint to do

certain optimization without invoking an additional pass to compact the ray buffer.

== Solution Space



== Proposal

API proposal

New Enum Constants

• VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME
• VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION
• Extending VkAccessFlagBits2KHR:

 ◦ VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI

• Extending VkImageUsageFlagBits:

 ◦ VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI

• Extending VkPipelineStageFlagBits2KHR:

 ◦ VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

• Extending VkStructureType:

 ◦ VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI


New structure
 ◦ VkPhysicalDeviceInvocationMaskFeaturesHUAWEI

typedef enum VkImageUsageFlagBits {

 VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
 VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
 VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
 VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
 VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
 VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
 VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
 VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
 VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = 0x00000100,

 // Provided by VK_EXT_fragment_density_map
 VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,

 // Provided by VK_HUAWEI_invocation_mask
 VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,

} VkImageUsageFlagBits;

New commands

void vkCmdBindInvocationMaskHUAWEI(
  VkCommandBuffer commandBuffer,
  VkImageView imageView,
  VkImageLayout imageLayout);
  
• If imageView is not VK_NULL_HANDLE, it must be a valid VkImageView handle of type VK_IMAGE_VIEW_TYPE_2D

• If imageView is not VK_NULL_HANDLE, it must have a format of VK_FORMAT_R8_UINT

• If imageView is not VK_NULL_HANDLE, it must have been created with a usage value including VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI

• If imageView is not VK_NULL_HANDLE, imageLayout must match the actual VkImageLayou
of each subresource accessible from imageView at the time the subresource is accessed
• If imageView is not VK_NULL_HANDLE, imageLayout must be VK_IMAGE_LAYOUT_GENERAL

Valid usage:

Mask image resolution must match the width/height in vkCmdTraceRay;
The element of the invocation mask image use value 0 and 1.
The value 1 means the invocation is active.

New structure

• Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:

 ◦ VkPhysicalDeviceInvocationMaskFeaturesHUAWEI

 typedef struct VkPhysicalDeviceInvocationMaskFeaturesHUAWEI {
  VkStructureType sType;
  void* pNext;
  VkBool32 invocationMask;
 } VkPhysicalDeviceInvocationMaskFeaturesHUAWEI;

invocationMask = true mean the feature is supported


== Examples

RT mask is updated before each traceRay.

Step 1. Generate InvocationMask.

//the rt mask image bind as color attachment in the fragment shader
Layout(location = 2) out vec4 outRTmask
vec4 mask = vec4(x,x,x,x);
outRTmask = mask;

Step 2. traceRay with InvocationMask

vkCmdBindPipeline(
    commandBuffers[imageIndex],
    VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, m_rtPipeline);
    vkCmdBindDescriptorSets(commandBuffers[imageIndex],
    VK_PIPELINE_BIND_POINT_RAY_TRACING_NV,
    m_rtPipelineLayout, 0, 1, &m_rtDescriptorSet,
    0, nullptr);

vkCmdBindInvocationMaskHUAWEI(
    commandBuffers[imageIndex],
    InvocationMaskimageView,
    InvocationMaskimageLayout);
    vkCmdTraceRaysKHR(commandBuffers[imageIndex],
    pRaygenShaderBindingTable,
    pMissShaderBindingTable,
    swapChainExtent.width,
    swapChainExtent.height, 1);


== Issues


== Further Functionality