RTAS Builder - Experimental

Contents

RTAS Builder - Experimental#

oneAPI Level Zero Specification - Version 1.18.31

RTAS Builder - Experimental Functions#

zeRTASBuilderCreateExp#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderCreateExp(ze_driver_handle_t hDriver, const ze_rtas_builder_exp_desc_t *pDescriptor, ze_rtas_builder_exp_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_BUILDER_EXP_NAME extension.

Parameters:

  • hDriver – [in] handle of driver object

  • pDescriptor – [in] pointer to builder descriptor

  • phBuilder – [out] handle of builder object

Returns:

zeRTASBuilderGetBuildPropertiesExp#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderGetBuildPropertiesExp(ze_rtas_builder_exp_handle_t hBuilder, const ze_rtas_builder_build_op_exp_desc_t *pBuildOpDescriptor, ze_rtas_builder_exp_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:

zeRTASBuilderBuildExp#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderBuildExp(ze_rtas_builder_exp_handle_t hBuilder, const ze_rtas_builder_build_op_exp_desc_t *pBuildOpDescriptor, void *pScratchBuffer, size_t scratchBufferSizeBytes, void *pRtasBuffer, size_t rtasBufferSizeBytes, ze_rtas_parallel_operation_exp_handle_t hParallelOperation, void *pBuildUserPtr, ze_rtas_aabb_exp_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.

  • It is the user’s responsibility to manage the acceleration structure buffer allocation, de-allocation, and potential prefetching to the device memory. The required size of the acceleration structure buffer can be queried with the zeRTASBuilderGetBuildPropertiesExp function. The acceleration structure buffer must be a shared USM allocation and should be present on the host at build time. The referenced scene data (index- and vertex- buffers) can be standard host allocations, and will not be referenced into by the build acceleration structure.

  • Before an acceleration structure can be built, the user must allocate the memory for the acceleration structure buffer and scratch buffer using sizes based on a query for the estimated size properties.

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

  • When using the “expected” size for the acceleration structure buffer, the acceleration structure construction may fail with ZE_RESULT_EXP_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 acceleration structure buffer must be a USM allocation.

  • 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 zeRTASParallelOperationJoinExp with user-provided worker threads.

  • 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:

zeRTASBuilderDestroyExp#

Added in version 1.7

ZE_APIEXPORT ze_result_t ZE_APICALL zeRTASBuilderDestroyExp(ze_rtas_builder_exp_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 - Experimental Enums#

ze_rtas_builder_exp_flags_t#

Added in version 1.7

enum ze_rtas_builder_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_EXP_FLAG_RESERVED#

Reserved for future use.

enumerator ZE_RTAS_BUILDER_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_EXP_FLAG_* ENUMs.

ze_rtas_builder_geometry_exp_flags_t#

Added in version 1.7

enum ze_rtas_builder_geometry_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_NON_OPAQUE#

non-opaque geometries invoke an any-hit shader

enumerator ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_GEOMETRY_EXP_FLAG_* ENUMs.

ze_rtas_builder_instance_exp_flags_t#

Added in version 1.7

enum ze_rtas_builder_instance_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_CULL_DISABLE#

disables culling of front-facing and back-facing triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_FRONT_COUNTERCLOCKWISE#

reverses front and back face of triangles

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_TRIANGLE_FORCE_OPAQUE#

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

enumerator ZE_RTAS_BUILDER_INSTANCE_EXP_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_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_INSTANCE_EXP_FLAG_* ENUMs.

ze_rtas_builder_build_op_exp_flags_t#

Added in version 1.7

enum ze_rtas_builder_build_op_exp_flag_t#

Values:

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_COMPACT#

build more compact acceleration structure

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_NO_DUPLICATE_ANYHIT_INVOCATION#

guarantees single any-hit shader invocation per primitive

enumerator ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_BUILD_OP_EXP_FLAG_* ENUMs.

ze_rtas_builder_build_quality_hint_exp_t#

Added in version 1.7

enum ze_rtas_builder_build_quality_hint_exp_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_EXP_LOW#

build low-quality acceleration structure (fast)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_MEDIUM#

build medium-quality acceleration structure (slower)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_HIGH#

build high-quality acceleration structure (slow)

enumerator ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_BUILD_QUALITY_HINT_EXP_* ENUMs.

ze_rtas_builder_geometry_type_exp_t#

Added in version 1.7

enum ze_rtas_builder_geometry_type_exp_t#

Ray tracing acceleration structure builder geometry type.

Values:

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_TRIANGLES#

triangle mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_QUADS#

quad mesh geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_PROCEDURAL#

procedural geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_INSTANCE#

instance geometry type

enumerator ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_* ENUMs.

ze_rtas_builder_input_data_format_exp_t#

Added in version 1.7

enum ze_rtas_builder_input_data_format_exp_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_EXP_FLOAT3#

3-component float vector (see ze_rtas_float3_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_COLUMN_MAJOR#

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

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_ALIGNED_COLUMN_MAJOR#

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

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FLOAT3X4_ROW_MAJOR#

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

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_AABB#

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

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_TRIANGLE_INDICES_UINT32#

Unsigned 32-bit triangle indices (see ze_rtas_triangle_indices_uint32_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_QUAD_INDICES_UINT32#

Unsigned 32-bit quad indices (see ze_rtas_quad_indices_uint32_exp_t)

enumerator ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_FORCE_UINT32#

Value marking end of ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_* ENUMs.

RTAS Builder - Experimental Structures#

ze_rtas_builder_exp_desc_t#

Added in version 1.7

struct ze_rtas_builder_exp_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_exp_version_t builderVersion#

[in] ray tracing acceleration structure builder version

ze_rtas_builder_exp_properties_t#

Added in version 1.7

struct ze_rtas_builder_exp_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_exp_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_EXP_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_exp_t#

Added in version 1.7

struct ze_rtas_builder_geometry_info_exp_t#

Ray tracing acceleration structure builder geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type

ze_rtas_builder_triangles_geometry_info_exp_t#

Added in version 1.7

struct ze_rtas_builder_triangles_geometry_info_exp_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_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_TRIANGLES

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_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_exp_t triangleFormat#

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

ze_rtas_builder_packed_input_data_format_exp_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_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_exp_t#

Added in version 1.7

struct ze_rtas_builder_quads_geometry_info_exp_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_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_QUADS

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_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_exp_t quadFormat#

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

ze_rtas_builder_packed_input_data_format_exp_t vertexFormat#

[in] format of vertex buffer data, must be ZE_RTAS_BUILDER_INPUT_DATA_FORMAT_EXP_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_exp_t#

Added in version 1.7

struct ze_rtas_builder_procedural_geometry_info_exp_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 zeRTASBuilderBuildExp, 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_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_PROCEDURAL

ze_rtas_builder_packed_geometry_exp_flags_t geometryFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_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_exp_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_exp_t#

Added in version 1.7

struct ze_rtas_builder_instance_geometry_info_exp_t#

Ray tracing acceleration structure builder instance geometry info.

Public Members

ze_rtas_builder_packed_geometry_type_exp_t geometryType#

[in] geometry type, must be ZE_RTAS_BUILDER_GEOMETRY_TYPE_EXP_INSTANCE

ze_rtas_builder_packed_instance_exp_flags_t instanceFlags#

[in] 0 or some combination of ze_rtas_builder_geometry_exp_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_exp_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_exp_t *pBounds#

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

void *pAccelerationStructure#

[in] pointer to acceleration structure to instantiate

ze_rtas_builder_build_op_exp_desc_t#

Added in version 1.7

struct ze_rtas_builder_build_op_exp_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_exp_t rtasFormat#

[in] ray tracing acceleration structure format

ze_rtas_builder_build_quality_hint_exp_t buildQuality#

[in] acceleration structure build quality hint

ze_rtas_builder_build_op_exp_flags_t buildFlags#

[in] 0 or some combination of ze_rtas_builder_build_op_exp_flag_t flags

const ze_rtas_builder_geometry_info_exp_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