OptiX
3.9
NVIDIA OptiX Acceleration Engine
|
Simple API for performing raytracing queries using OptiX or the CPU.
Go to the source code of this file.
Classes | |
struct | RTUtraversalresult |
Typedefs | |
typedef struct RTUtraversal_api * | RTUtraversal |
Enumerations | |
enum | RTUquerytype { RTU_QUERY_TYPE_ANY_HIT = 0, RTU_QUERY_TYPE_CLOSEST_HIT, RTU_QUERY_TYPE_COUNT } |
enum | RTUrayformat { RTU_RAYFORMAT_ORIGIN_DIRECTION_TMIN_TMAX_INTERLEAVED = 0, RTU_RAYFORMAT_ORIGIN_DIRECTION_INTERLEAVED, RTU_RAYFORMAT_COUNT } |
enum | RTUtriformat { RTU_TRIFORMAT_MESH = 0, RTU_TRIFORMAT_TRIANGLE_SOUP, RTU_TRIFORMAT_COUNT } |
enum | RTUinitoptions { RTU_INITOPTION_NONE = 0, RTU_INITOPTION_GPU_ONLY = 1 << 0, RTU_INITOPTION_CPU_ONLY = 1 << 1, RTU_INITOPTION_CULL_BACKFACE = 1 << 2 } |
enum | RTUoutput { RTU_OUTPUT_NONE = 0, RTU_OUTPUT_NORMAL = 1 << 0, RTU_OUTPUT_BARYCENTRIC = 1 << 1, RTU_OUTPUT_BACKFACING = 1 << 2 } |
enum | RTUoption { RTU_OPTION_INT_NUM_THREADS =0 } |
typedef struct RTUtraversal_api* RTUtraversal |
Opaque type. Note that the *_api types should never be used directly. Only the typedef target names will be guaranteed to remain unchanged.
enum RTUinitoptions |
Initialization options (static across life of traversal object).
The rtuTraverse API supports both running on the CPU and GPU. When RTU_INITOPTION_NONE is specified GPU context creation is attempted. If that fails (such as when there isn't an NVIDIA GPU part present, the CPU code path is automatically chosen. Specifying RTU_INITOPTION_GPU_ONLY or RTU_INITOPTION_CPU_ONLY will only use the GPU or CPU modes without automatic transitions from one to the other.
RTU_INITOPTION_CULL_BACKFACE will enable back face culling during intersection.
Enumerator | |
---|---|
RTU_INITOPTION_NONE |
No option |
RTU_INITOPTION_GPU_ONLY |
GPU only |
RTU_INITOPTION_CPU_ONLY |
CPU only |
RTU_INITOPTION_CULL_BACKFACE |
Back face culling |
enum RTUoption |
enum RTUoutput |
enum RTUquerytype |
The type of ray query to be performed.
See OptiX Programming Guide for explanation of any vs. closest hit queries. Note that in the case of RTU_QUERY_TYPE_ANY_HIT, the prim_id and t intersection values in RTUtraversalresult will correspond to the first successful intersection. These values may not be indicative of the closest intersection, only that there was at least one.
Enumerator | |
---|---|
RTU_QUERY_TYPE_ANY_HIT |
Perform any hit calculation |
RTU_QUERY_TYPE_CLOSEST_HIT |
Perform closest hit calculation |
RTU_QUERY_TYPE_COUNT |
Query type count |
enum RTUrayformat |
The input format of the ray vector.
Enumerator | |
---|---|
RTU_RAYFORMAT_ORIGIN_DIRECTION_TMIN_TMAX_INTERLEAVED |
Origin Direction Tmin Tmax interleaved |
RTU_RAYFORMAT_ORIGIN_DIRECTION_INTERLEAVED |
Origin Direction interleaved |
RTU_RAYFORMAT_COUNT |
Ray format count |
enum RTUtriformat |
The input format of the triangles.
TRIANGLE_SOUP implies future use of rtuTraversalSetTriangles while MESH implies use of rtuTraversalSetMesh.
Enumerator | |
---|---|
RTU_TRIFORMAT_MESH |
Triangle format mesh |
RTU_TRIFORMAT_TRIANGLE_SOUP |
Triangle 'soup' format |
RTU_TRIFORMAT_COUNT |
Triangle format count |
RTresult RTAPI rtuTraversalCreate | ( | RTUtraversal * | traversal, |
RTUquerytype | query_type, | ||
RTUrayformat | ray_format, | ||
RTUtriformat | tri_format, | ||
unsigned int | outputs, | ||
unsigned int | options, | ||
RTcontext | context | ||
) |
Create a traversal state and associate a context with it. If context is a null pointer a new context will be created internally. The context should also not be used for any other launch commands from the OptiX host API, nor attached to multiple RTUtraversal objects at one time.
RTresult RTAPI rtuTraversalDestroy | ( | RTUtraversal | traversal | ) |
Clean up any internal memory associated with rtuTraversal* operations. Includes destruction of result buffers returned via rtuTraversalGetErrorString. Invalidates traversal object.
traversal | Traversal state handle |
RTresult RTAPI rtuTraversalGetAccelData | ( | RTUtraversal | traversal, |
void * | data | ||
) |
Retrieve acceleration data for current geometry. Will force acceleration build if necessary. The data parameter should be preallocated and its length should match return value of rtuTraversalGetAccelDataSize.
traversal | Traversal state handle | |
[out] | data | Acceleration data |
RTresult RTAPI rtuTraversalGetAccelDataSize | ( | RTUtraversal | traversal, |
RTsize * | data_size | ||
) |
Retrieve acceleration data size for current geometry. Will force acceleration build if necessary.
traversal | Traversal state handle | |
[out] | data_size | Size of acceleration data |
RTresult RTAPI rtuTraversalGetErrorString | ( | RTUtraversal | traversal, |
RTresult | code, | ||
const char ** | return_string | ||
) |
Returns the string associated with the error code and any additional information from the last error. If traversal is non-NULL return_string only remains valid while traversal is live.
For a list of associated error codes that this function might inspect take a look at RTresult .
[out] | return_string | Pointer to string with error message in it |
traversal | Traversal state handle. Can be NULL | |
code | Error code from last error |
RTresult RTAPI rtuTraversalMapOutput | ( | RTUtraversal | traversal, |
RTUoutput | which, | ||
void ** | output | ||
) |
Retrieve user-specified output from last rtuTraversalTraverse call. Output can be copied from the pointer returned by rtuTraversalMapOutput and will have length 'num_rays' from as prescribed from the previous call to rtuTraversalMapRays. For each RTUoutput, a single rtuTraversalMapOutput pointers can be outstanding. rtuTraversalUnmapOutput should be called when finished reading the output.
If requested output type was not turned on with a previous call to rtuTraversalCreate an error will be returned. See RTUoutput enum for description of output data formats for various outputs.
traversal | Traversal state handle | |
which | Output type to be specified | |
[out] | output | Pointer to output from last traverse |
RTresult RTAPI rtuTraversalMapRays | ( | RTUtraversal | traversal, |
unsigned int | num_rays, | ||
float ** | rays | ||
) |
Specify set of rays to be cast upon next call to rtuTraversalTraverse. rtuTraversalMapRays obtains a pointer which can be used to copy the ray data into. Rays should be packed in the format described in rtuTraversalCreate call. When copying is completed rtuTraversalUnmapRays should be called. Note that this call invalidates any existing results buffers until rtuTraversalTraverse is called again.
traversal | Traversal state handle |
num_rays | Number of rays to be traced |
rays | Pointer to ray data |
RTresult RTAPI rtuTraversalMapResults | ( | RTUtraversal | traversal, |
RTUtraversalresult ** | results | ||
) |
Retrieve results of last rtuTraversal call. Results can be copied from the pointer returned by rtuTraversalMapResults and will have length 'num_rays' as prescribed from the previous call to rtuTraversalMapRays. rtuTraversalUnmapResults should be called when finished reading the results. Returned primitive ID of -1 indicates a ray miss.
traversal | Traversal state handle | |
[out] | results | Pointer to results of last traverse |
RTresult RTAPI rtuTraversalPreprocess | ( | RTUtraversal | traversal | ) |
Perform any necessary preprocessing (eg, acceleration structure building, optix context compilation). It is not necessary to call this function as rtuTraversalTraverse will call this internally as necessary.
traversal | Traversal state handle |
RTresult RTAPI rtuTraversalSetAccelData | ( | RTUtraversal | traversal, |
const void * | data, | ||
RTsize | data_size | ||
) |
Specify acceleration data for current geometry. Input acceleration data should be result of rtuTraversalGetAccelData or rtAccelerationGetData call.
traversal | Traversal state handle |
data | Acceleration data |
data_size | Size of acceleration data |
RTresult RTAPI rtuTraversalSetMesh | ( | RTUtraversal | traversal, |
unsigned int | num_verts, | ||
const float * | verts, | ||
unsigned int | num_tris, | ||
const unsigned * | indices | ||
) |
Specify triangle mesh to be intersected by the next call to rtuTraversalTraverse. Only one geometry set may be active at a time. Subsequent calls to rtuTraversalSetTriangles or rtuTraversalSetMesh will override any previously specified geometry. No internal copies of the mesh data are made. The user should ensure that the mesh data remains valid until after rtuTraversalTraverse has been called. Counter-clockwise winding is assumed for normal and backfacing computations.
traversal | Traversal state handle |
num_verts | Vertex count |
verts | Vertices [ v1_x, v1_y, v1_z, v2.x, ... ] |
num_tris | Triangle count |
indices | Indices [ tri1_index1, tr1_index2, ... ] |
RTresult RTAPI rtuTraversalSetOption | ( | RTUtraversal | traversal, |
RTUoption | option, | ||
void * | value | ||
) |
Set a runtime option. Unlike initialization options, these options may be set more than once for a given RTUtraversal instance.
traversal | Traversal state handle |
option | The option to be set |
value | Value of the option |
RTresult RTAPI rtuTraversalSetTriangles | ( | RTUtraversal | traversal, |
unsigned int | num_tris, | ||
const float * | tris | ||
) |
Specify triangle soup to be intersected by the next call to rtuTraversalLaunch. Only one geometry set may be active at a time. Subsequent calls to rtuTraversalSetTriangles or rtuTraversalSetMesh will override any previously specified geometry. No internal copies of the triangle data are made. The user should ensure that the triangle data remains valid until after rtuTraversalTraverse has been called. Counter-clockwise winding is assumed for normal and backfacing computations.
traversal | Traversal state handle |
num_tris | Triangle count |
tris | Triangles [ tri1_v1.x, tri1_v1.y, tr1_v1.z, tri1_v2.x, ... ] |
RTresult RTAPI rtuTraversalTraverse | ( | RTUtraversal | traversal | ) |
Perform any necessary preprocessing (eg, acceleration structure building and kernel compilation ) and cast current rays against current geometry.
traversal | Traversal state handle |
RTresult RTAPI rtuTraversalUnmapOutput | ( | RTUtraversal | traversal, |
RTUoutput | which | ||
) |
See rtuTraversalMapOutput .
RTresult RTAPI rtuTraversalUnmapRays | ( | RTUtraversal | traversal | ) |
See rtuTraversalMapRays .
RTresult RTAPI rtuTraversalUnmapResults | ( | RTUtraversal | traversal | ) |
See rtuTraversalMapResults .