1
2// Copyright 2021 HUAWEI, Inc.
3//
4// SPDX-License-Identifier: CC-BY-4.0
5
6= VK_HUAWEI_invocation_mask
7:toc: left
8:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/
9
10
11
12== Problem Statement
13
14The rays to trace may be sparse in some use cases.
15
16For example, the scene only have a few regions to reflect.
17
18Providing an invocation mask image to the trace ray commands could potentially give the hardware the hint to do
19
20certain optimization without invoking an additional pass to compact the ray buffer.
21
22== Solution Space
23
24
25
26== Proposal
27
28API proposal
29
30New Enum Constants
31
32• VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME
33• VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION
34• Extending VkAccessFlagBits2KHR:
35
36 ◦ VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI
37
38• Extending VkImageUsageFlagBits:
39
40 ◦ VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI
41
42• Extending VkPipelineStageFlagBits2KHR:
43
44 ◦ VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI
45
46• Extending VkStructureType:
47
48 ◦ VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI
49
50
51New structure
52 ◦ VkPhysicalDeviceInvocationMaskFeaturesHUAWEI
53
54typedef enum VkImageUsageFlagBits {
55
56 VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
57 VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
58 VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
59 VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
60 VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
61 VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
62 VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
63 VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
64 VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV = 0x00000100,
65
66 // Provided by VK_EXT_fragment_density_map
67 VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT = 0x00000200,
68
69 // Provided by VK_HUAWEI_invocation_mask
70 VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI = 0x00040000,
71
72} VkImageUsageFlagBits;
73
74New commands
75
76void vkCmdBindInvocationMaskHUAWEI(
77  VkCommandBuffer commandBuffer,
78  VkImageView imageView,
79  VkImageLayout imageLayout);
80
81• If imageView is not VK_NULL_HANDLE, it must be a valid VkImageView handle of type VK_IMAGE_VIEW_TYPE_2D
82
83• If imageView is not VK_NULL_HANDLE, it must have a format of VK_FORMAT_R8_UINT
84
85• If imageView is not VK_NULL_HANDLE, it must have been created with a usage value including VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI
86
87• If imageView is not VK_NULL_HANDLE, imageLayout must match the actual VkImageLayou
88of each subresource accessible from imageView at the time the subresource is accessed
89• If imageView is not VK_NULL_HANDLE, imageLayout must be VK_IMAGE_LAYOUT_GENERAL
90
91Valid usage:
92
93Mask image resolution must match the width/height in vkCmdTraceRay;
94The element of the invocation mask image use value 0 and 1.
95The value 1 means the invocation is active.
96
97New structure
98
99• Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:
100
101 ◦ VkPhysicalDeviceInvocationMaskFeaturesHUAWEI
102
103 typedef struct VkPhysicalDeviceInvocationMaskFeaturesHUAWEI {
104  VkStructureType sType;
105  void* pNext;
106  VkBool32 invocationMask;
107 } VkPhysicalDeviceInvocationMaskFeaturesHUAWEI;
108
109invocationMask = true mean the feature is supported
110
111
112== Examples
113
114RT mask is updated before each traceRay.
115
116Step 1. Generate InvocationMask.
117
118//the rt mask image bind as color attachment in the fragment shader
119Layout(location = 2) out vec4 outRTmask
120vec4 mask = vec4(x,x,x,x);
121outRTmask = mask;
122
123Step 2. traceRay with InvocationMask
124
125vkCmdBindPipeline(
126    commandBuffers[imageIndex],
127    VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, m_rtPipeline);
128    vkCmdBindDescriptorSets(commandBuffers[imageIndex],
129    VK_PIPELINE_BIND_POINT_RAY_TRACING_NV,
130    m_rtPipelineLayout, 0, 1, &m_rtDescriptorSet,
131    0, nullptr);
132
133vkCmdBindInvocationMaskHUAWEI(
134    commandBuffers[imageIndex],
135    InvocationMaskimageView,
136    InvocationMaskimageLayout);
137    vkCmdTraceRaysKHR(commandBuffers[imageIndex],
138    pRaygenShaderBindingTable,
139    pMissShaderBindingTable,
140    swapChainExtent.width,
141    swapChainExtent.height, 1);
142
143
144== Issues
145
146
147== Further Functionality
148
149
150