OptiX  3.9
NVIDIA OptiX Acceleration Engine
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions
optix_prime.h File Reference

Detailed Description

OptiX Prime public API.

Author
NVIDIA Corporation OptiX Prime public API

Go to the source code of this file.

Macros

#define OPTIX_PRIME_VERSION
 
#define RTPAPI   __declspec(dllimport)
 

Typedefs

typedef unsigned int RTPsize
 
typedef struct RTPcontext_api * RTPcontext
 
typedef struct RTPmodel_api * RTPmodel
 
typedef struct RTPquery_api * RTPquery
 
typedef struct RTPbufferdesc_api * RTPbufferdesc
 
typedef struct CUstream_st * cudaStream_t
 

Functions

RTPresult RTPAPI rtpContextCreate (RTPcontexttype type, RTPcontext *context)
 
RTPresult RTPAPI rtpContextSetCudaDeviceNumbers (RTPcontext context, unsigned deviceCount, const unsigned *deviceNumbers)
 
RTPresult RTPAPI rtpContextSetCpuThreads (RTPcontext context, unsigned numThreads)
 
RTPresult RTPAPI rtpContextDestroy (RTPcontext context)
 
RTPresult RTPAPI rtpContextGetLastErrorString (RTPcontext context, const char **return_string)
 
RTPresult RTPAPI rtpBufferDescCreate (RTPcontext context, RTPbufferformat format, RTPbuffertype type, void *buffer, RTPbufferdesc *desc)
 
RTPresult RTPAPI rtpBufferDescGetContext (RTPbufferdesc desc, RTPcontext *context)
 
RTPresult RTPAPI rtpBufferDescSetRange (RTPbufferdesc desc, RTPsize begin, RTPsize end)
 
RTPresult RTPAPI rtpBufferDescSetStride (RTPbufferdesc desc, unsigned strideBytes)
 
RTPresult RTPAPI rtpBufferDescSetCudaDeviceNumber (RTPbufferdesc desc, unsigned deviceNumber)
 
RTPresult RTPAPI rtpBufferDescDestroy (RTPbufferdesc desc)
 
RTPresult RTPAPI rtpModelCreate (RTPcontext context, RTPmodel *model)
 
RTPresult RTPAPI rtpModelGetContext (RTPmodel model, RTPcontext *context)
 
RTPresult RTPAPI rtpModelSetTriangles (RTPmodel model, RTPbufferdesc indices, RTPbufferdesc vertices)
 
RTPresult RTPAPI rtpModelSetInstances (RTPmodel model, RTPbufferdesc instances, RTPbufferdesc transforms)
 
RTPresult RTPAPI rtpModelUpdate (RTPmodel model, unsigned hints)
 
RTPresult RTPAPI rtpModelFinish (RTPmodel model)
 
RTPresult RTPAPI rtpModelGetFinished (RTPmodel model, int *isFinished)
 
RTPresult RTPAPI rtpModelCopy (RTPmodel model, RTPmodel srcModel)
 
RTPresult RTPAPI rtpModelSetBuilderParameter (RTPmodel model_api, RTPbuilderparam param, RTPsize size, const void *ptr)
 
RTPresult RTPAPI rtpModelDestroy (RTPmodel model)
 
RTPresult RTPAPI rtpQueryCreate (RTPmodel model, RTPquerytype queryType, RTPquery *query)
 
RTPresult RTPAPI rtpQueryGetContext (RTPquery query, RTPcontext *context)
 
RTPresult RTPAPI rtpQuerySetRays (RTPquery query, RTPbufferdesc rays)
 
RTPresult RTPAPI rtpQuerySetHits (RTPquery query, RTPbufferdesc hits)
 
RTPresult RTPAPI rtpQueryExecute (RTPquery query, unsigned hints)
 
RTPresult RTPAPI rtpQueryFinish (RTPquery query)
 
RTPresult RTPAPI rtpQueryGetFinished (RTPquery query, int *isFinished)
 
RTPresult RTPAPI rtpQuerySetCudaStream (RTPquery query, cudaStream_t stream)
 
RTPresult RTPAPI rtpQueryDestroy (RTPquery query)
 
RTPresult RTPAPI rtpHostBufferLock (void *buffer, RTPsize size)
 
RTPresult RTPAPI rtpHostBufferUnlock (void *buffer)
 
RTPresult RTPAPI rtpGetErrorString (RTPresult errorCode, const char **errorString)
 
RTPresult RTPAPI rtpGetVersion (unsigned *version)
 
RTPresult RTPAPI rtpGetVersionString (const char **versionString)
 

Macro Definition Documentation

#define OPTIX_PRIME_VERSION
Value:
3090 /* 3.9.0 (major = OPTIX_PRIME_VERSION/1000, *
* minor = (OPTIX_PRIME_VERSION%1000)/10, *
* micro = OPTIX_PRIME_VERSION%10 */

Typedef Documentation

typedef struct RTPbufferdesc_api* RTPbufferdesc

Opaque type. Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged.

typedef struct RTPcontext_api* RTPcontext

Opaque type. Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged.

typedef struct RTPmodel_api* RTPmodel

Opaque type. Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged.

typedef struct RTPquery_api* RTPquery

Opaque type. Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged.

Function Documentation

RTPresult RTPAPI rtpBufferDescCreate ( RTPcontext  context,
RTPbufferformat  format,
RTPbuffertype  type,
void *  buffer,
RTPbufferdesc *  desc 
)

Create a buffer descriptor.

This function creates a buffer descriptor with the specified element format and buffertype. A buffer of type RTP_BUFFER_TYPE_CUDA_LINEAR is assumed to reside on the current device. The device number can be changed by calling rtpBufferDescSetCudaDeviceNumber.

Parameters
[in]contextOptiX Prime context
[in]formatFormat of the buffer
[in]typeType of the buffer
[in]bufferPointer to buffer data
[out]descPointer to the new buffer descriptor

Return values

Relevant return values:

Example Usage:

RTPbufferdesc verticesBD;
rtpBufferDescCreate(context, RTP_BUFFER_FORMAT_VERTEX_FLOAT3, RTP_BUFFER_TYPE_HOST, vertices, &verticesBD);
RTPresult RTPAPI rtpBufferDescDestroy ( RTPbufferdesc  desc)

Destroys a buffer descriptor.

Buffer descriptors can be destroyed immediately after it is used as a function parameter. The buffer contents associated with a buffer descriptor, however, must remain valid until they are no longer used by any OptiX Prime objects.

Parameters
[in]descBuffer descriptor

Return values

Relevant return values:

RTPresult RTPAPI rtpBufferDescGetContext ( RTPbufferdesc  desc,
RTPcontext *  context 
)

Gets the context object associated with the provided buffer descriptor.

Parameters
[in]descBuffer descriptor
[out]contextReturned context

Return values

Relevant return values:

RTPresult RTPAPI rtpBufferDescSetCudaDeviceNumber ( RTPbufferdesc  desc,
unsigned  deviceNumber 
)

Sets the CUDA device number for a buffer.

A buffer of type RTP_BUFFER_TYPE_CUDA_LINEAR is assumed to reside on the device that was current when its buffer descriptor was created unless otherwise specified using this function.

Parameters
[in]descBuffer descriptor
[in]deviceNumberCUDA device number

Return values

Relevant return values:

RTPresult RTPAPI rtpBufferDescSetRange ( RTPbufferdesc  desc,
RTPsize  begin,
RTPsize  end 
)

Sets the element range of a buffer to use.

The range is specified in terms of number of elements. By default, the range for a buffer is 0 to the number of elements in the buffer.

Parameters
[in]descBuffer descriptor
[in]beginStart index of the range
[in]endEnd index of the range (exclusive, one past the index of the last element)

Return values

Relevant return values:

RTPresult RTPAPI rtpBufferDescSetStride ( RTPbufferdesc  desc,
unsigned  strideBytes 
)

Sets the stride for elements in a buffer.

This function is only valid for buffers of format RTP_BUFFER_FORMAT_VERTEX_FLOAT3. This function is useful for vertex buffers that contain interleaved vertex attributes. For buffers that are transferred between the host and a device it is recommended that only buffers with default stride be used to avoid transferring data that will not be used.

Parameters
[in]descBuffer descriptor
[in]strideBytesStride in bytes. The default value of 0 indicates that elements are contiguous in memory.

Return values

Relevant return values:

Example Usage:

struct Vertex {
float3 pos, normal, color;
};
...
RTPbufferdesc vertsBD;
rtpBufferDescCreate(context, RTP_BUFFER_FORMAT_VERTEX_FLOAT3, RTP_BUFFER_TYPE_HOST, verts, &vertsBD);
rtpBufferDescSetRange(vertsBD, 0, numVerts);
rtpBufferDescSetStride(vertsBD, sizeof(Vertex));
RTPresult RTPAPI rtpContextCreate ( RTPcontexttype  type,
RTPcontext *  context 
)

Creates an OptiX Prime context.

By default, a context created with type RTP_CONTEXT_TYPE_CUDA will use all available CUDA devices. Specific devices can be selected using rtpContextSetCudaDeviceNumbers. One device will be selected as the primary device and will be set as the current device when the function returns. If no available device has compute capability 2.0 or greater the created context will not be able to build acceleration structures.

Parameters
[in]typeThe type of context to create
[out]contextPointer to the new OptiX Prime context

Return values

Relevant return values:

Example Usage:

RTPcontext context;
if(rtpContextCreate( RTP_CONTEXT_TYPE_CUDA, &context ) == RTP_SUCCESS ) {
int deviceNumbers[] = {0,1};
rtpContextSetCudaDeviceNumbers( 2, deviceNumbers );
}
else
rtpContextCreate( RTP_CONTEXT_TYPE_CPU, &context ); // Fallback to CPU
RTPresult RTPAPI rtpContextDestroy ( RTPcontext  context)

Destroys an OptiX Prime context.

Ongoing work is finished before context is destroyed. All OptiX Prime objects associated with context are aslo destroyed when context is destroyed.

Parameters
[in]contextOptiX Prime context to destroy

Return values

Relevant return values:

RTPresult RTPAPI rtpContextGetLastErrorString ( RTPcontext  context,
const char **  return_string 
)

Returns a string describing last error encountered.

This function returns an error string for the last error encountered in context that may contain invocation-specific details beyond the simple RTPresult error code. Note that this function may return errors from previous asynchronous launches or from calls by other threads.

Parameters
[in]contextOptiX Prime context
[out]return_stringString with error details

Return values

Relevant return values:

See also rtpGetErrorString

RTPresult RTPAPI rtpContextSetCpuThreads ( RTPcontext  context,
unsigned  numThreads 
)

Sets the number of CPU threads used by a CPU context.

This function will return an error if the provided context is not of type RTP_CONTEXT_TYPE_CPU.

By default, one ray tracing thread is created per CPU core.

Parameters
[in]contextOptiX Prime context
[in]numThreadsNumber of threads used for the CPU context

Return values

Relevant return values:

RTPresult RTPAPI rtpContextSetCudaDeviceNumbers ( RTPcontext  context,
unsigned  deviceCount,
const unsigned *  deviceNumbers 
)

Sets the CUDA devices used by a context.

The first device provided in deviceNumbers will be used as the primary device. Acceleration structures will be built on the primary device and copied to the others. To build the acceleration structures the primary device must be of compute capability 2.0 or greater. The current device will be set to the primary device when this function returns.

If deviceCount==0, then the primary device is selected automatically and all available devices are selected for use. deviceNumbers is ignored.

Parameters
[in]contextOptiX Prime context
[in]deviceCountNumber of devices supplied in deviceNumbers or 0
[in]deviceNumbersArray of integer device indices, or NULL if deviceCount==0

This function will return an error if the provided context is not of type RTP_CONTEXT_TYPE_CUDA

Return values

Relevant return values:

RTPresult RTPAPI rtpGetErrorString ( RTPresult  errorCode,
const char **  errorString 
)

Translates an RTPresult error code to a string.

Translates an RTPresult error code to a string describing the error.

Parameters
[in]errorCodeError code to be translated
[out]errorStringReturned error string

Return values

Relevant return values:

See also rtpContextGetLastErrorString

RTPresult RTPAPI rtpGetVersion ( unsigned *  version)

Gets OptiX Prime version number.

The encoding for the version number is major*1000 + minor*10 + micro. For example, for version 3.5.1 this function would return 3051.

Parameters
[out]versionReturned version

Return values

Relevant return values:

RTPresult RTPAPI rtpGetVersionString ( const char **  versionString)

Gets OptiX Prime version string.

Returns OptiX Prime version string and other information in a human-readable format.

Parameters
[in]versionStringReturned version information

Return values

Relevant return values:

RTPresult RTPAPI rtpHostBufferLock ( void *  buffer,
RTPsize  size 
)

Page-locks a host buffer.

Transfers between the host and device are faster if the host buffers are page-locked. However, page-locked memory is a limited resource and should be used judiciously.

Parameters
[in]bufferBuffer on the host
[in]sizeSize of the buffer

Return values

Relevant return values:

RTPresult RTPAPI rtpHostBufferUnlock ( void *  buffer)

Unlocks a previously page-locked host buffer.

Transfers between the host and device are faster if the host buffers are page-locked. However, page-locked memory is a limited resource and should be used judiciously. Use this function on buffers previous page-locked with rtpHostBufferLock.

Parameters
[in]bufferBuffer on the host

Return values

Relevant return values:

RTPresult RTPAPI rtpModelCopy ( RTPmodel  model,
RTPmodel  srcModel 
)

Copies one model to another.

This function copies a model from one OptiX Prime context to another for user-managed multi-GPU operation where one context is allocated per device. Only triangle models can be copied, not instance models. Furthermore, when a srcModel has the RTP_BUILDER_PARAM_USE_CALLER_TRIANGLES build parameter set to 1, and it is intended that the triangle data is automatically transfered to the other context, the destination (model) should have the build parameter set to 0 before the copy call. If the destination model also has the has the build parameter set to 1, its triangles must be set by calling rtpModelSetTriangles followed by rtpModelUpdate using RTP_MODEL_HINT_USER_TRIANGLES_AFTER_COPY_SET.

Parameters
[in]modelDestination model
[in]srcModelSource model

Return values

Relevant return values:

RTPresult RTPAPI rtpModelCreate ( RTPcontext  context,
RTPmodel *  model 
)

Creates a model.

Parameters
[in]contextOptiX Prime context
[out]modelPointer to the new model

Return values

Relevant return values:

RTPresult RTPAPI rtpModelDestroy ( RTPmodel  model)

Destroys a model.

Any queries created on the model are also destroyed with the model. The queries are allowed to finish before they are destroyed.

Parameters
[in]modelModel

Return values

Relevant return values:

RTPresult RTPAPI rtpModelFinish ( RTPmodel  model)

Blocks current thread until model update is finished.

This function can be called multiple times. It will return immediately if the previous update has already finished.

Parameters
[in]modelModel

Return values

Relevant return values:

RTPresult RTPAPI rtpModelGetContext ( RTPmodel  model,
RTPcontext *  context 
)

Gets the context object associated with the model.

Parameters
[in]modelModel to obtain the context from
[out]contextReturned context

Return values

Relevant return values:

RTPresult RTPAPI rtpModelGetFinished ( RTPmodel  model,
int *  isFinished 
)

Polls the status of a model update.

Parameters
[in]modelModel
[out]isFinishedReturns finished status

Return values

Relevant return values:

RTPresult RTPAPI rtpModelSetBuilderParameter ( RTPmodel  model_api,
RTPbuilderparam  param,
RTPsize  size,
const void *  ptr 
)

Specifies a builder parameter for a model.

The following builder parameters are supported:

RTP_BUILDER_PARAM_USE_CALLER_TRIANGLES : int

If the value for RTP_BUILDER_PARAM_USE_CALLER_TRIANGLES is set to 0 (default), Prime uses an internal representation for triangles (which requires additional memory) to improve query performance and does not reference the user's vertex buffer during a query. If set to 1, Prime uses the provided triangle data as-is, which may result in slower query performance, but reduces memory usage.

RTP_BUILDER_PARAM_CHUNK_SIZE : RTPsize

Acceleration structures are built in chunks to reduce the amount of scratch memory needed. The size of the scratch memory chunk is specified in bytes by RTP_BUILDER_PARAM_CHUNK_SIZE. If set to -1, the chunk size has no limit. If set to 0 (default) the chunk size is chosen automatically, currently as 10% of the total available video memory for GPU builds and 512MB for CPU builds.

Parameters
[in]model_apiModel
[in]paramBuilder parameter to set
[in]sizeSize in bytes of the parameter being set
[in]ptrPointer to where the value of the attribute will be copied from. This must point to at least size bytes of memory

Return values

Relevant return values:

RTPresult RTPAPI rtpModelSetInstances ( RTPmodel  model,
RTPbufferdesc  instances,
RTPbufferdesc  transforms 
)

Sets the instance data for a model.

The instances buffer specifies a list of model instances, and the transforms buffer holds a transformation matrix for each instance. The instance buffer type must be RTP_BUFFER_TYPE_HOST.

Instance buffers must be of format RTP_BUFFER_FORMAT_INSTANCE_MODEL, and transform buffers of format RTP_BUFFER_FORMAT_TRANSFORM_FLOAT4x4 or RTP_BUFFER_FORMAT_TRANSFORM_FLOAT4x3. If a stride is specified for the transformations, it must be a multiple of 16 bytes. Furthermore, the matrices must be stored in row-major order. Only affine transformations are supported, and the last row is always assumed to be [0.0, 0.0, 0.0, 1.0].

All instance models in the instances buffer must belong to the same context as the model itself. Additionally, the build parameter RTP_BUILDER_PARAM_USE_CALLER_TRIANGLES must be the same for all models (if applied). Setting RTP_BUILDER_PARAM_USE_CALLER_TRIANGLES for a model which contains instances has no effect.

The buffers are not used until rtpModelUpdate is called.

Parameters
[in]modelModel
[in]instancesBuffer descriptor for instances
[in]transformsBuffer descriptor for 4x4 transform matrices

Return values

Relevant return values:

RTPresult RTPAPI rtpModelSetTriangles ( RTPmodel  model,
RTPbufferdesc  indices,
RTPbufferdesc  vertices 
)

Sets the triangle data for a model.

The index buffer specifies triplet of vertex indices. If the index buffer descriptor is not specified (e.g. indices==NULL), the vertex buffer is considered to be a flat list of triangles, with every three vertices forming a triangle. The buffers are not used until rtpModelUpdate is called.

Parameters
[in]modelModel
[in]indicesBuffer descriptor for triangle vertex indices, or NULL
[in]verticesBuffer descriptor for triangle vertices

Return values

Relevant return values:

RTPresult RTPAPI rtpModelUpdate ( RTPmodel  model,
unsigned  hints 
)

Updates data, or creates an acceleration structure over triangles or instances.

Depending on the specified hints, rtpModelUpdate performs different operations:

If the flag RTP_MODEL_HINT_ASYNC is specified, some or all of the acceleration structure update may run asynchronously and rtpModelUpdate may return before the update is finished. In the case of RTP_MODEL_HINT_NONE, the acceleration structure build is blocking. It is important that buffers specified in rtpModelSetTriangles and rtpModelSetInstances not be modified until the update has finished. rtpModelFinish blocks the current thread until the update is finished. rtpModelGetFinished can be used to poll until the update is finished. Once the update has finished the input buffers can be modified.

The acceleration structure build performed by rtpModelUpdate uses a fast, high quality algorithm, but has the cost of requiring additional working memory. The amount of working memory is controlled by RTP_BUILDER_PARAM_CHUNK_SIZE.

The flag RTP_MODEL_HINT_MASK_UPDATE should be used to inform Prime when visibility mask data changed (after calling rtpModelSetTriangles with the updated values), e.g. when the indices format RTP_BUFFER_FORMAT_INDICES_INT3_MASK_INT is used. RTP_MODEL_HINT_MASK_UPDATE can be combined with RTP_MODEL_HINT_ASYNC to perform asynchronous data updates.

Hint RTP_MODEL_HINT_USER_TRIANGLES_AFTER_COPY_SET should be used when a triangle model has been copied (with the user triangle build flag set), and new user triangles have been set (by calling rtpModelSetTriangles again with the updated values). RTP_MODEL_HINT_USER_TRIANGLES_AFTER_COPY_SET can be combined with RTP_MODEL_HINT_ASYNC to perform asynchronous data updates.

Parameters
[in]modelModel
[in]hintsA combination of flags from RTPmodelhint

Return values

Relevant return values:

Example Usage:

RTPmodel model;
rtpModelCreate(context, &model);
rtpModelSetTriangles(model, 0, vertsBD);
rtpModelUpdate(model, RTP_MODEL_HINT_ASYNC);
// ... do useful work on CPU while GPU is busy
rtpModelFinish(model);
// It is now safe to modify vertex buffer
RTPresult RTPAPI rtpQueryCreate ( RTPmodel  model,
RTPquerytype  queryType,
RTPquery *  query 
)

Creates a query on a model.

If the model to which a query is bound destroyed with rtpModelDestroy() the query will be destroyed as well.

Parameters
[in]modelModel to use for this query
[in]queryTypeType of the query
[out]queryPointer to the new query

Return values

Relevant return values:

RTPresult RTPAPI rtpQueryDestroy ( RTPquery  query)

Destroys a query.

The query is finished before it is destroyed

Parameters
[in]queryQuery to be destroyed

Return values

Relevant return values:

RTPresult RTPAPI rtpQueryExecute ( RTPquery  query,
unsigned  hints 
)

Executes a raytracing query.

If the flag RTP_QUERY_HINT_ASYNC is specified, rtpQueryExecute may return before the query is actually finished. rtpQueryFinish can be called to block the current thread until the query is finished, or rtpQueryGetFinished can be used to poll until the query is finished.

Parameters
[in]queryQuery
[in]hintsA combination of flags from RTPqueryhint

Once the query has finished all of the hits are guaranteed to have been returned, and it is safe to modify the ray buffer.

Return values

Relevant return values:

Example Usage:

RTPquery query;
rtpQueryCreate(model, RTP_QUERY_TYPE_CLOSEST, &query);
rtpQuerySetRays(query, raysBD);
rtpQuerySetHits(hits, hitsBD);
rtpQueryExecute(query, 0);
// safe to modify ray buffer and process hits
RTPresult RTPAPI rtpQueryFinish ( RTPquery  query)

Blocks current thread until query is finished.

This function can be called multiple times. It will return immediately if the query has already finished.

Parameters
[in]queryQuery

Return values

Relevant return values:

RTPresult RTPAPI rtpQueryGetContext ( RTPquery  query,
RTPcontext *  context 
)

Gets the context object associated with a query.

Parameters
[in]queryQuery to obtain the context from
[out]contextReturned context

Return values

Relevant return values:

RTPresult RTPAPI rtpQueryGetFinished ( RTPquery  query,
int *  isFinished 
)

Polls the status of a query.

Parameters
[in]queryQuery
[out]isFinishedReturns finished status

Return values

Relevant return values:

RTPresult RTPAPI rtpQuerySetCudaStream ( RTPquery  query,
cudaStream_t  stream 
)

Sets a sync stream for a query.

Specify a Cuda stream used for synchronization. If no stream is specified, the default 0-stream is used. A stream can only be specified for contexts with type RTP_CONTEXT_TYPE_CUDA.

Parameters
[in]queryQuery
[in]streamA cuda stream

Return values

Relevant return values:

RTPresult RTPAPI rtpQuerySetHits ( RTPquery  query,
RTPbufferdesc  hits 
)

Sets the hits buffer for a query.

A hit is reported for every ray in the query. Therefore the size of the range in the hit buffer must match that of the ray buffer.

Parameters
[in]queryQuery
[in]hitsBuffer descriptor for hits

Return values

Relevant return values:

RTPresult RTPAPI rtpQuerySetRays ( RTPquery  query,
RTPbufferdesc  rays 
)

Sets the rays buffer for a query.

The rays buffer is not accessed until rtpQueryExecute() is called.

Parameters
[in]queryQuery
[in]raysBuffer descriptor for rays

Return values

Relevant return values:

Generated on Thu Mar 31 2016 09:25:40 for OptiX by   doxygen 1.8.6