Ray Tracing

Defines

D3D_HAS_RAY_TRACING

Enums

enum class RaytraceBuildFlags : uint32_t

Values:

enumerator NONE

enumerator ALLOW_UPDATE

enumerator ALLOW_COMPACTION

enumerator FAST_TRACE

enumerator FAST_BUILD

enumerator LOW_MEMORY

enum class RaytraceShaderType

Values:

enumerator RAYGEN

enumerator ANY_HIT

enumerator CLOSEST_HIT

enumerator MISS

enumerator INTERSECTION

enumerator CALLABLE

enum class RaytraceShaderGroupType

Values:

enumerator GENERAL

enumerator TRIANGLES_HIT

enumerator PROCEDURAL_HIT

Functions

DAGOR_ENABLE_ENUM_BITMASK(RaytraceGeometryDescription::Flags)

DAGOR_ENABLE_ENUM_BITMASK(RaytraceBuildFlags)

struct RaytraceAnyAccelerationStructure

#include <dag_drvRayTrace.h>

Public Functions

RaytraceAnyAccelerationStructure() = default

RaytraceAnyAccelerationStructure(const RaytraceAnyAccelerationStructure&) = default

RaytraceAnyAccelerationStructure &operator=(const RaytraceAnyAccelerationStructure&) = default

inline RaytraceAnyAccelerationStructure(RaytraceTopAccelerationStructure *t)

inline RaytraceAnyAccelerationStructure(RaytraceBottomAccelerationStructure *b)

inline explicit operator bool() const

Public Members

RaytraceTopAccelerationStructure *top = nullptr

RaytraceBottomAccelerationStructure *bottom = nullptr

struct RaytraceAccelerationStructureGpuHandle

#include <dag_drvRayTrace.h>

Public Members

uint64_t handle

struct RaytraceGeometryDescription

#include <dag_drvRayTrace.h>

Public Types

enum class Flags : uint32_t

Values:

enumerator NONE

enumerator IS_OPAQUE

enumerator NO_DUPLICATE_ANY_HIT_INVOCATION

enum class Type

Values:

enumerator TRIANGLES

enumerator AABBS

Public Members

Type type = Type::TRIANGLES 

AnyInfo data = {}

struct AABBsInfo

#include <dag_drvRayTrace.h>

Public Members

Sbuffer *buffer

uint32_t count

uint32_t stride

uint32_t offset

Flags flags

union AnyInfo

#include <dag_drvRayTrace.h>

Public Members

AABBsInfo aabbs

TrianglesInfo triangles

struct TrianglesInfo

#include <dag_drvRayTrace.h>

Public Members

Sbuffer *transformBuffer

Sbuffer *vertexBuffer

Sbuffer *indexBuffer

uint32_t transformOffset

uint32_t vertexCount

uint32_t vertexStride

uint32_t vertexOffset

uint32_t vertexOffsetExtraBytes

uint32_t vertexFormat

uint32_t indexCount

uint32_t indexOffset

Flags flags

struct RaytraceGeometryInstanceDescription

#include <dag_drvRayTrace.h>

Public Types

enum Flags

Values:

enumerator NONE

enumerator TRIANGLE_CULL_DISABLE

enumerator TRIANGLE_CULL_FLIP_WINDING

enumerator FORCE_OPAQUE

enumerator FORCE_NO_OPAQUE

Public Members

float transform[12]

uint32_t instanceId

uint32_t mask

uint32_t instanceOffset

uint32_t flags

RaytraceBottomAccelerationStructure *accelerationStructure

uint32_t paddToMatchTarget

struct RaytraceShaderGroup

#include <dag_drvRayTrace.h>

Public Members

RaytraceShaderGroupType type

uint32_t indexToGeneralShader

uint32_t indexToClosestHitShader

uint32_t indexToAnyHitShader

uint32_t indexToIntersecionShader

namespace raytrace

Typedefs

using AccelerationStructureSizeCalculcationInfo = eastl::variant<TopAccelerationStructureSizeCalculcationInfo, BottomAccelerationStructureSizeCalculcationInfo>: Represents either TLAS or BLAS size calculation info.

using BottomAccelerationStructure = RaytraceBottomAccelerationStructure

using TopAccelerationStructure = RaytraceTopAccelerationStructure

using AnyAccelerationStructure = RaytraceAnyAccelerationStructure 

using AccelerationStructurePlacementInfo = eastl::variant<TopAccelerationStructurePlacementInfo, BottomAccelerationStructurePlacementInfo>: Placement information of a TLAS or a BLAS in a raytrace acceleration structure pool.

Enums

enum class AccelerationStructureBuildMode

Values:

enumerator Synchronous: Build process is executed as normal and the build results are usable right away.

enumerator FrameParallel: This allows the driver to move the build process to a execution queue that is executing builds in parallel to the current frame. Those builds are required to be completed before the next frame starts (eg aiming for the end of current frame). This mode aims to minimizes the impact for the build process to the frame time of the current frame with a simple rules change. All builds with this mode will be executed in order by one queue, this means that resource regions, like scratch buffer regions used by this build process are unavailable for builds with other modes than this mode, but can be used again with builds with FrameParallel build mode in the same frame. Constant resources, like source acceleration structures for compaction, vertex index and other buffers, are still usable as normal during the frame, as long as they are not modified during the frame in a way that would affect the build command. So updating a region of a vertex buffer that is not used by the build command during the frame is perfectly fine, but a region the is used by the build command, may be not. This is because the driver may reorders internally the order in which copies to buffers and the execution of build commands on the parallel queue is executed on the GPU. Should any resource used by build commands with this mode, be deleted during the current frame, the driver has to ensure that the resources are valid until the build command is completed.

enum class ShaderGroup

Describes which kind of shader group a shader belongs to.

Values:

enumerator Undefined: Undefined, indicates that ShaderGroupMember is uninitialized.

enumerator RayGen: Shader group is of RayGenShaderGroupMember type.

enumerator Miss: Shader group is of MissShaderGroupMember type.

enumerator Callable: Shader group is of CallableShaderGroupMember type.

enumerator Triangle: Shader group is of TriangleShaderGroupMember type.

enumerator Procedural: Shader group is of ProceduralShaderGroupMember type.

Functions

AccelerationStructurePool create_acceleration_structure_pool(const AccelerationStructurePoolCreateInfo &info)

Creates a new pool for acceleration structures. Returns InvalidAccelerationStructurePool on error or when pools are not supported. A value other than 0 of DeviceDriverRaytraceProperties::accelerationStructurePoolSizeAlignment indicates supports for pools. Cause for error may be:

Invalid input
Insufficient space to satisfy the requested allocation size
Device error

Parameters:: info – The properties of the pool to create.
Returns:: A new pool object or InvalidAccelerationStructurePool to indicate an error.

void destroy_acceleration_structure_pool(AccelerationStructurePool pool)

Destroys the given acceleration structure pool. Implicitly destroys all TLAS and BLAS created from the given pool. Drivers will ensure that pending uses of the pool will be executed safely before the pool is actually freed. This may result in a delayed freeing of the used memory of the pool.

Parameters:: pool – The ray trace acceleration structure pool to delete.

RaytraceAccelerationStructureGpuHandle get_pool_base_address(AccelerationStructurePool pool)

Returns the base address (address at offset 0) of the acceleration structure pool. This can be used to calculate GPU addresses for BLAS and TLAS. This address will remain constant for the entire lifetime duration of the pool. Returned value may be 0 on drivers without proper GPU address support.

Parameters:: pool – The pool to query the base GPU address of.
Returns:: A valid GPU address or 0, depending on the driver support.

AccelerationStructureSizes calculate_acceleration_structure_sizes(const AccelerationStructureSizeCalculcationInfo &info)

Calculates all needed sizes for BLAS or TLAS create, build and update. Note this may allocate some temporary memory internally to convert some input data arrays to target APIs data structures.

Parameters:: info – The information about the BLAS or TLAS the size is requested for.
Returns:: Required sizes information or all 0 on error. Cause for error may be invalid inputs to info or a device reset.

AnyAccelerationStructure create_acceleration_structure(AccelerationStructurePool pool, const AccelerationStructurePlacementInfo &placement_info)

Creates a TLAS or BLAS at the given location at the offset specified by ‘placement_info’ in the acceleration structure pool ‘pool’ with the size from ‘placement_info’. offset and size need to be aligned to the system specific (T/B)LAS alignment values. pool is for the time being optional, and can be InvalidAccelerationStructurePool.

Concurrent create invocations with the same pool have to be synchronized as modifying access to the pool object is not thread safe.

May return nullptr on error. Cause for error may be:

when pool is not InvalidAccelerationStructurePool and offset + size is larger than pool size
when pool is not InvalidAccelerationStructurePool and offset is not aligned to the required alignment
size if not aligned to the required alignment
Feature unsupported

Parameters:

pool – The pool where the TLAS / BLAS should be placed.
placement_info – Information on where to place the TLAS / BLAS in pool.

Returns:

A TLAS or BLAS object on success or nullptr on error.

void destroy_acceleration_structure(AccelerationStructurePool pool, AnyAccelerationStructure structure)

Destroys a acceleration struct, pool has to be the pool where the structure was allocated from. Providing mismatching pool and structure results in undefined behavior, it may work or it may cause memory corruptions and errors.

Parameters:

pool – The pool where the TLAS / BLAS was placed into.
structure – TLAS / BLAS to destroy.

void build_acceleration_structure(AccelerationStructureBuildParameters build_params, AccelerationStructureBuildMode build_mode = AccelerationStructureBuildMode::Synchronous): Issues a build command with the given parameters and mode. See AccelerationStructureBuildParameters and AccelerationStructureBuildMode for details.

Pipeline create_pipeline(const PipelineCreateInfo &pci): Creates a new pipeline object with the given properties defined by the ‘pci’ parameter. May return InvalidPipeline on an error. In case of a device reset, the pipeline becomes unusable and has to be destroyed and recreated.

Pipeline expand_pipeline(const Pipeline &pipeline, const PipelineExpandInfo &pei): Tries to expand a existing pipeline object. This will return a new pipeline object, the old one is can still be used normally (and concurrently) and is kept as is and may be destroyed at any time with destroy_pipeline should the new object replace the old one. May return InvalidPipeline on an error or when an expansion was not be possible. This is to be cheaper than ‘create_pipeline’ with the same existing and added shaders, when the driver supports pipeline expansion natively. In any case it should not perform worse than ‘create_pipeline’. Native support for pipeline expansion is not required. In some cases, driver may not be able to expand the pipeline, even when native expansion is supported, this may be because of various cases, like pipeline layout / root signature not being able to supply all the resource slots needed by the expanded pipeline.

void destroy_pipeline(Pipeline &p): Destroys a pipeline object, pending ray dispatches will be guaranteed to be executed before the object is actually destroyed. This function will not block to make this guarantee.

ShaderBindingTableBufferProperties get_shader_binding_table_buffer_properties(const ShaderBindingTableDefinition &sbtd, const Pipeline &pipeline): Calculates the properties of a buffer to be use as a shader binding table with the given properties. Returns default initialized data structure on error and on success values to create a sbuffer for shader binding table use.

void dispatch(const ResourceBindingTable &rbt, const Pipeline &pipeline, const RayDispatchParameters &rdp, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS): Dispatches the ray gen shader rederenced by the ‘shaderBindingTableSet’ member of ‘rdp’ with the grid parameters of ‘rdp’. All resource usages are defined by ‘rbt’ any resource slot undefined will use a null resource. All shaders that may be invoked directly or indirectly by this dispatch have to be part of ‘pipeline’.

void dispatch_indirect(const ResourceBindingTable &rbt, const Pipeline &pipeline, const RayDispatchIndirectParameters &rdip, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS): Indirect dispatch of the ray gen shader referenced by each entry in the indirect buffer, the indirect invocation will be executed the number of times the ‘count’ member of ‘rdip’ declares. All resource usages are defined by ‘rbt’ any resource slot undefined will use a null resource. All shaders that may be invoked directly or indirectly by this dispatch have to be part of ‘pipeline’.

void dispatch_indirect_count(const ResourceBindingTable &rbt, const Pipeline &pipeline, const RayDispatchIndirectCountParameters &rdicp, GpuPipeline gpu_pipeline = GpuPipeline::GRAPHICS): Indirect dispatch of the ray gen shader referenced by each entry in the indirect buffer, the indirect invocation will be executed the number of times the value at the count buffer is at the time of the invocation on the execution device, however this value can not exceed the value of ‘maxCount’ member of ‘rdip’ declares. All resource usages are defined by ‘rbt’ any resource slot undefined will use a null resource. All shaders that may be invoked directly or indirectly by this dispatch have to be part of ‘pipeline’.

Variables

constexpr Pipeline InvalidPipeline = {}: Represents a “null pointer” to a pipeline object.

struct AccelerationStructureBuildParameters

#include <dag_drvRayTrace.h>

Holds all data for a acceleration structure build command. The structure allows to issue builds of top and bottom structures at the same time. The execution order of the data structure is as follows: 1) Build all bottom level structures 2) Flush bottom level builds, when requested 3) Build all top level structures 4) Flush top level builds, when requested

Public Members

eastl::span<BatchedBottomAccelerationStructureBuildInfo> bottomBuilds: Span of bottom level acceleration structures to build TODO can not be const for the moment…

eastl::span<BatchedTopAccelerationStructureBuildInfo> topBuilds: Span of top level acceleration structures to build TODO can not be const for the moment…

bool flushAfterBottomBuild = false: Should the driver automatically insert a barrier to flush all bottom builds. Beware of that some drivers will always do a flush after a batch of builds.

bool flushAfterTopBuild = false: Should the driver automatically insert a barrier to flush all top builds. Beware of that some drivers will always do a flush after a batch of builds.

struct AccelerationStructurePoolCreateInfo

#include <dag_drvRayTrace.h>

Properties of a acceleration structure pool should be created.

Public Members

const char *debugName = nullptr: Debug name for the pool, will be the name shown on buffers in tools like PIX on DX12.

uint32_t sizeInBytes = 0: Total pool size for any kind of structure, must be aligned to the platforms pool size alignment DeviceDriverRaytraceProperties::accelerationStructurePoolSizeAlignment.

uint32_t topLevelStructureCountHint = 0: A hint on how many TLAS are going to be allocated from this pool. Drivers can use this hint to pre allocate some TLAS specific data, like on DX12 a small descriptor heap for TLAS descriptors can be allocated.

uint32_t bottomLevelStructureCountHint = 0: A hint on how many BLAS are going to be allocated from the pool. Drivers can use this hint to pre allocate some BLAS specific data.

struct AccelerationStructureSizes

#include <dag_drvRayTrace.h>

Holds sizes to create, build and update acceleration structures. This may be calculated by calculate_acceleration_structure_sizes.

Public Members

uint32_t structureSizeInBytes = 0: Size requirement for the structure.

uint32_t buildScratchBufferSizeInBytes = 0: Scratch space required for re-build commands (non updates).

uint32_t updateScratchBufferSizeInBytes = 0: Scratch space required for update build commands, only valid when update support is requested.

struct BatchedBottomAccelerationStructureBuildInfo

#include <dag_drvRayTrace.h>

Public Members

RaytraceBottomAccelerationStructure *as = nullptr: The BLAS for an element of a batched BLAS build.

BottomAccelerationStructureBuildInfo basbi: The descriptor for an element of a batched BLAS build.

struct BatchedTopAccelerationStructureBuildInfo

#include <dag_drvRayTrace.h>

Public Members

RaytraceTopAccelerationStructure *as = nullptr: The TLAS for an element of a batched BLAS build.

TopAccelerationStructureBuildInfo tasbi: The TLAS for an element of a batched BLAS build.

struct BottomAccelerationCreateInfo

#include <dag_drvRayTrace.h>

Subclassed by raytrace::BottomAccelerationStructureBuildInfo

Public Members

const RaytraceGeometryDescription *geometryDesc = nullptr: An array of geometry descriptions that describes all the geometry the structure should encapsulate.

uint32_t geometryDescCount = 0: Array size of geometryDesc.

RaytraceBuildFlags flags = RaytraceBuildFlags::NONE : Flags that influence some characteristics and valid usage of the structure.

struct BottomAccelerationStructureBuildInfo : public raytrace::BottomAccelerationCreateInfo 

#include <dag_drvRayTrace.h>

Provides all necessary information to build or update a ray trace bottom acceleration structure.

Public Members

bool doUpdate = false: Do an update instead of a rebuild. Only valid to use when previous rebuilds had the flag RaytraceBuildFlags::ALLOW_UPDATE set.

Sbuffer *compactedSizeOutputBuffer = nullptr: Needs to be set when RaytraceBuildFlags::ALLOW_COMPACTION flag is set, otherwise ignored. At the end of the build process, the GPU will write the required size of a compacted variant of resulting data structure content to this buffer at the offset location. This can be used to create smaller compacted acceleration structures.

uint32_t compactedSizeOutputBufferOffsetInBytes = 0: Ignored when compactedSizeOutputBuffer is nullptr. compactedSizeOutputBuffer has to be large enough to store a uint64_t at that offset. Offset has to be 64 bit aligned.

Sbuffer *scratchSpaceBuffer = nullptr: Buffer that provides scratch space needed for the build, size requirements are derived from scratchSpaceBufferOffsetInBytes + scratchSpaceBufferSizeInBytes.

Note

Multiple builds can safely use the same buffer without synchronization as long as they do not overlap in used region of the buffer.

Note

May be nullptr when the corresponding scratch buffer size provided by d3d::create_raytrace_bottom_acceleration_structure was 0.

Note

A frame end is a implicit flush of every buffer. So no synchronization in between frames is needed.

Warning

Currently this is optional, but this behavior is deprecated until all users have updated to provide this buffer when needed.

uint32_t scratchSpaceBufferOffsetInBytes = 0: Offset into scratchSpaceBuffer, buffer has to be large enough to provide space for scratchSpaceBufferOffsetInBytes + scratchSpaceBufferSizeInBytes.

uint32_t scratchSpaceBufferSizeInBytes = 0: Usable space of scratchSpaceBuffer, this has to be at least as large as the provided build_scratch_size_in_bytes value for the build structure for a rebuild or update_scratch_size_in_bytes for updates.

struct BottomAccelerationStructurePlacementInfo

#include <dag_drvRayTrace.h>

Placement information of a BLAS in a raytrace acceleration structure pool.

Public Members

uint32_t offsetInBytes = 0: Offset where to place the BLAS in the pool. Has to be aligned to DeviceDriverRaytraceProperties::accelerationStructurePoolOffsetAlignment.

uint32_t sizeInBytes = 0: Size if the TLAS to place in the pool. offsetInBytes + this value can not exceed the size of the target pool.

struct BottomAccelerationStructureSizeCalculcationInfo

#include <dag_drvRayTrace.h>

Hold the information to calculate the required size of a BLAS.

Public Members

dag::ConstSpan<const RaytraceGeometryDescription> geometryDesc: Array of descriptions of the geometry that is supposed to be represented by the BLAS.

RaytraceBuildFlags flags = RaytraceBuildFlags::NONE : Build flags that may be used with the TLAS, they may influence some sizes.

struct CallableShaderGroupMember

#include <dag_drvRayTrace.h>

Shader group describing a callable group.

Public Members

ShaderInLibraryReference callable: Reference of a callable shader Has to be a valid reference.

struct MissShaderGroupMember

#include <dag_drvRayTrace.h>

Shader group describing a miss group.

Public Members

ShaderInLibraryReference miss: Reference of a miss shader in a shader library. Has to be a valid reference.

class Pipeline

#include <dag_drvRayTrace.h>

Pipeline type, wraps a pipeline object and shader handle table. Drivers that implement pipelines should implement a derived type of this, that provides a appropriate constructor and access to the internals when needed. To adapt input pipelines this can be achieved by a “copy” constructor that uses the copy constructor of this type to initialize the derived object.

Public Functions

constexpr Pipeline() = default

Pipeline(const Pipeline&) = default

Pipeline &operator=(const Pipeline&) = default

Pipeline(Pipeline&&) = default

Pipeline &operator=(Pipeline&&) = default

inline uint32_t getShaderCount() const: Returns the number of shaders the pipeline object makes usable.

inline dag::ConstSpan<const uint8_t> getShaderHandle(uint32_t index) const: Returns a shader handle pointer with a size returned by getShaderHandleSize.

inline void writeShaderHandleTo(uint32_t index, dag::Span<uint8_t> target) const: Helper to copy a shader handle at the target memory location.

inline uint32_t getShaderHandleSize() const: Retrieves the size of a handle returned by getShaderHandle.

Protected Functions

inline Pipeline(void *obj, const uint8_t *sht, uint32_t shs, uint32_t sc): Drivers implementing this should create a derived type to gain access to this constructor.

Protected Attributes

void *driverObject = nullptr: Object handle for the driver.

const uint8_t *shaderHandleTable = nullptr: Shader handle table of all shaders of that pipeline, in the order they where defined during creation and expansion.

uint32_t shaderHandleSize = 0: Size in bytes of a single shader handle in shaderHandleTable.

uint32_t shaderCount = 0: Number of shaders of the pipeline and in shaderHandleTable.

Friends

inline friend bool operator==(const Pipeline &l, const Pipeline &r)

inline friend bool operator!=(const Pipeline &l, const Pipeline &r)

struct PipelineCreateInfo : public raytrace::PipelineExpandInfo 

#include <dag_drvRayTrace.h>

Describes creation data for a new pipeline.

Public Members

dag::ConstSpan<const ShaderLibrary> rayGenForwardRefernces: The pipeline should be prepared to add any ray gen shaders from the set of libraries. Having a pipeline prepared for any library increases the likelihood that a expand will work and does not require a recreate.

dag::ConstSpan<const ShaderLibrary> missForwardReferences: The pipeline should be prepared to add any miss shaders from the set of libraries. Having a pipeline prepared for any library increases the likelihood that a expand will work and does not require a recreate.

dag::ConstSpan<const ShaderLibrary> hitForwardRefrences: The pipeline should be prepared to add any hit shaders from the set of libraries. Having a pipeline prepared for any library increases the likelihood that a expand will work and does not require a recreate.

dag::ConstSpan<const ShaderLibrary> callableForwardReferences: The pipeline should be prepared to add any callable shaders from the set of libraries. Having a pipeline prepared for any library increases the likelihood that a expand will work and does not require a recreate.

uint32_t maxRecursionDepth = 0: Max number of recursion depth, has to be less or equal to Driver3dDesc::raytraceMaxRecursion. With 0 the driver will try to guess on basis of some meta data of all used shaders. A min value of 1 means that the RayGen shader is the only shader that can shoot rays.

uint32_t maxPayloadSize = 0: Max payload size, in bytes, that is transmitted from hit and miss shaders to ray cast invocations. With 0 the driver will try to guess on basis of some meta data of all used shaders.

uint32_t maxAttributeSize = 0: Max size of attributes, usually this is 2 * size of float, for build-in triangle intersection, but for procedural intersection this can be anything. With 0 and no procedural hit groups, the driver will assume 2 * size of float, otherwise it will guess on basis of some meta data of all used procedural hit groups and triangle hit groups.

struct PipelineExpandInfo

#include <dag_drvRayTrace.h>

Describes a expansion of a existing pipeline.

Subclassed by raytrace::PipelineCreateInfo

Public Members

const char *name = nullptr: Debug name of the pipeline.

dag::ConstSpan<const ShaderGroupMember> groupMemebers: A set of shader group members that should be appended to the pipeline, in the order they appear in the array.

bool expandable = false: Indicates that the pipeline may be expanded over time with calls to expand_pipeline. Calls to expand_pipeline without this flag are invalid. This flag is not inherited by the expanded pipeline and has to be set on expansion when the expanded pipeline should be capable to be further expanded.

bool alwaysIgnoreTriangleGeometry = false: Pipelines with this flag will always ignore triangle geometry during traversal. Requires the hasRayTraceSkipPrimitiveType feature to be available, otherwise pipeline create / expand will fail.

bool alwaysIgnoreProceduralGeometry = false: Pipelines with this flag will always ignore procedural geometry during traversal. Requires the hasRayTraceSkipPrimitiveType feature to be available, otherwise pipeline create / expand will fail.

struct ProceduralShaderGroupMember : public raytrace::TriangleShaderGroupMember 

#include <dag_drvRayTrace.h>

Shader group describing a procedural hit group.

Public Members

ShaderInLibraryReference intersection: Reference of a intersection shader Has to be a valid reference.

struct RayDispatchGroup

#include <dag_drvRayTrace.h>

A ray dispatch group definition.

Subclassed by raytrace::RayDispatchGroupTable

Public Members

uint64_t virtualGpuAddress: Virtual GPU address to the beginning of the shader binding table of that group.

uint64_t sizeInBytes: Total size of the group in the shader binding table.

struct RayDispatchGroupTable : public raytrace::RayDispatchGroup 

#include <dag_drvRayTrace.h>

A ray dispatch group definition, for groups with multiple entries.

Public Members

uint64_t strideInBytes: Stride in bytes of a entry of the group in the shader binding table.

struct RayDispatchGroupTableSet

#include <dag_drvRayTrace.h>

Table of shader groups for ray dispatches.

Public Members

RayDispatchGroup rayGen: Properties of the ray gen shader group.

RayDispatchGroupTable miss: Properties of the miss shader group.

RayDispatchGroupTable hit: Properties of the hit shader group.

RayDispatchGroupTable callable: Properties of the callable shader group.

struct RayDispatchIndirectArguments

#include <dag_drvRayTrace.h>

Describes the memory layout of a indirect dispatch command entry.

Public Members

RayDispatchGroupTableSet dispatchTableSet: Dispatch table set that should be used by the indirect command.

uint32_t width: Dispatch grid width.

uint32_t height: Dispatch grid height.

uint32_t depth: Dispatch grid depth.

struct RayDispatchIndirectBaseParameters

#include <dag_drvRayTrace.h>

Common parameters for a indirect dispatch command, with and without a count buffer.

Subclassed by raytrace::RayDispatchIndirectCountParameters, raytrace::RayDispatchIndirectParameters

Public Members

Sbuffer *indirectBuffer: Buffer storing indirect values of the type ‘RayDispatchIndirectArguments’.

uint32_t indirectByteOffset: Offset into ‘directBuffer’, value has to be aligned to <TODO>.

uint32_t indirectByteStride: Stride of each entry in ‘indirectBuffer’, value has to be aligned to <TODO>.

struct RayDispatchIndirectCountParameters : public raytrace::RayDispatchIndirectBaseParameters 

#include <dag_drvRayTrace.h>

Parameters for a indirect dispatch command, with a count fetched from a buffer, with a upper limit.

Public Members

Sbuffer *countBuffer: Buffer that holds the counter of indirect invocations.

uint32_t countByteOffset: Offset into ‘countBuffer’, has to be aligned to <TODO>

uint32_t maxCount: The value read from ‘countBuffer’ can not exceed this value.

struct RayDispatchIndirectParameters : public raytrace::RayDispatchIndirectBaseParameters 

#include <dag_drvRayTrace.h>

Parameters for a indirect dispatch command, with predefined count.

Public Members

uint32_t count: Number of indirect dispatches to execute.

struct RayDispatchParameters

#include <dag_drvRayTrace.h>

Parameters of a ray dispatch command.

Public Members

ShaderBindingTableSet shaderBindingTableSet: Shader binding table set.

uint32_t width: Dispatch grid width.

uint32_t height: Dispatch grid height.

uint32_t depth: Dispatch grid depth.

struct RayGenShaderGroupMember

#include <dag_drvRayTrace.h>

Shader group describing a ray gen group.

Public Members

ShaderInLibraryReference rayGen: Reference of a ray gen shader in a shader library. Has to be a valid reference.

struct ResourceBindingTable

#include <dag_drvRayTrace.h>

Resource binding table, order is not important. Slots that are undefined by this table that are used by the pipeline of the dispatch will be using the corresponding null resource. Definitions by this table with null for resource references will be ignored and do not contribute to possible slot usage clashes. ‘constantBufferReads’ use the ‘b’ register space. ‘bufferReads’, ‘textureReads’ and ‘accelerationStructureReads’ use the ‘t’ register space. ‘bufferWrites’ and ‘textureWrites’ use the ‘u’ register space. Behavior is undefined when slot usages clash. A usage clash happens when the same register slot of the same register space is used by multiple resource usage definitions, for example if ‘bufferReads’ has a entry with a ‘slot’ value and ‘textureReads’ has a entry with a ‘slot’ with the same value.

Public Members

dag::ConstSpan<const uint32_t> immediateConstants: Constant data that is supposed to be pushed into immediate registers, this data is usually written directly to to the command buffer of the device and update some constant registers of the device.

dag::ConstSpan<ConstBufferRead> constantBufferReads: Binding set of constant buffers.

dag::ConstSpan<BufferRead> bufferReads: Binding set for read only buffers (eg SRV).

dag::ConstSpan<TextureRead> textureReads: Binding set for read only textures (eg SRV).

dag::ConstSpan<AccelerationStructureRead> accelerationStructureReads: Binding set for acceleration structures.

dag::ConstSpan<BufferWrite> bufferWrites: Binding set for read write buffers (eg UAV).

dag::ConstSpan<TextureWrite> textureWrites: Binding set for read write textures (eg UAV).

dag::ConstSpan<SamplerRead> samples: Binding set for samplers.

struct AccelerationStructureRead

#include <dag_drvRayTrace.h>

Defines a acceleration structure read on a t register slot.

Public Members

RaytraceTopAccelerationStructure *structure = nullptr: Acceleration structure to read from.

uint32_t slot = 0: t register slot

struct BufferRead

#include <dag_drvRayTrace.h>

Defines a buffer read on a t register slot.

Public Members

Sbuffer *buffer = nullptr: Buffer to read from.

uint32_t slot = 0: t register slot

struct BufferWrite

#include <dag_drvRayTrace.h>

Defines a buffer write on a u register slot.

Public Members

Sbuffer *buffer = nullptr: Buffer to write to.

uint32_t slot = 0: u register slot

struct ConstBufferRead

#include <dag_drvRayTrace.h>

Defines a constant buffer read on a b register slot.

Public Members

Sbuffer *buffer = nullptr: Buffer to read from.

uint32_t slot = 0: b register slot

uint32_t offsetInBytes = 0: Offset to read from buffer.

uint32_t sizeInBytes = 0: Size of the constant data range.

struct SamplerRead

#include <dag_drvRayTrace.h>

Defines a sampler read on a s register slot.

Public Members

d3d::SamplerHandle sampler = d3d::INVALID_SAMPLER_HANDLE: Sampler to read.

uint32_t slot = 0: s register slot

struct TextureRead

#include <dag_drvRayTrace.h>

Defines a texture read on a t register slot.

Public Members

BaseTexture *texture = nullptr: Texture to read from.

uint32_t slot = 0: t register slot

struct TextureWrite

#include <dag_drvRayTrace.h>

Defines a texture write on a u register slot.

Public Members

BaseTexture *texture = nullptr: Texture to write to.

uint32_t slot = 0: u register slot

uint32_t mipIndex = 0: Mip map level to write to.

uint32_t arrayIndex = 0: Array layer to write to.

bool viewAsUI32 = false: Access data as an uint32.

struct ShaderBindingTableBufferProperties

#include <dag_drvRayTrace.h>

The driver calculated properties of the shader binding table to be used with create_sbuffer to create a buffer that can be used as shader binding table. Typical use is: auto props = get_shader_binding_table_buffer_properties(myBindingTableProperties, myPipeline); auto buf = d3d::create_sbuffer(props.createStructSize, props.calculateElementCount({ray_gen_count, miss_count, hit_count, call_count}), props.createFlags, props.createFormat, “my shader binding table buffer”);

Public Functions

inline uint32_t calculateElementCount(const GroupCounts &counts) const: Calculates the number of elements input for sbuffer create.

Public Members

uint32_t createStructSize = 0: Structure size that has to be used with create_sbuffer. Using a different value may result in a device reset. Only 0 on error, otherwise larger than 0.

uint32_t createFlags = 0: Create flags required to pass to create_sbuffer. Using different flags may result in device reset or the buffer being not usable as a shader binding table.

uint32_t createFormat = 0: Create format required to pass to create_sbuffer. Using a different format may result in device reset or the buffer being not usable as a shader binding table.

uint32_t groupOffsetAlignmentSizeInBytes = 0: Offsets of each group has to be aligned to this value. Note that this may be (and will be on DX12) different than ShaderBindingTableGroupProperties::entryAlignedSize. Not properly aligning the offsets may result in a device reset.

ShaderBindingTableGroupProperties rayGenGroup: Properties of the ray gen shader groups.

ShaderBindingTableGroupProperties missGroup: Properties of the miss shader groups.

ShaderBindingTableGroupProperties hitGroup: Properties of the hit shader groups.

ShaderBindingTableGroupProperties callableGroup: Properties of the callable groups.

struct GroupCounts

#include <dag_drvRayTrace.h>

Counts of shader groups to calculate the size of a buffer used as a shader binding table.

Public Members

uint32_t rayGenGroupCount = 0: Number of ray gen shader groups. Usually 1.

uint32_t missGroupCount = 0: Number of miss shader groups. Usually 1.

uint32_t hitGroupCount = 0: Number of hit shader groups.

uint32_t callableGroupCount = 0: Number of callable groups.

struct ShaderBindingTableDefinition

#include <dag_drvRayTrace.h>

Describes a shader binding table layout.

Public Members

ShaderBindingTableGroupInfo rayGenGroup: Properties of the ray gen group.

ShaderBindingTableGroupInfo missGroup: Properties of the miss group.

ShaderBindingTableGroupInfo hitGroup: Properties of the hit group.

ShaderBindingTableGroupInfo callableGroup: Properties of the callable group.

uint32_t bufferCreateFlags = 0: Create flags the buffer should have. Note that some usages are not working (well), like formatted srv / uav uses, use instead byte address or structured. Note be mindful of the create flags, as this table is used during the execution dispatch command to kick off all sorts of shaders on each ray cast and shader call will read from the table.

struct ShaderBindingTableGroupInfo

#include <dag_drvRayTrace.h>

Properties for any shader group a shader binding table.

Public Members

uint32_t minResourceReferences = 0: Minimum of resources references the shader record has to be able to store. As this is a minimum, the driver may use more for total size calculation should shaders in that shader group need more space. In most cases, leaving this as 0 is fine.

uint32_t minConstantDataSizeInBytes = 0: Minimum number of bytes of constant data the shader record has to be able to store. As this is a minimum, the driver may use more for total size calculation should shaders in that shader group need more space. In most cases, leaving this as 0 is fine.

struct ShaderBindingTableGroupProperties

#include <dag_drvRayTrace.h>

Properties of a shader group in a shader binding table.

Public Members

uint32_t dataSizeInBytes = 0: Total size of paired data of a entry of that shader group. This includes resource references and constant data.

uint32_t entryAlignedSizeInBytes = 0: Total size (data plus shader handle) of an entry aligned to the platforms requirement size. This alignment has to be a value that results in valid values for arrays of the shader group. In case of the ray gen group, there are only single values and this means an array of those would be an array of groups not an a group of an array of shader records.

struct ShaderBindingTableOffset

#include <dag_drvRayTrace.h>

Shader binding table entry info for groups with one entry.

Subclassed by raytrace::ShaderBindingTableSubRange

Public Members

Sbuffer *bindingTableBuffer = nullptr: Buffer that hold the binding table entry / entries.

uint32_t offsetInBytes = 0: Offset in the buffer to the first entry.

uint32_t sizeInBytes = 0: Size of each entry, this includes handle size plush shader record size.

struct ShaderBindingTableSet

#include <dag_drvRayTrace.h>

Shader binding table set, it contains all the binding table data for all shader groups.

Public Members

ShaderBindingTableOffset rayGenGroup: ray gen group binding table data.

ShaderBindingTableSubRange missGroup: miss group binding table data.

ShaderBindingTableSubRange hitGroup: hit group binding table data.

ShaderBindingTableSubRange callableGroup: callable group binding table data.

struct ShaderBindingTableSubRange : public raytrace::ShaderBindingTableOffset 

#include <dag_drvRayTrace.h>

Extends ShaderBindingTableOffset by a stride value for groups with more than one entry.

Public Members

uint32_t strideInBytes = 0: Stride from entry to entry.

struct ShaderGroupMember

#include <dag_drvRayTrace.h>

Defines a shader group of a specific type.

Public Functions

ShaderGroupMember() = default: Constructs empty state.

ShaderGroupMember(const ShaderGroupMember&) = default: Default copy constructor.

inline ShaderGroupMember(const RayGenShaderGroupMember &rg): Constructs this with a state that represents a ray gen group.

inline ShaderGroupMember(const MissShaderGroupMember &m): Constructs this with a state that represents a miss group.

inline ShaderGroupMember(const CallableShaderGroupMember &c): Constructs this with a state that represents a callable group.

inline ShaderGroupMember(const TriangleShaderGroupMember &tr): Constructs this with a state that represents a triangle group.

inline ShaderGroupMember(const ProceduralShaderGroupMember &pr): Constructs this with a state that represents a procedural group.

template<typename T> inline void visit(T clb)

Dispatching helper, will switch over the group member and invokes clb with the corresponding union member.

Parameters:: clb – Callback that may receive the rayGen, miss, callable, triangle or procedural member as input.

Public Members

ShaderGroup group = ShaderGroup::Undefined : Indicates to which group this member belongs and which member variable is valid to use.

RayGenShaderGroupMember rayGen: Valid when ‘type’ is of ShaderGroupType::RayGen Specifies a ray gen group

MissShaderGroupMember miss: Valid when ‘type’ is of ShaderGroupType::Miss Specifies a miss group

CallableShaderGroupMember callable: Valid when ‘type’ is of ShaderGroupType::Callable Specifies a callable group

TriangleShaderGroupMember triangle: Valid when ‘type’ is of ShaderGroupType::Triangle Specifies a triangle group

ProceduralShaderGroupMember procedural: Valid when ‘type’ is of ShaderGroupType::Procedural Specifies a procedural group

union raytrace::ShaderGroupMember

struct TopAccelerationStructureBuildInfo

#include <dag_drvRayTrace.h>

Provides all necessary information to build or update a ray trace top acceleration structure.

Public Members

bool doUpdate = false: Do an update instead of a rebuild. Only valid to use when previous rebuilds had the flag RaytraceBuildFlags::ALLOW_UPDATE set.

Sbuffer *instanceBuffer = nullptr: A buffer, filled with instance descriptors.

uint32_t instanceCount = 0: The number of instance descriptors in the instanceBuffer.

Sbuffer *scratchSpaceBuffer = nullptr: Buffer that provides scratch space needed for the build, size requirements are derived from scratchSpaceBufferOffsetInBytes + scratchSpaceBufferSizeInBytes.

Note

Multiple builds can safely use the same buffer without synchronization as long as they do not overlap in used region of the buffer.

Note

May be nullptr when the corresponding scratch buffer size provided by d3d::create_raytrace_top_acceleration_structure was 0.

Note

A frame end is a implicit flush of every buffer. So no synchronization in between frames is needed.

Warning

Currently this is optional, but this behavior is deprecated until all users have updated to provide this buffer when needed.

uint32_t scratchSpaceBufferOffsetInBytes = 0: Offset into scratchSpaceBuffer, buffer has to be large enough to provide space for scratchSpaceBufferOffsetInBytes + scratchSpaceBufferSizeInBytes.

uint32_t scratchSpaceBufferSizeInBytes = 0: Usable space of scratchSpaceBuffer, this has to be at least as large as the provided build_scratch_size_in_bytes value for the build structure for a rebuild or update_scratch_size_in_bytes for updates.

RaytraceBuildFlags flags = RaytraceBuildFlags::NONE : Flags that influence some characteristics and valid usage of the structure.

struct TopAccelerationStructurePlacementInfo

#include <dag_drvRayTrace.h>

Placement information of a TLAS in a raytrace acceleration structure pool.

Public Members

uint32_t offsetInBytes = 0: Offset where to place the TLAS in the pool. Has to be aligned to DeviceDriverRaytraceProperties::accelerationStructurePoolOffsetAlignment.

uint32_t sizeInBytes = 0: Size if the TLAS to place in the pool. offsetInBytes + this value can not exceed the size of the target pool.

struct TopAccelerationStructureSizeCalculcationInfo

#include <dag_drvRayTrace.h>

Hold the information to calculate the required size of a TLAS.

Public Members

uint32_t elementCount = 0: Number of elements a TLAS contains.

RaytraceBuildFlags flags = RaytraceBuildFlags::NONE : Build flags that may be used with the TLAS, they may influence some sizes.

struct TriangleShaderGroupMember

#include <dag_drvRayTrace.h>

Shader group describing a triangle hit group At least one of ‘anyHit’ and ‘closestHit’ members has to be a valid reference.

Subclassed by raytrace::ProceduralShaderGroupMember

Public Members

ShaderInLibraryReference anyHit: Reference of a any hit shader Can be a valid or a null reference.

ShaderInLibraryReference closestHit: Reference of a closest git shader Can be a valid or a null reference.