vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Description

Name

VK_NV_ray_tracing_invocation_reorder - device extension

VK_NV_ray_tracing_invocation_reorder

Name String
VK_NV_ray_tracing_invocation_reorder
Extension Type
Device extension
Registered Extension Number
491
Revision
1
Ratification Status
Not ratified
Extension and Version Dependencies
VK_KHR_ray_tracing_pipeline
Contact

Other Extension Metadata

Last Modified Date
2022-11-02
Interactions and External Dependencies
Contributors
  • Eric Werness, NVIDIA
  • Ashwin Lele, NVIDIA

Description

The ray tracing pipeline API provides some ability to reorder for locality, but it is useful to have more control over how the reordering happens and what information is included in the reordering. The shader API provides a hit object to contain result information from the hit which can be used as part of the explicit sorting plus options that contain an integer for hint bits to use to add more locality.

New Structures

New Enums

New Enum Constants

HLSL Mapping

HLSL does not provide this functionality natively yet.

However, it is possible to use this functionality via SPIR-V Intrinsics.

The codes for shader invocation reorder are obtained from this page:

#define ShaderInvocationReorderNV 5383
#define HitObjectAttributeNV 5385

#define OpHitObjectRecordHitMotionNV 5249
#define OpHitObjectRecordHitWithIndexMotionNV 5250
#define OpHitObjectRecordMissMotionNV 5251
#define OpHitObjectGetWorldToObjectNV 5252
#define OpHitObjectGetObjectToWorldNV 5253
#define OpHitObjectGetObjectRayDirectionNV 5254
#define OpHitObjectGetObjectRayOriginNV 5255
#define OpHitObjectTraceRayMotionNV 5256
#define OpHitObjectGetShaderRecordBufferHandleNV 5257
#define OpHitObjectGetShaderBindingTableRecordIndexNV 5258
#define OpHitObjectRecordEmptyNV 5259
#define OpHitObjectTraceRayNV 5260
#define OpHitObjectRecordHitNV 5261
#define OpHitObjectRecordHitWithIndexNV 5262
#define OpHitObjectRecordMissNV 5263
#define OpHitObjectExecuteShaderNV 5264
#define OpHitObjectGetCurrentTimeNV 5265
#define OpHitObjectGetAttributesNV 5266
#define OpHitObjectGetHitKindNV 5267
#define OpHitObjectGetPrimitiveIndexNV 5268
#define OpHitObjectGetGeometryIndexNV 5269
#define OpHitObjectGetInstanceIdNV 5270
#define OpHitObjectGetInstanceCustomIndexNV 5271
#define OpHitObjectGetWorldRayDirectionNV 5272
#define OpHitObjectGetWorldRayOriginNV 5273
#define OpHitObjectGetRayTMaxNV 5274
#define OpHitObjectGetRayTMinNV 5275
#define OpHitObjectIsEmptyNV 5276
#define OpHitObjectIsHitNV 5277
#define OpHitObjectIsMissNV 5278
#define OpReorderThreadWithHitObjectNV 5279
#define OpReorderThreadWithHintNV 5280
#define OpTypeHitObjectNV 5281

The capability and extension need to be added:

[[vk::ext_capability(ShaderInvocationReorderNV)]]
[[vk::ext_extension("SPV_NV_shader_invocation_reorder")]]

The creation of the HitObject type can be done like this:

[[vk::ext_type_def(HitObjectAttributeNV, OpTypeHitObjectNV)]]
void createHitObjectNV();
#define HitObjectNV vk::ext_type<HitObjectAttributeNV>

The payload:

  • must be global
  • needs the RayPayloadKHR attribute as an extra storage class
struct [raypayload] HitPayload
{
  float hitT : write(closesthit, miss) : read(caller);
  int instanceIndex : write(closesthit) : read(caller);
  float3 pos : write(closesthit) : read(caller);
  float3 nrm : write(closesthit) : read(caller);
};

#define RayPayloadKHR 5338
[[vk::ext_storage_class(RayPayloadKHR)]] static HitPayload payload;

Here is the declaration of a few invocation reordering functions:

[[vk::ext_instruction(OpHitObjectRecordEmptyNV)]]
void hitObjectRecordEmptyNV([[vk::ext_reference]] HitObjectNV hitObject);

[[vk::ext_instruction(OpHitObjectTraceRayNV)]]
void hitObjectTraceRayNV(
    [[vk::ext_reference]] HitObjectNV hitObject,
    RaytracingAccelerationStructure as,
    uint RayFlags,
    uint CullMask,
    uint SBTOffset,
    uint SBTStride,
    uint MissIndex,
    float3 RayOrigin,
    float RayTmin,
    float3 RayDirection,
    float RayTMax,
    [[vk::ext_reference]] [[vk::ext_storage_class(RayPayloadKHR)]] HitPayload payload
  );

[[vk::ext_instruction(OpReorderThreadWithHintNV)]]
void reorderThreadWithHintNV(int Hint, int Bits);

[[vk::ext_instruction(OpReorderThreadWithHitObjectNV)]]
void reorderThreadWithHitObjectNV([[vk::ext_reference]] HitObjectNV hitObject);

[[vk::ext_instruction(OpHitObjectExecuteShaderNV)]]
void hitObjectExecuteShaderNV([[vk::ext_reference]] HitObjectNV hitObject, [[vk::ext_reference]] [[vk::ext_storage_class(RayPayloadKHR)]] HitPayload payload);

[[vk::ext_instruction(OpHitObjectIsHitNV)]]
bool hitObjectIsHitNV([[vk::ext_reference]] HitObjectNV hitObject);

Using the function in the code, can be done like this

  if (USE_SER == 1)
  {
    createHitObjectNV();
    HitObjectNV hObj; //  hitObjectNV hObj;
    hitObjectRecordEmptyNV(hObj); //Initialize to an empty hit object
    hitObjectTraceRayNV(hObj, topLevelAS, rayFlags, 0xFF, 0, 0, 0, r.Origin, 0.0, r.Direction, INFINITE, payload);
    reorderThreadWithHitObjectNV(hObj);
    hitObjectExecuteShaderNV(hObj, payload);
  }

Note:

  • createHitObjectNV() needs to be call at least once. This can be also done in the main entry of the shader.
  • Function with a payload parameter, needs to have the payload struct defined before. There are no templated declaration of the function.

Version History

  • Revision 1, 2020-09-12 (Eric Werness, Ashwin Lele)

    • Initial external release

See Also

PhysicalDeviceRayTracingInvocationReorderFeaturesNV, PhysicalDeviceRayTracingInvocationReorderPropertiesNV, RayTracingInvocationReorderModeNV

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

data PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source #

VkPhysicalDeviceRayTracingInvocationReorderFeaturesNV - Structure describing feature to control ray tracing invocation reordering

Members

This structure describes the following feature:

Description

If the PhysicalDeviceRayTracingInvocationReorderFeaturesNV structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDeviceRayTracingInvocationReorderFeaturesNV can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_NV_ray_tracing_invocation_reorder, Bool32, StructureType

Constructors

PhysicalDeviceRayTracingInvocationReorderFeaturesNV 

Fields

Instances

Instances details
Storable PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Show PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Eq PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

FromCStruct PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

ToCStruct PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Zero PhysicalDeviceRayTracingInvocationReorderFeaturesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

data PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source #

VkPhysicalDeviceRayTracingInvocationReorderPropertiesNV - Structure describing shader module identifier properties of an implementation

Description

Note

Because the extension changes how hits are managed there is a compatibility reason to expose the extension even when an implementation does not have sorting active.

If the PhysicalDeviceRayTracingInvocationReorderPropertiesNV structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Valid Usage (Implicit)

See Also

VK_NV_ray_tracing_invocation_reorder, RayTracingInvocationReorderModeNV, StructureType

Constructors

PhysicalDeviceRayTracingInvocationReorderPropertiesNV 

Fields

Instances

Instances details
Storable PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Show PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Eq PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

FromCStruct PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

ToCStruct PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Zero PhysicalDeviceRayTracingInvocationReorderPropertiesNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

newtype RayTracingInvocationReorderModeNV Source #

VkRayTracingInvocationReorderModeNV - Enum providing a hint on how the application may reorder

See Also

VK_NV_ray_tracing_invocation_reorder, PhysicalDeviceRayTracingInvocationReorderPropertiesNV

Bundled Patterns

pattern RAY_TRACING_INVOCATION_REORDER_MODE_NONE_NV :: RayTracingInvocationReorderModeNV

RAY_TRACING_INVOCATION_REORDER_MODE_NONE_NV indicates that the implementation is likely to not reorder at reorder calls.

pattern RAY_TRACING_INVOCATION_REORDER_MODE_REORDER_NV :: RayTracingInvocationReorderModeNV

RAY_TRACING_INVOCATION_REORDER_MODE_REORDER_NV indicates that the implementation is likely to reorder at reorder calls.

Instances

Instances details
Storable RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Read RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Show RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Eq RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Ord RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

Zero RayTracingInvocationReorderModeNV Source # 
Instance details

Defined in Vulkan.Extensions.VK_NV_ray_tracing_invocation_reorder

type NV_RAY_TRACING_INVOCATION_REORDER_EXTENSION_NAME = "VK_NV_ray_tracing_invocation_reorder" Source #