Package org.lwjgl.vulkan

Class HUAWEIInvocationMask

java.lang.Object

org.lwjgl.vulkan.HUAWEIInvocationMask

public class HUAWEIInvocationMask
extends Object

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.

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);

Name String

VK_HUAWEI_invocation_mask

Extension Type

Device extension

Registered Extension Number

371

Revision

1

Extension and Version Dependencies

VK_KHR_ray_tracing_pipeline and VK_KHR_synchronization2 or Version 1.3

Contact

• Pan Gao PanGao-h

Extension Proposal

VK_HUAWEI_invocation_mask

Other Extension Metadata

Last Modified Date

2021-05-27

Interactions and External Dependencies

• This extension requires VK_KHR_ray_tracing_pipeline, which allow to bind an invocation mask image before the ray tracing command
• This extension requires VK_KHR_synchronization2, which allows new pipeline stage for the invocation mask image

Contributors

• Yunpeng Zhu
• Juntao Li, Huawei
• Liang Chen, Huawei
• Shaozhuang Shi, Huawei
• Hailong Chu, Huawei

Field Summary

Fields

Modifier and Type	Field	Description
static final long	VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI	Extends VkAccessFlagBits2.
static final String	VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME	The extension name.
static final int	VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION	The extension specification version.
static final int	VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI	Extends VkImageUsageFlagBits.
static final long	VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI	Extends VkPipelineStageFlagBits2.
static final int	VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI	Extends VkStructureType.

Method Summary

Modifier and Type	Method	Description
static void	vkCmdBindInvocationMaskHUAWEI(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long imageView, int imageLayout)	Bind an invocation mask image on a command buffer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION

public static final int VK_HUAWEI_INVOCATION_MASK_SPEC_VERSION

The extension specification version.

See Also:

• Constant Field Values

VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME

public static final String VK_HUAWEI_INVOCATION_MASK_EXTENSION_NAME

The extension name.

See Also:

• Constant Field Values

VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI

public static final int VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_INVOCATION_MASK_FEATURES_HUAWEI

Extends VkStructureType.

See Also:

• Constant Field Values

VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI

public static final long VK_ACCESS_2_INVOCATION_MASK_READ_BIT_HUAWEI

Extends VkAccessFlagBits2.

See Also:

• Constant Field Values

VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI

public static final int VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI

Extends VkImageUsageFlagBits.

See Also:

• Constant Field Values

VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

public static final long VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI

Extends VkPipelineStageFlagBits2.

See Also:

• Constant Field Values

Method Details

vkCmdBindInvocationMaskHUAWEI

public static void vkCmdBindInvocationMaskHUAWEI(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
 long imageView,
 int imageLayout)

Bind an invocation mask image on a command buffer.

C Specification

When invocation mask image usage is enabled in the bound ray tracing pipeline, the pipeline uses an invocation mask image specified by the command:

 void vkCmdBindInvocationMaskHUAWEI(
     VkCommandBuffer                             commandBuffer,
     VkImageView                                 imageView,
     VkImageLayout                               imageLayout);

Valid Usage

• The invocationMask feature must be enabled
• If imageView is not NULL_HANDLE, it must be a valid VkImageView handle of type IMAGE_VIEW_TYPE_2D
• If imageView is not NULL_HANDLE, it must have a format of FORMAT_R8_UINT
• If imageView is not NULL_HANDLE, it must have been created with IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI set
• If imageView is not NULL_HANDLE, imageLayout must be IMAGE_LAYOUT_GENERAL
• Thread mask image resolution must match the width and height in CmdTraceRaysKHR
• Each element in the invocation mask image must have the value 0 or 1. The value 1 means the invocation is active
• depth in CmdTraceRaysKHR must be 1

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• If imageView is not NULL_HANDLE, imageView must be a valid VkImageView handle
• imageLayout must be a valid VkImageLayout value
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance
• This command must only be called outside of a video coding scope
• Both of commandBuffer, and imageView that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

• Host access to commandBuffer must be externally synchronized
• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Video Coding Scope	Supported Queue Types	Command Type
Primary Secondary	Outside	Outside	Compute	State

Parameters:

commandBuffer - the command buffer into which the command will be recorded

imageView - an image view handle specifying the invocation mask image imageView may be NULL_HANDLE, which is equivalent to specifying a view of an image filled with ones value.

imageLayout - the layout that the image subresources accessible from imageView will be in when the invocation mask image is accessed