Detailed Description

Simple API for performing raytracing queries using OptiX or the CPU.

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 }

Functions
RTresult RTAPI	rtuTraversalCreate (RTUtraversal *traversal, RTUquerytype query_type, RTUrayformat ray_format, RTUtriformat tri_format, unsigned int outputs, unsigned int options, RTcontext context)

RTresult RTAPI	rtuTraversalGetErrorString (RTUtraversal traversal, RTresult code, const char **return_string)

RTresult RTAPI	rtuTraversalSetOption (RTUtraversal traversal, RTUoption option, void *value)

RTresult RTAPI	rtuTraversalSetMesh (RTUtraversal traversal, unsigned int num_verts, const float verts, unsigned int num_tris, const unsigned indices)

RTresult RTAPI	rtuTraversalSetTriangles (RTUtraversal traversal, unsigned int num_tris, const float *tris)

RTresult RTAPI	rtuTraversalSetAccelData (RTUtraversal traversal, const void *data, RTsize data_size)

RTresult RTAPI	rtuTraversalGetAccelDataSize (RTUtraversal traversal, RTsize *data_size)

RTresult RTAPI	rtuTraversalGetAccelData (RTUtraversal traversal, void *data)

RTresult RTAPI	rtuTraversalMapRays (RTUtraversal traversal, unsigned int num_rays, float **rays)

RTresult RTAPI	rtuTraversalUnmapRays (RTUtraversal traversal)

RTresult RTAPI	rtuTraversalPreprocess (RTUtraversal traversal)

RTresult RTAPI	rtuTraversalTraverse (RTUtraversal traversal)

RTresult RTAPI	rtuTraversalMapResults (RTUtraversal traversal, RTUtraversalresult **results)

RTresult RTAPI	rtuTraversalUnmapResults (RTUtraversal traversal)

RTresult RTAPI	rtuTraversalMapOutput (RTUtraversal traversal, RTUoutput which, void **output)

RTresult RTAPI	rtuTraversalUnmapOutput (RTUtraversal traversal, RTUoutput which)

RTresult RTAPI	rtuTraversalDestroy (RTUtraversal traversal)

Typedef Documentation

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.

Enumeration Type Documentation

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

Runtime options (can be set multiple times for a given traversal object).

Enumerator
RTU_OPTION_INT_NUM_THREADS	Number of threads

enum RTUoutput

RTUoutput requested.

Enumerator
RTU_OUTPUT_NONE	Output None
RTU_OUTPUT_NORMAL	float3 [x, y, z]
RTU_OUTPUT_BARYCENTRIC	float2 [alpha, beta] (gamma implicit)
RTU_OUTPUT_BACKFACING	char [1 \| 0]

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

Function Documentation

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.

Parameters

[out]	traversal	Return pointer for traverse state handle
	query_type	Ray query type
	ray_format	Ray format
	tri_format	Triangle format
	outputs	OR'ed mask of requested RTUoutput
	options	Bit vector of or'ed RTUinitoptions
	context	RTcontext used for internal object creation

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.

Parameters

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.

Parameters

	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.

Parameters

	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 .

Parameters

[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.

Parameters

	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.

Parameters

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.

Parameters

	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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters