// Copyright (c) 2021 Huawei Technologies Co. Ltd.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_HUAWEI_invocation_mask.txt[]

=== Other Extension Metadata

*Last Modified Date*::
    2021-05-27
*Interactions and External Dependencies*::
  - This extension requires `apiext:VK_KHR_ray_tracing_pipeline`, which
    allow to bind an invocation mask image before the ray tracing command
  - This extension requires `apiext:VK_KHR_synchronization2`, which allows
    new pipeline stage for the invocation mask image
*Contributors*::
  - Yunpeng Zhu, HuaWei

=== Description

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 ray tracing commands could
potentially give the hardware the hint to do certain optimization without
invoking an additional pass to compact the ray buffer.

include::{generated}/interfaces/VK_HUAWEI_invocation_mask.txt[]

=== Examples

RT mask is updated before each traceRay.

Step 1.
Generate InvocationMask.

[source,c]
---------------------------------------------------
//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

[source,c]
---------------------------------------------------
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);
---------------------------------------------------

=== Version History

 * Revision 1, 2021-05-27 (Yunpeng Zhu)
   - Initial draft.