RTAS Builder - Extensions

Contents

RTAS Builder - Extensions#

oneAPI Level Zero Specification - Version 1.18.31

RTAS Builder - Extension Functions#

zeRTASBuilderCreateExt#

Added in version 1.13

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderCreateExt(ze_driver_handle_t hDriver, const ze_rtas_builder_ext_desc_t *pDescriptor, ze_rtas_builder_ext_handle_t *phBuilder)#

Creates a ray tracing acceleration structure builder object.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

  • The implementation must support ZE_RTAS_EXT_NAME extension.

Parameters:

  • hDriver – [in] handle of driver object

  • pDescriptor – [in] pointer to builder descriptor

  • phBuilder – [out] handle of builder object

Returns:

zeRTASBuilderGetBuildPropertiesExt#

Added in version 1.13

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderGetBuildPropertiesExt(ze_rtas_builder_ext_handle_t hBuilder, const ze_rtas_builder_build_op_ext_desc_t *pBuildOpDescriptor, ze_rtas_builder_ext_properties_t *pProperties)#

Retrieves ray tracing acceleration structure builder properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function must be thread-safe.

Parameters:

  • hBuilder – [in] handle of builder object

  • pBuildOpDescriptor – [in] pointer to build operation descriptor

  • pProperties – [in,out] query result for builder properties

Returns:

zeRTASBuilderBuildExt#

Added in version 1.13

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderBuildExt(ze_rtas_builder_ext_handle_t hBuilder, const ze_rtas_builder_build_op_ext_desc_t *pBuildOpDescriptor, void *pScratchBuffer, size_t scratchBufferSizeBytes, void *pRtasBuffer, size_t rtasBufferSizeBytes, ze_rtas_parallel_operation_ext_handle_t hParallelOperation, void *pBuildUserPtr, ze_rtas_aabb_ext_t *pBounds, size_t *pRtasBufferSizeBytes)#

Build ray tracing acceleration structure.

  • This function builds an acceleration structure of the scene consisting of the specified geometry information and writes the acceleration structure to the provided destination buffer. All types of geometries can get freely mixed inside a scene.

  • Before an acceleration structure can be built, the user must allocate the memory for the acceleration structure buffer and scratch buffer using sizes queried with the zeRTASBuilderGetBuildPropertiesExt function.

  • When using the “worst-case” size for the acceleration structure buffer, the acceleration structure construction will never fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY.

  • When using the “expected” size for the acceleration structure buffer, the acceleration structure construction may fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY. If this happens, the user may resize their acceleration structure buffer using the returned *pRtasBufferSizeBytes value, which will be updated with an improved size estimate that will likely result in a successful build.

  • The acceleration structure construction is run on the host and is synchronous, thus after the function returns with a successful result, the acceleration structure may be used.

  • All provided data buffers must be host-accessible. The referenced scene data (index- and vertex- buffers) have to be accessible from the host, and will not be referenced by the build acceleration structure.

  • The acceleration structure buffer is typically a host allocation that is later manually copied to a device allocation. Alternatively one can also use a shared USM allocation as acceleration structure buffer and skip the copy.

  • A successfully constructed acceleration structure is entirely self-contained. There is no requirement for input data to persist beyond build completion.

  • A successfully constructed acceleration structure is non-copyable.

  • Acceleration structure construction may be parallelized by passing a valid handle to a parallel operation object and joining that parallel operation using zeRTASParallelOperationJoinExt with user-provided worker threads.

  • A successfully constructed acceleration structure is generally non-copyable. It can only get copied from host to device using the special zeRTASBuilderCommandListAppendCopyExt function.

  • Additional Notes

    • ”The geometry infos array, geometry infos, and scratch buffer must

      all be standard host memory allocations.”

    • ”A pointer to a geometry info can be a null pointer, in which case

      the geometry is treated as empty.”

    • ”If no parallel operation handle is provided, the build is run

      sequentially on the current thread.”

    • ”A parallel operation object may only be associated with a single

      acceleration structure build at a time.”

Parameters:

  • hBuilder – [in] handle of builder object

  • pBuildOpDescriptor – [in] pointer to build operation descriptor

  • pScratchBuffer – [in][range(0, scratchBufferSizeBytes)] scratch buffer to be used during acceleration structure construction

  • scratchBufferSizeBytes – [in] size of scratch buffer, in bytes

  • pRtasBuffer – [in] pointer to destination buffer

  • rtasBufferSizeBytes – [in] destination buffer size, in bytes

  • hParallelOperation – [in][optional] handle to parallel operation object

  • pBuildUserPtr – [in][optional] pointer passed to callbacks

  • pBounds – [in,out][optional] pointer to destination address for acceleration structure bounds

  • pRtasBufferSizeBytes – [out][optional] updated acceleration structure size requirement, in bytes

Returns:

zeRTASBuilderCommandListAppendCopyExt#

Added in version 1.13

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderCommandListAppendCopyExt(ze_command_list_handle_t hCommandList, void *dstptr, const void *srcptr, size_t size, ze_event_handle_t hSignalEvent, uint32_t numWaitEvents, ze_event_handle_t *phWaitEvents)#

Copies a ray tracing acceleration structure (RTAS) from host to device memory.

  • The memory pointed to by srcptr must be host memory containing a valid ray tracing acceleration structure.

  • The number of bytes to copy must be larger or equal to the size of the ray tracing acceleration structure.

  • The application must ensure the memory pointed to by dstptr and srcptr is accessible by the device on which the command list was created.

  • The implementation must not access the memory pointed to by dstptr and srcptr as they are free to be modified by either the Host or device up until execution.

  • The application must ensure the events are accessible by the device on which the command list was created.

  • The application must ensure the command list and events were created, and the memory was allocated, on the same context.

  • The application must not call this function from simultaneous threads with the same command list handle.

  • The implementation of this function should be lock-free.

Parameters:

  • hCommandList – [in] handle of command list

  • dstptr – [in] pointer to destination in device memory to copy the ray tracing acceleration structure to

  • srcptr – [in] pointer to a valid source ray tracing acceleration structure in host memory to copy from

  • size – [in] size in bytes to copy

  • hSignalEvent – [in][optional] handle of the event to signal on completion

  • numWaitEvents – [in][optional] number of events to wait on before launching; must be 0 if nullptr == phWaitEvents

  • phWaitEvents – [in][optional][range(0, numWaitEvents)] handle of the events to wait on before launching

Returns:

zeRTASBuilderDestroyExt#

Added in version 1.13

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderDestroyExt(ze_rtas_builder_ext_handle_t hBuilder)#

Destroys a ray tracing acceleration structure builder object.

  • The implementation of this function may immediately release any internal Host and Device resources associated with this builder.

  • The application must not call this function from simultaneous threads with the same builder handle.

  • The implementation of this function must be thread-safe.

Parameters:

hBuilder – [in][release] handle of builder object to destroy

Returns:

RTAS Builder - Extension Enums#

ze_rtas_builder_ext_flags_t#

Added in version 1.13

enum ze_rtas_builder_ext_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_EXT_FLAG_RESERVED#

Reserved for future use.

enumerator ZE_RTAS_BUILDER_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_EXT_FLAG_* ENUMs.

ze_rtas_builder_geometry_ext_flags_t#

Added in version 1.13

enum ze_rtas_builder_geometry_ext_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXT_FLAG_NON_OPAQUE#

non-opaque geometries invoke an any-hit shader

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_GEOMETRY_EXT_FLAG_* ENUMs.

ze_rtas_builder_instance_ext_flags_t#

Added in version 1.13

enum ze_rtas_builder_instance_ext_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_TRIANGLE_CULL_DISABLE#

disables culling of front-facing and back-facing triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_TRIANGLE_FRONT_COUNTERCLOCKWISE#

reverses front and back face of triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_TRIANGLE_FORCE_OPAQUE#

forces instanced geometry to be opaque, unless ray flag forces it to be non-opaque

enumerator ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_TRIANGLE_FORCE_NON_OPAQUE#

forces instanced geometry to be non-opaque, unless ray flag forces it to be opaque

enumerator ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_INSTANCE_EXT_FLAG_* ENUMs.

ze_rtas_builder_build_op_ext_flags_t#

Added in version 1.13

enum ze_rtas_builder_build_op_ext_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXT_FLAG_COMPACT#

build more compact acceleration structure

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXT_FLAG_NO_DUPLICATE_ANYHIT_INVOCATION#

guarantees single any-hit shader invocation per primitive

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXT_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_BUILD_OP_EXT_FLAG_* ENUMs.

ze_rtas_builder_build_quality_hint_ext_t#

Added in version 1.13

enum ze_rtas_builder_build_quality_hint_ext_t#

Ray tracing acceleration structure builder build quality hint.

  • Depending on use case different quality modes for acceleration structure build are supported.

  • A low-quality build builds an acceleration structure fast, but at the cost of some reduction in ray tracing performance. This mode is recommended for dynamic content, such as animated characters.

  • A medium-quality build uses a compromise between build quality and ray tracing performance. This mode should be used by default.

  • Higher ray tracing performance can be achieved by using a high-quality build, but acceleration structure build performance might be significantly reduced.

Values:

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_LOW#

build low-quality acceleration structure (fast)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_MEDIUM#

build medium-quality acceleration structure (slower)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_HIGH#

build high-quality acceleration structure (slow)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXT_* ENUMs.

ze_rtas_builder_geometry_type_ext_t#

Added in version 1.13

enum ze_rtas_builder_geometry_type_ext_t#

Ray tracing acceleration structure builder geometry type.

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_TRIANGLES#

triangle mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_QUADS#

quad mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_PROCEDURAL#

procedural geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_INSTANCE#

instance geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_* ENUMs.

ze_rtas_builder_input_data_format_ext_t#

Added in version 1.13

enum ze_rtas_builder_input_data_format_ext_t#

Ray tracing acceleration structure data buffer element format.

  • Specifies the format of data buffer elements.

  • Data buffers may contain instancing transform matrices, triangle/quad vertex indices, etc…

Values:

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3#

3-component float vector (see ze_rtas_float3_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3X4_COLUMN_MAJOR#

3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_column_major_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3X4_ALIGNED_COLUMN_MAJOR#

3x4 affine transformation in column-major format (see ze_rtas_transform_float3x4_aligned_column_major_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3X4_ROW_MAJOR#

3x4 affine transformation in row-major format (see ze_rtas_transform_float3x4_row_major_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_AABB#

3-dimensional axis-aligned bounding-box (see ze_rtas_aabb_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_TRIANGLE_INDICES_UINT32#

Unsigned 32-bit triangle indices (see ze_rtas_triangle_indices_uint32_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_QUAD_INDICES_UINT32#

Unsigned 32-bit quad indices (see ze_rtas_quad_indices_uint32_ext_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_* ENUMs.

RTAS Builder - Extension Structures#

ze_rtas_builder_ext_desc_t#

Added in version 1.13

struct ze_rtas_builder_ext_desc_t#

Ray tracing acceleration structure builder descriptor.

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_builder_ext_version_t builderVersion#

[in] ray tracing acceleration structure builder version

ze_rtas_builder_ext_properties_t#

Added in version 1.13

struct ze_rtas_builder_ext_properties_t#

Ray tracing acceleration structure builder properties.

Public Members

ze_structure_type_t stype#

[in] type of this structure

void *pNext#

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_builder_ext_flags_t flags#

[out] ray tracing acceleration structure builder flags

size_t rtasBufferSizeBytesExpected#

[out] expected size (in bytes) required for acceleration structure buffer

  • When using an acceleration structure buffer of this size, the build is expected to succeed; however, it is possible that the build may fail with ZE_RESULT_EXT_RTAS_BUILD_RETRY

size_t rtasBufferSizeBytesMaxRequired#

[out] worst-case size (in bytes) required for acceleration structure buffer

  • When using an acceleration structure buffer of this size, the build is guaranteed to not run out of memory.

size_t scratchBufferSizeBytes#

[out] scratch buffer size (in bytes) required for acceleration structure build.

ze_rtas_builder_geometry_info_ext_t#

Added in version 1.13

struct ze_rtas_builder_geometry_info_ext_t#

Ray tracing acceleration structure builder geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_ext_t geometryType#

[in] geometry type

ze_rtas_builder_triangles_geometry_info_ext_t#

Added in version 1.13

struct ze_rtas_builder_triangles_geometry_info_ext_t#

Ray tracing acceleration structure builder triangle mesh geometry info.

  • The linear barycentric u/v parametrization of the triangle is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1, and

    • (u=0, v=1) at v2

Public Members

ze_rtas_builder_packed_geometry_type_ext_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_TRIANGLES

ze_rtas_builder_packed_geometry_ext_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_ext_t triangleFormat#

[in] format of triangle buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_TRIANGLE_INDICES_UINT32

ze_rtas_builder_packed_input_data_format_ext_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3

uint32_t triangleCount#

[in] number of triangles in triangle buffer

uint32_t vertexCount#

[in] number of vertices in vertex buffer

uint32_t triangleStride#

[in] stride (in bytes) of triangles in triangle buffer

uint32_t vertexStride#

[in] stride (in bytes) of vertices in vertex buffer

void *pTriangleBuffer#

[in] pointer to array of triangle indices in specified format

void *pVertexBuffer#

[in] pointer to array of triangle vertices in specified format

ze_rtas_builder_quads_geometry_info_ext_t#

Added in version 1.13

struct ze_rtas_builder_quads_geometry_info_ext_t#

Ray tracing acceleration structure builder quad mesh geometry info.

  • A quad is a triangle pair represented using 4 vertex indices v0, v1, v2, v3. The first triangle is made out of indices v0, v1, v3 and the second triangle from indices v2, v3, v1. The piecewise linear barycentric u/v parametrization of the quad is defined as:

    • (u=0, v=0) at v0,

    • (u=1, v=0) at v1,

    • (u=0, v=1) at v3, and

    • (u=1, v=1) at v2 This is achieved by correcting the u’/v’ coordinates of the second triangle by u = 1-u’ and v = 1-v’, yielding a piecewise linear parametrization.

Public Members

ze_rtas_builder_packed_geometry_type_ext_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_QUADS

ze_rtas_builder_packed_geometry_ext_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_ext_t quadFormat#

[in] format of quad buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_QUAD_INDICES_UINT32

ze_rtas_builder_packed_input_data_format_ext_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXT_FLOAT3

uint32_t quadCount#

[in] number of quads in quad buffer

uint32_t vertexCount#

[in] number of vertices in vertex buffer

uint32_t quadStride#

[in] stride (in bytes) of quads in quad buffer

uint32_t vertexStride#

[in] stride (in bytes) of vertices in vertex buffer

void *pQuadBuffer#

[in] pointer to array of quad indices in specified format

void *pVertexBuffer#

[in] pointer to array of quad vertices in specified format

ze_rtas_builder_procedural_geometry_info_ext_t#

Added in version 1.13

struct ze_rtas_builder_procedural_geometry_info_ext_t#

Ray tracing acceleration structure builder procedural primitives geometry info.

  • A host-side bounds callback function is invoked by the acceleration structure builder to query the bounds of procedural primitives on demand. The callback is passed some pGeomUserPtr that can point to an application-side representation of the procedural primitives. Further, a second pBuildUserPtr, which is set by a parameter to zeRTASBuilderBuildExt, is passed to the callback. This allows the build to change the bounds of the procedural geometry, for example, to build a BVH only over a short time range to implement multi-segment motion blur.

Public Members

ze_rtas_builder_packed_geometry_type_ext_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_PROCEDURAL

ze_rtas_builder_packed_geometry_ext_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

uint8_t reserved#

[in] reserved for future use

uint32_t primCount#

[in] number of primitives in geometry

ze_rtas_geometry_aabbs_cb_ext_t pfnGetBoundsCb#

[in] pointer to callback function to get the axis-aligned bounding-box for a range of primitives

void *pGeomUserPtr#

[in] user data pointer passed to callback

ze_rtas_builder_instance_geometry_info_ext_t#

Added in version 1.13

struct ze_rtas_builder_instance_geometry_info_ext_t#

Ray tracing acceleration structure builder instance geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_ext_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXT_INSTANCE

ze_rtas_builder_packed_instance_ext_flags_t instanceFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_ext_flag_t bits representing the geometry flags for all primitives of this geometry

uint8_t geometryMask#

[in] 8-bit geometry mask for ray masking

ze_rtas_builder_packed_input_data_format_ext_t transformFormat#

[in] format of the specified transformation

uint32_t instanceUserID#

[in] user-specified identifier for the instance

void *pTransform#

[in] object-to-world instance transformation in specified format

ze_rtas_aabb_ext_t *pBounds#

[in] object-space axis-aligned bounding-box of the instanced acceleration structure

void *pAccelerationStructure#

[in] device pointer to acceleration structure to instantiate

ze_rtas_builder_build_op_ext_desc_t#

Added in version 1.13

struct ze_rtas_builder_build_op_ext_desc_t#

Public Members

ze_structure_type_t stype#

[in] type of this structure

const void *pNext#

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

ze_rtas_format_ext_t rtasFormat#

[in] ray tracing acceleration structure format

ze_rtas_builder_build_quality_hint_ext_t buildQuality#

[in] acceleration structure build quality hint

ze_rtas_builder_build_op_ext_flags_t buildFlags#

[in] 0 or some combination of ze_rtas_builder_build_op_ext_flag_t flags

const ze_rtas_builder_geometry_info_ext_t **ppGeometries#

[in][optional][range(0, numGeometries)] NULL or a valid array of pointers to geometry infos

uint32_t numGeometries#

[in] number of geometries in geometry infos array, can be zero when ppGeometries is NULL