NVIDIA OptiX 6.0 API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Acceleration functions

Functions

RTresult RTAPI rtAccelerationCreate (RTcontext context, RTacceleration *acceleration)
 
RTresult RTAPI rtAccelerationDestroy (RTacceleration acceleration)
 
RTresult RTAPI rtAccelerationValidate (RTacceleration acceleration)
 
RTresult RTAPI rtAccelerationGetContext (RTacceleration acceleration, RTcontext *context)
 
RTresult RTAPI rtAccelerationSetBuilder (RTacceleration acceleration, const char *builder)
 
RTresult RTAPI rtAccelerationGetBuilder (RTacceleration acceleration, const char **stringReturn)
 
RTresult RTAPI rtAccelerationSetProperty (RTacceleration acceleration, const char *name, const char *value)
 
RTresult RTAPI rtAccelerationGetProperty (RTacceleration acceleration, const char *name, const char **stringReturn)
 
RTresult RTAPI rtAccelerationMarkDirty (RTacceleration acceleration)
 
RTresult RTAPI rtAccelerationIsDirty (RTacceleration acceleration, int *dirty)
 

Detailed Description

Functions related to an OptiX Acceleration Structure node.

Function Documentation

RTresult RTAPI rtAccelerationCreate ( RTcontext  context,
RTacceleration acceleration 
)

Creates a new acceleration structure.

Description

rtAccelerationCreate creates a new ray tracing acceleration structure within a context. An acceleration structure is used by attaching it to a group or geometry group by calling rtGroupSetAcceleration or rtGeometryGroupSetAcceleration. Note that an acceleration structure can be shared by attaching it to multiple groups or geometry groups if the underlying geometric structures are the same, see rtGroupSetAcceleration and rtGeometryGroupSetAcceleration for more details. A newly created acceleration structure is initially in dirty state. Sets *acceleration to the handle of a newly created acceleration structure within context. Returns RT_ERROR_INVALID_VALUE if acceleration is NULL.

Parameters
[in]contextSpecifies a context within which to create a new acceleration structure
[out]accelerationReturns the newly created acceleration structure

Return values

Relevant return values:

History

rtAccelerationCreate was introduced in OptiX 1.0.

See also rtAccelerationDestroy, rtContextCreate, rtAccelerationMarkDirty, rtAccelerationIsDirty, rtGroupSetAcceleration, rtGeometryGroupSetAcceleration

RTresult RTAPI rtAccelerationDestroy ( RTacceleration  acceleration)

Destroys an acceleration structure object.

Description

rtAccelerationDestroy removes acceleration from its context and deletes it. acceleration should be a value returned by rtAccelerationCreate. After the call, acceleration is no longer a valid handle.

Parameters
[in]accelerationHandle of the acceleration structure to destroy

Return values

Relevant return values:

History

rtAccelerationDestroy was introduced in OptiX 1.0.

See also rtAccelerationCreate

RTresult RTAPI rtAccelerationGetBuilder ( RTacceleration  acceleration,
const char **  stringReturn 
)

Query the current builder from an acceleration structure.

Description

rtAccelerationGetBuilder returns the name of the builder currently used in the acceleration structure acceleration. If no builder has been set for acceleration, an empty string is returned. stringReturn will be set to point to the returned string. The memory stringReturn points to will be valid until the next API call that returns a string.

Parameters
[in]accelerationThe acceleration structure handle
[out]stringReturnReturn string buffer

Return values

Relevant return values:

History

rtAccelerationGetBuilder was introduced in OptiX 1.0.

See also rtAccelerationSetBuilder

RTresult RTAPI rtAccelerationGetContext ( RTacceleration  acceleration,
RTcontext context 
)

Returns the context associated with an acceleration structure.

Description

rtAccelerationGetContext queries an acceleration structure for its associated context. The context handle is returned in *context.

Parameters
[in]accelerationThe acceleration structure handle
[out]contextReturns the context associated with the acceleration structure

Return values

Relevant return values:

History

rtAccelerationGetContext was introduced in OptiX 1.0.

See also rtAccelerationCreate

RTresult RTAPI rtAccelerationGetProperty ( RTacceleration  acceleration,
const char *  name,
const char **  stringReturn 
)

Queries an acceleration structure property.

Description

rtAccelerationGetProperty returns the value of the acceleration structure property name. See rtAccelerationSetProperty for a list of supported properties. If the property name is not found, an empty string is returned. stringReturn will be set to point to the returned string. The memory stringReturn points to will be valid until the next API call that returns a string.

Parameters
[in]accelerationThe acceleration structure handle
[in]nameThe name of the property to be queried
[out]stringReturnReturn string buffer

Return values

Relevant return values:

History

rtAccelerationGetProperty was introduced in OptiX 1.0.

See also rtAccelerationSetProperty, rtAccelerationSetBuilder,

RTresult RTAPI rtAccelerationIsDirty ( RTacceleration  acceleration,
int *  dirty 
)

Returns the dirty flag of an acceleration structure.

Description

rtAccelerationIsDirty returns whether the acceleration structure is currently marked dirty. If the flag is set, a nonzero value will be returned in *dirty. Otherwise, zero is returned.

Any acceleration structure which is marked dirty will be rebuilt on a call to one of the rtContextLaunch functions, and its dirty flag will be reset.

An acceleration structure which is not marked dirty will never be rebuilt, even if associated groups, geometry, properties, or any other values have changed.

Initially after creation, acceleration structures are marked dirty.

Parameters
[in]accelerationThe acceleration structure handle
[out]dirtyReturned dirty flag

Return values

Relevant return values:

History

rtAccelerationIsDirty was introduced in OptiX 1.0.

See also rtAccelerationMarkDirty, rtContextLaunch functions

RTresult RTAPI rtAccelerationMarkDirty ( RTacceleration  acceleration)

Marks an acceleration structure as dirty.

Description

rtAccelerationMarkDirty sets the dirty flag for acceleration.

Any acceleration structure which is marked dirty will be rebuilt on a call to one of the rtContextLaunch functions, and its dirty flag will be reset.

An acceleration structure which is not marked dirty will never be rebuilt, even if associated groups, geometry, properties, or any other values have changed.

Initially after creation, acceleration structures are marked dirty.

Parameters
[in]accelerationThe acceleration structure handle

Return values

Relevant return values:

History

rtAccelerationMarkDirty was introduced in OptiX 1.0.

See also rtAccelerationIsDirty, rtContextLaunch functions

RTresult RTAPI rtAccelerationSetBuilder ( RTacceleration  acceleration,
const char *  builder 
)

Specifies the builder to be used for an acceleration structure.

Description

rtAccelerationSetBuilder specifies the method used to construct the ray tracing acceleration structure represented by acceleration. A builder must be set for the acceleration structure to pass validation. The current builder can be changed at any time, including after a call to rtContextLaunch. In this case, data previously computed for the acceleration structure is invalidated and the acceleration will be marked dirty.

builder can take one of the following values:

  • "NoAccel": Specifies that no acceleration structure is explicitly built. Traversal linearly loops through the list of primitives to intersect. This can be useful e.g. for higher level groups with only few children, where managing a more complex structure introduces unnecessary overhead.
  • "Bvh": A standard bounding volume hierarchy, useful for most types of graph levels and geometry. Medium build speed, good ray tracing performance.
  • "Sbvh": A high quality BVH variant for maximum ray tracing performance. Slower build speed and slightly higher memory footprint than "Bvh".
  • "Trbvh": High quality similar to Sbvh but with fast build performance. The Trbvh builder uses about 2.5 times the size of the final BVH for scratch space. A CPU-based Trbvh builder that does not have the memory constraints is available. OptiX includes an optional automatic fallback to the CPU version when out of GPU memory. Please refer to the Programming Guide for more details. Supports motion blur.
  • "MedianBvh": Deprecated in OptiX 4.0. This builder is now internally remapped to Trbvh.
  • "Lbvh": Deprecated in OptiX 4.0. This builder is now internally remapped to Trbvh.
  • "TriangleKdTree": Deprecated in OptiX 4.0. This builder is now internally remapped to Trbvh.
Parameters
[in]accelerationThe acceleration structure handle
[in]builderString value specifying the builder type

Return values

Relevant return values:

History

rtAccelerationSetBuilder was introduced in OptiX 1.0.

See also rtAccelerationGetBuilder, rtAccelerationSetProperty

RTresult RTAPI rtAccelerationSetProperty ( RTacceleration  acceleration,
const char *  name,
const char *  value 
)

Sets an acceleration structure property.

Description

rtAccelerationSetProperty sets a named property value for an acceleration structure. Properties can be used to fine tune the way an acceleration structure is built, in order to achieve faster build times or better ray tracing performance. Properties are evaluated and applied by the acceleration structure during build time, and different builders recognize different properties. Setting a property will never fail as long as acceleration is a valid handle. Properties that are not recognized by an acceleration structure will be ignored.

The following is a list of the properties used by the individual builders:

  • "refit": Available in: Trbvh, Bvh If set to "1", the builder will only readjust the node bounds of the bounding volume hierarchy instead of constructing it from scratch. Refit is only effective if there is an initial BVH already in place, and the underlying geometry has undergone relatively modest deformation. In this case, the builder delivers a very fast BVH update without sacrificing too much ray tracing performance. The default is "0".
  • "vertex_buffer_name": Available in: Trbvh, Sbvh The name of the buffer variable holding triangle vertex data. Each vertex consists of 3 floats. The default is "vertex_buffer".
  • "vertex_buffer_stride": Available in: Trbvh, Sbvh The offset between two vertices in the vertex buffer, given in bytes. The default value is "0", which assumes the vertices are tightly packed.
  • "index_buffer_name": Available in: Trbvh, Sbvh The name of the buffer variable holding vertex index data. The entries in this buffer are indices of type int, where each index refers to one entry in the vertex buffer. A sequence of three indices represents one triangle. If no index buffer is given, the vertices in the vertex buffer are assumed to be a list of triangles, i.e. every 3 vertices in a row form a triangle. The default is "index_buffer".
  • "index_buffer_stride": Available in: Trbvh, Sbvh The offset between two indices in the index buffer, given in bytes. The default value is "0", which assumes the indices are tightly packed.
  • "chunk_size": Available in: Trbvh Number of bytes to be used for a partitioned acceleration structure build. If no chunk size is set, or set to "0", the chunk size is chosen automatically. If set to "-1", the chunk size is unlimited. The minimum chunk size is 64MB. Please note that specifying a small chunk size reduces the peak-memory footprint of the Trbvh but can result in slower rendering performance.
  • " motion_steps" Available in: Trbvh Number of motion steps to build into an acceleration structure that contains motion geometry or motion transforms. Ignored for acceleration structures built over static nodes. Gives a tradeoff between device memory and time: if the input geometry or transforms have many motion steps, then increasing the motion steps in the acceleration structure may result in faster traversal, at the cost of linear increase in memory usage. Default 2, and clamped >=1.
Parameters
[in]accelerationThe acceleration structure handle
[in]nameString value specifying the name of the property
[in]valueString value specifying the value of the property

Return values

Relevant return values:

History

rtAccelerationSetProperty was introduced in OptiX 1.0.

See also rtAccelerationGetProperty, rtAccelerationSetBuilder,

RTresult RTAPI rtAccelerationValidate ( RTacceleration  acceleration)

Validates the state of an acceleration structure.

Description

rtAccelerationValidate checks acceleration for completeness. If acceleration is not valid, returns RT_ERROR_INVALID_VALUE.

Parameters
[in]accelerationThe acceleration structure handle

Return values

Relevant return values:

History

rtAccelerationValidate was introduced in OptiX 1.0.

See also rtAccelerationCreate