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

Modules

 rtContextLaunch functions
 

Functions

RTresult RTAPI rtContextCreate (RTcontext *context)
 
RTresult RTAPI rtContextDestroy (RTcontext context)
 
RTresult RTAPI rtContextValidate (RTcontext context)
 
void RTAPI rtContextGetErrorString (RTcontext context, RTresult code, const char **stringReturn)
 
RTresult RTAPI rtContextSetAttribute (RTcontext context, RTcontextattribute attrib, RTsize size, const void *p)
 
RTresult RTAPI rtContextGetAttribute (RTcontext context, RTcontextattribute attrib, RTsize size, void *p)
 
RTresult RTAPI rtContextSetDevices (RTcontext context, unsigned int count, const int *devices)
 
RTresult RTAPI rtContextGetDevices (RTcontext context, int *devices)
 
RTresult RTAPI rtContextGetDeviceCount (RTcontext context, unsigned int *count)
 
RTresult RTAPI rtContextSetStackSize (RTcontext context, RTsize bytes)
 
RTresult RTAPI rtContextGetStackSize (RTcontext context, RTsize *bytes)
 
RTresult RTAPI rtContextSetMaxCallableProgramDepth (RTcontext context, unsigned int maxDepth)
 
RTresult RTAPI rtContextGetMaxCallableProgramDepth (RTcontext context, unsigned int *maxDepth)
 
RTresult RTAPI rtContextSetMaxTraceDepth (RTcontext context, unsigned int maxDepth)
 
RTresult RTAPI rtContextGetMaxTraceDepth (RTcontext context, unsigned int *maxDepth)
 
RTresult RTAPI rtContextSetUsageReportCallback (RTcontext context, RTusagereportcallback callback, int verbosity, void *cbdata)
 
RTresult RTAPI rtContextSetEntryPointCount (RTcontext context, unsigned int count)
 
RTresult RTAPI rtContextGetEntryPointCount (RTcontext context, unsigned int *count)
 
RTresult RTAPI rtContextSetRayGenerationProgram (RTcontext context, unsigned int entryPointIndex, RTprogram program)
 
RTresult RTAPI rtContextGetRayGenerationProgram (RTcontext context, unsigned int entryPointIndex, RTprogram *program)
 
RTresult RTAPI rtContextSetExceptionProgram (RTcontext context, unsigned int entryPointIndex, RTprogram program)
 
RTresult RTAPI rtContextGetExceptionProgram (RTcontext context, unsigned int entryPointIndex, RTprogram *program)
 
RTresult RTAPI rtContextSetExceptionEnabled (RTcontext context, RTexception exception, int enabled)
 
RTresult RTAPI rtContextGetExceptionEnabled (RTcontext context, RTexception exception, int *enabled)
 
RTresult RTAPI rtContextSetRayTypeCount (RTcontext context, unsigned int rayTypeCount)
 
RTresult RTAPI rtContextGetRayTypeCount (RTcontext context, unsigned int *rayTypeCount)
 
RTresult RTAPI rtContextSetMissProgram (RTcontext context, unsigned int rayTypeIndex, RTprogram program)
 
RTresult RTAPI rtContextGetMissProgram (RTcontext context, unsigned int rayTypeIndex, RTprogram *program)
 
RTresult RTAPI rtContextGetTextureSamplerFromId (RTcontext context, int samplerId, RTtexturesampler *sampler)
 
RTresult RTAPI rtContextGetRunningState (RTcontext context, int *running)
 
RTresult RTAPI rtContextLaunchProgressive2D (RTcontext context, unsigned int entryIndex, RTsize width, RTsize height, unsigned int maxSubframes)
 
RTresult RTAPI rtContextStopProgressive (RTcontext context)
 
RTresult RTAPI rtContextSetPrintEnabled (RTcontext context, int enabled)
 
RTresult RTAPI rtContextGetPrintEnabled (RTcontext context, int *enabled)
 
RTresult RTAPI rtContextSetPrintBufferSize (RTcontext context, RTsize bufferSizeBytes)
 
RTresult RTAPI rtContextGetPrintBufferSize (RTcontext context, RTsize *bufferSizeBytes)
 
RTresult RTAPI rtContextSetPrintLaunchIndex (RTcontext context, int x, int y, int z)
 
RTresult RTAPI rtContextGetPrintLaunchIndex (RTcontext context, int *x, int *y, int *z)
 
RTresult RTAPI rtContextDeclareVariable (RTcontext context, const char *name, RTvariable *v)
 
RTresult RTAPI rtContextQueryVariable (RTcontext context, const char *name, RTvariable *v)
 
RTresult RTAPI rtContextRemoveVariable (RTcontext context, RTvariable v)
 
RTresult RTAPI rtContextGetVariableCount (RTcontext context, unsigned int *count)
 
RTresult RTAPI rtContextGetVariable (RTcontext context, unsigned int index, RTvariable *v)
 
RTresult RTAPI rtContextGetBufferFromId (RTcontext context, int bufferId, RTbuffer *buffer)
 

Detailed Description

Functions related to an OptiX context.

Function Documentation

RTresult RTAPI rtContextCreate ( RTcontext context)

Creates a new context object.

Description

rtContextCreate allocates and returns a handle to a new context object. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[out]contextHandle to context for return value

Return values

Relevant return values:

History

rtContextCreate was introduced in OptiX 1.0.

See also

RTresult RTAPI rtContextDeclareVariable ( RTcontext  context,
const char *  name,
RTvariable v 
)

Declares a new named variable associated with this context.

Description

rtContextDeclareVariable - Declares a new variable named name and associated with this context. Only a single variable of a given name can exist for a given context and any attempt to create multiple variables with the same name will cause a failure with a return value of RT_ERROR_VARIABLE_REDECLARED. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer. Return RT_ERROR_ILLEGAL_SYMBOL if name is not syntactically valid.

Parameters
[in]contextThe context node to which the variable will be attached
[in]nameThe name that identifies the variable to be queried
[out]vPointer to variable handle used to return the new object

Return values

Relevant return values:

History

rtContextDeclareVariable was introduced in OptiX 1.0.

See also rtGeometryDeclareVariable, rtGeometryInstanceDeclareVariable, rtMaterialDeclareVariable, rtProgramDeclareVariable, rtSelectorDeclareVariable, rtContextGetVariable, rtContextGetVariableCount, rtContextQueryVariable, rtContextRemoveVariable

RTresult RTAPI rtContextDestroy ( RTcontext  context)

Destroys a context and frees all associated resources.

Description

rtContextDestroy frees all resources, including OptiX objects, associated with this object. Returns RT_ERROR_INVALID_VALUE if passed a NULL context. RT_ERROR_LAUNCH_FAILED may be returned if a previous call to rtContextLaunch failed.

Parameters
[in]contextHandle of the context to destroy

Return values

Relevant return values:

History

rtContextDestroy was introduced in OptiX 1.0.

See also rtContextCreate

RTresult RTAPI rtContextGetAttribute ( RTcontext  context,
RTcontextattribute  attrib,
RTsize  size,
void *  p 
)

Returns an attribute specific to an OptiX context.

Description

rtContextGetAttribute returns in p the value of the per context attribute specified by attrib.

Each attribute can have a different size. The sizes are given in the following list:

RT_CONTEXT_ATTRIBUTE_MAX_TEXTURE_COUNT queries the maximum number of textures handled by OptiX. For OptiX versions below 2.5 this value depends on the number of textures supported by CUDA.

RT_CONTEXT_ATTRIBUTE_CPU_NUM_THREADS queries the number of host CPU threads OptiX can use for various tasks.

RT_CONTEXT_ATTRIBUTE_USED_HOST_MEMORY queries the amount of host memory allocated by OptiX.

RT_CONTEXT_ATTRIBUTE_AVAILABLE_DEVICE_MEMORY queries the amount of free device memory.

RT_CONTEXT_ATTRIBUTE_DISK_CACHE_ENABLED queries whether or not the OptiX disk cache is enabled.

RT_CONTEXT_ATTRIBUTE_DISK_CACHE_LOCATION queries the file path of the OptiX disk cache.

RT_CONTEXT_ATTRIBUTE_DISK_CACHE_MEMORY_LIMITS queries the low and high watermark values for the OptiX disk cache.

Some attributes are used to get per device information. In contrast to rtDeviceGetAttribute, these attributes are determined by the context and are therefore queried through the context. This is done by adding the attribute with the OptiX device ordinal number when querying the attribute. The following are per device attributes.

RT_CONTEXT_ATTRIBUTE_AVAILABLE_DEVICE_MEMORY

Parameters
[in]contextThe context object to be queried
[in]attribAttribute to query
[in]sizeSize of the attribute being queried. Parameter p must have at least this much memory allocated
[out]pReturn pointer where the value of the attribute will be copied into. This must point to at least size bytes of memory

Return values

Relevant return values:

  • RT_SUCCESS
  • RT_ERROR_INVALID_VALUE - Can be returned if size does not match the proper size of the attribute, if p is NULL, or if attribute+ordinal does not correspond to an OptiX device

History

rtContextGetAttribute was introduced in OptiX 2.0.

See also rtContextGetDeviceCount, rtContextSetAttribute, rtDeviceGetAttribute

RTresult RTAPI rtContextGetBufferFromId ( RTcontext  context,
int  bufferId,
RTbuffer buffer 
)

Gets an RTbuffer corresponding to the buffer id.

Description

rtContextGetBufferFromId returns a handle to the buffer in *buffer corresponding to the bufferId supplied. If bufferId does not map to a valid buffer handle, *buffer is NULL or if context is invalid, returns RT_ERROR_INVALID_VALUE.

Parameters
[in]contextThe context the buffer should be originated from
[in]bufferIdThe ID of the buffer to query
[out]bufferThe return handle for the buffer object corresponding to the bufferId

Return values

Relevant return values:

History

rtContextGetBufferFromId was introduced in OptiX 3.5.

See also rtBufferGetId

RTresult RTAPI rtContextGetDeviceCount ( RTcontext  context,
unsigned int *  count 
)

Query the number of devices currently being used.

Description

rtContextGetDeviceCount - Query the number of devices currently being used.

Parameters
[in]contextThe context containing the devices
[out]countReturn parameter for the device count

Return values

Relevant return values:

History

rtContextGetDeviceCount was introduced in OptiX 2.0.

See also rtContextSetDevices, rtContextGetDevices

RTresult RTAPI rtContextGetDevices ( RTcontext  context,
int *  devices 
)

Retrieve a list of hardware devices being used by the kernel.

Description

rtContextGetDevices retrieves a list of hardware devices used by the context. Note that the device numbers are OptiX device ordinals, which may not be the same as CUDA device ordinals. Use rtDeviceGetAttribute with RT_DEVICE_ATTRIBUTE_CUDA_DEVICE_ORDINAL to query the CUDA device corresponding to a particular OptiX device.

Parameters
[in]contextThe context to which the hardware list is applied
[out]devicesReturn parameter for the list of devices. The memory must be able to hold entries numbering least the number of devices as returned by rtContextGetDeviceCount

Return values

Relevant return values:

History

rtContextGetDevices was introduced in OptiX 2.0.

See also rtContextSetDevices, rtContextGetDeviceCount

RTresult RTAPI rtContextGetEntryPointCount ( RTcontext  context,
unsigned int *  count 
)

Query the number of entry points for this context.

Description

rtContextGetEntryPointCount passes back the number of entry points associated with this context in count. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context node to be queried
[out]countReturn parameter for passing back the entry point count

Return values

Relevant return values:

History

rtContextGetEntryPointCount was introduced in OptiX 1.0.

See also rtContextSetEntryPointCount

void RTAPI rtContextGetErrorString ( RTcontext  context,
RTresult  code,
const char **  stringReturn 
)

Returns the error string associated with a given error.

Description

rtContextGetErrorString return a descriptive string given an error code. If context is valid and additional information is available from the last OptiX failure, it will be appended to the generic error code description. stringReturn will be set to point to this string. The memory stringReturn points to will be valid until the next API call that returns a string.

Parameters
[in]contextThe context object to be queried, or NULL
[in]codeThe error code to be converted to string
[out]stringReturnThe return parameter for the error string

Return values

rtContextGetErrorString does not return a value

History

rtContextGetErrorString was introduced in OptiX 1.0.

See also

RTresult RTAPI rtContextGetExceptionEnabled ( RTcontext  context,
RTexception  exception,
int *  enabled 
)

Query whether a specified exception is enabled.

Description

rtContextGetExceptionEnabled passes back 1 in *enabled if the given exception is enabled, 0 otherwise. exception specifies the type of exception to be queried. For a list of available types, see rtContextSetExceptionEnabled. If exception is RT_EXCEPTION_ALL, enabled is set to 1 only if all possible exceptions are enabled.

Parameters
[in]contextThe context to be queried
[in]exceptionThe exception of which to query the state
[out]enabledReturn parameter to store whether the exception is enabled

Return values

Relevant return values:

History

rtContextGetExceptionEnabled was introduced in OptiX 1.1.

See also rtContextSetExceptionEnabled, rtContextSetExceptionProgram, rtContextGetExceptionProgram, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails, RTexception

RTresult RTAPI rtContextGetExceptionProgram ( RTcontext  context,
unsigned int  entryPointIndex,
RTprogram program 
)

Queries the exception program associated with the given context and entry point.

Description

rtContextGetExceptionProgram passes back the exception program associated with the given context and entry point. This program is set via rtContextSetExceptionProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid entry point index or NULL pointer.

Parameters
[in]contextThe context node associated with the exception program
[in]entryPointIndexThe entry point index for the desired exception program
[out]programReturn parameter to store the exception program

Return values

Relevant return values:

History

rtContextGetExceptionProgram was introduced in OptiX 1.0.

See also rtContextSetExceptionProgram, rtContextSetEntryPointCount, rtContextSetExceptionEnabled, rtContextGetExceptionEnabled, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails

RTresult RTAPI rtContextGetMaxCallableProgramDepth ( RTcontext  context,
unsigned int *  maxDepth 
)

Query the maximum call depth for callable programs.

Description

rtContextGetMaxCallableProgramDepth passes back the maximum callable program call depth associated with this context in maxDepth. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context node to be queried
[out]maxDepthReturn parameter to store the maximum callable program depth

Return values

Relevant return values:

History

rtContextGetMaxCallableProgramDepth was introduced in OptiX 6.0

See also rtContextSetMaxCallableProgramDepth

RTresult RTAPI rtContextGetMaxTraceDepth ( RTcontext  context,
unsigned int *  maxDepth 
)

Query the maximum trace depth for this context.

Description

rtContextGetMaxTraceDepth passes back the maximum trace depth associated with this context in maxDepth. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context node to be queried
[out]maxDepthReturn parameter to store the maximum trace depth

Return values

Relevant return values:

History

rtContextGetMaxTraceDepth was introduced in OptiX 6.0.

See also rtContextSetMaxTraceDepth

RTresult RTAPI rtContextGetMissProgram ( RTcontext  context,
unsigned int  rayTypeIndex,
RTprogram program 
)

Queries the miss program associated with the given context and ray type.

Description

rtContextGetMissProgram passes back the miss program associated with the given context and ray type. This program is set via rtContextSetMissProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid ray type index or a NULL pointer.

Parameters
[in]contextThe context node associated with the miss program
[in]rayTypeIndexThe ray type index for the desired miss program
[out]programReturn parameter to store the miss program

Return values

Relevant return values:

History

rtContextGetMissProgram was introduced in OptiX 1.0.

See also rtContextSetMissProgram, rtContextGetRayTypeCount

RTresult RTAPI rtContextGetPrintBufferSize ( RTcontext  context,
RTsize bufferSizeBytes 
)

Get the current size of the print buffer.

Description

rtContextGetPrintBufferSize is used to query the buffer size available to hold data generated by rtPrintf functions. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context from which to query the print buffer size
[out]bufferSizeBytesThe returned print buffer size in bytes

Return values

Relevant return values:

History

rtContextGetPrintBufferSize was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextSetPrintEnabled, rtContextGetPrintEnabled, rtContextSetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex

RTresult RTAPI rtContextGetPrintEnabled ( RTcontext  context,
int *  enabled 
)

Query whether text printing from programs is enabled.

Description

rtContextGetPrintEnabled passes back 1 if text printing from programs through rtPrintf functions is currently enabled for this context; 0 otherwise. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context to be queried
[out]enabledReturn parameter to store whether printing is enabled

Return values

Relevant return values:

History

rtContextGetPrintEnabled was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex

RTresult RTAPI rtContextGetPrintLaunchIndex ( RTcontext  context,
int *  x,
int *  y,
int *  z 
)

Gets the active print launch index.

Description

rtContextGetPrintLaunchIndex is used to query for which launch indices rtPrintf functions generates output. The initial value of (x,y,z) is (-1,-1,-1), which generates output for all indices.

Parameters
[in]contextThe context from which to query the print launch index
[out]xReturns the launch index in the x dimension to which the output of rtPrintf functions invocations is limited. Will not be written to if a NULL pointer is passed
[out]yReturns the launch index in the y dimension to which the output of rtPrintf functions invocations is limited. Will not be written to if a NULL pointer is passed
[out]zReturns the launch index in the z dimension to which the output of rtPrintf functions invocations is limited. Will not be written to if a NULL pointer is passed

Return values

Relevant return values:

History

rtContextGetPrintLaunchIndex was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextGetPrintEnabled, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex

RTresult RTAPI rtContextGetRayGenerationProgram ( RTcontext  context,
unsigned int  entryPointIndex,
RTprogram program 
)

Queries the ray generation program associated with the given context and entry point.

Description

rtContextGetRayGenerationProgram passes back the ray generation program associated with the given context and entry point. This program is set via rtContextSetRayGenerationProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid entry point index or NULL pointer.

Parameters
[in]contextThe context node associated with the ray generation program
[in]entryPointIndexThe entry point index for the desired ray generation program
[out]programReturn parameter to store the ray generation program

Return values

Relevant return values:

History

rtContextGetRayGenerationProgram was introduced in OptiX 1.0.

See also rtContextSetRayGenerationProgram

RTresult RTAPI rtContextGetRayTypeCount ( RTcontext  context,
unsigned int *  rayTypeCount 
)

Query the number of ray types associated with this context.

Description

rtContextGetRayTypeCount passes back the number of entry points associated with this context in rayTypeCount. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context node to be queried
[out]rayTypeCountReturn parameter to store the number of ray types

Return values

Relevant return values:

History

rtContextGetRayTypeCount was introduced in OptiX 1.0.

See also rtContextSetRayTypeCount

RTresult RTAPI rtContextGetRunningState ( RTcontext  context,
int *  running 
)

Query whether the given context is currently running.

Description

This function is currently unimplemented and it is provided as a placeholder for a future implementation.

Parameters
[in]contextThe context node to be queried
[out]runningReturn parameter to store the running state

Return values

Since unimplemented, this function will always throw an assertion failure.

History

rtContextGetRunningState was introduced in OptiX 1.0.

See also rtContextLaunch1D, rtContextLaunch2D, rtContextLaunch3D

RTresult RTAPI rtContextGetStackSize ( RTcontext  context,
RTsize bytes 
)

Query the stack size for this context.

Description

rtContextGetStackSize passes back the stack size associated with this context in bytes. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context node to be queried
[out]bytesReturn parameter to store the size of the stack

Return values

Relevant return values:

History

rtContextGetStackSize was introduced in OptiX 1.0.

See also rtContextSetStackSize

RTresult RTAPI rtContextGetTextureSamplerFromId ( RTcontext  context,
int  samplerId,
RTtexturesampler sampler 
)

Gets an RTtexturesampler corresponding to the texture id.

Description

rtContextGetTextureSamplerFromId returns a handle to the texture sampler in *sampler corresponding to the samplerId supplied. If samplerId does not map to a valid texture handle, *sampler is NULL or if context is invalid, returns RT_ERROR_INVALID_VALUE.

Parameters
[in]contextThe context the sampler should be originated from
[in]samplerIdThe ID of the sampler to query
[out]samplerThe return handle for the sampler object corresponding to the samplerId

Return values

Relevant return values:

History

rtContextGetTextureSamplerFromId was introduced in OptiX 3.5.

See also rtTextureSamplerGetId

RTresult RTAPI rtContextGetVariable ( RTcontext  context,
unsigned int  index,
RTvariable v 
)

Queries an indexed variable associated with this context.

Description

rtContextGetVariable queries the variable at position index in the variable array from context and stores the result in the parameter v. A variable must be declared first with rtContextDeclareVariable and index must be in the range [0, rtContextGetVariableCount -1].

Parameters
[in]contextThe context node to be queried for an indexed variable
[in]indexThe index that identifies the variable to be queried
[out]vReturn value to store the queried variable

Return values

Relevant return values:

History

rtContextGetVariable was introduced in OptiX 1.0.

See also rtGeometryGetVariable, rtGeometryInstanceGetVariable, rtMaterialGetVariable, rtProgramGetVariable, rtSelectorGetVariable, rtContextDeclareVariable, rtContextGetVariableCount, rtContextQueryVariable, rtContextRemoveVariable

RTresult RTAPI rtContextGetVariableCount ( RTcontext  context,
unsigned int *  count 
)

Returns the number of variables associated with this context.

Description

rtContextGetVariableCount returns the number of variables that are currently attached to context. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.

Parameters
[in]contextThe context to be queried for number of attached variables
[out]countReturn parameter to store the number of variables

Return values

Relevant return values:

History

rtContextGetVariableCount was introduced in OptiX 1.0.

See also rtGeometryGetVariableCount, rtGeometryInstanceGetVariableCount, rtMaterialGetVariableCount, rtProgramGetVariableCount, rtSelectorGetVariable, rtContextDeclareVariable, rtContextGetVariable, rtContextQueryVariable, rtContextRemoveVariable

RTresult RTAPI rtContextLaunchProgressive2D ( RTcontext  context,
unsigned int  entryIndex,
RTsize  width,
RTsize  height,
unsigned int  maxSubframes 
)

Executes a Progressive Launch for a given context.

Description

Starts the (potentially parallel) generation of subframes for progressive rendering. If maxSubframes is zero, there is no limit on the number of subframes generated. The generated subframes are automatically composited into a single result and streamed to the client at regular intervals, where they can be read by mapping an associated stream buffer. An application can therefore initiate a progressive launch, and then repeatedly map and display the contents of the stream buffer in order to visualize the progressive refinement of the image.

The call is nonblocking. A polling approach should be used to decide when to map and display the stream buffer contents (see rtBufferGetProgressiveUpdateReady). If a progressive launch is already in progress at the time of the call and its parameters match the initial launch, the call has no effect. Otherwise, the accumulated result will be reset and a new progressive launch will be started.

If any other OptiX function is called while a progressive launch is in progress, it will cause the launch to stop generating new subframes (however, subframes that have already been generated and are currently in flight may still arrive at the client). The only exceptions to this rule are the operations to map a stream buffer, issuing another progressive launch with unchanged parameters, and polling for an update. Those exceptions do not cause the progressive launch to stop generating subframes.

There is no guarantee that the call actually produces any subframes, especially if rtContextLaunchProgressive2D and other OptiX commands are called in short succession. For example, during an animation, Variable setters calls may be tightly interleaved with progressive launches, and when rendering remotely the server may decide to skip some of the launches in order to avoid a large backlog in the command pipeline.

Parameters
[in]contextThe context in which the launch is to be executed
[in]entryIndexThe initial entry point into kernel
[in]widthWidth of the computation grid
[in]heightHeight of the computation grid
[in]maxSubframesThe maximum number of subframes to be generated. Set to zero to generate an unlimited number of subframes

Return values

Relevant return values:

History

rtContextLaunchProgressive2D was introduced in OptiX 3.8.

See also rtContextStopProgressive rtBufferGetProgressiveUpdateReady

RTresult RTAPI rtContextQueryVariable ( RTcontext  context,
const char *  name,
RTvariable v 
)

Returns a named variable associated with this context.

Description

rtContextQueryVariable queries a variable identified by the string name from context and stores the result in *v. A variable must be declared with rtContextDeclareVariable before it can be queried, otherwise *v will be set to NULL. RT_ERROR_INVALID_VALUE will be returned if name or v is NULL.

Parameters
[in]contextThe context node to query a variable from
[in]nameThe name that identifies the variable to be queried
[out]vReturn value to store the queried variable

Return values

Relevant return values:

History

rtContextQueryVariable was introduced in OptiX 1.0.

See also rtGeometryQueryVariable, rtGeometryInstanceQueryVariable, rtMaterialQueryVariable, rtProgramQueryVariable, rtSelectorQueryVariable, rtContextDeclareVariable, rtContextGetVariableCount, rtContextGetVariable, rtContextRemoveVariable

RTresult RTAPI rtContextRemoveVariable ( RTcontext  context,
RTvariable  v 
)

Removes a variable from the given context.

Description

rtContextRemoveVariable removes variable v from context if present. Returns RT_ERROR_VARIABLE_NOT_FOUND if the variable is not attached to this context. Returns RT_ERROR_INVALID_VALUE if passed an invalid variable.

Parameters
[in]contextThe context node from which to remove a variable
[in]vThe variable to be removed

Return values

Relevant return values:

History

rtContextRemoveVariable was introduced in OptiX 1.0.

See also rtGeometryRemoveVariable, rtGeometryInstanceRemoveVariable, rtMaterialRemoveVariable, rtProgramRemoveVariable, rtSelectorRemoveVariable, rtContextDeclareVariable, rtContextGetVariable, rtContextGetVariableCount, rtContextQueryVariable,

RTresult RTAPI rtContextSetAttribute ( RTcontext  context,
RTcontextattribute  attrib,
RTsize  size,
const void *  p 
)

Set an attribute specific to an OptiX context.

Description

rtContextSetAttribute sets p as the value of the per context attribute specified by attrib.

Each attribute can have a different size. The sizes are given in the following list:

RT_CONTEXT_ATTRIBUTE_CPU_NUM_THREADS sets the number of host CPU threads OptiX can use for various tasks.

RT_CONTEXT_ATTRIBUTE_PREFER_FAST_RECOMPILES is a hint about scene usage. By default OptiX produces device kernels that are optimized for the current scene. Such kernels generally run faster, but must be recompiled after some types of scene changes, causing delays. Setting PREFER_FAST_RECOMPILES to 1 will leave out some scene-specific optimizations, producing kernels that generally run slower but are less sensitive to changes in the scene.

RT_CONTEXT_ATTRIBUTE_FORCE_INLINE_USER_FUNCTIONS sets whether or not OptiX will automatically inline user functions, which is the default behavior. Please see the Programming Guide for more information about the benefits and limitations of disabling automatic inlining.

RT_CONTEXT_ATTRIBUTE_DISK_CACHE_LOCATION sets the location where the OptiX disk cache will be created. The location must be provided as a NULL-terminated string. OptiX will attempt to create the directory if it does not exist. An exception will be thrown if OptiX is unable to create the cache database file at the specified location for any reason (e.g., the path is invalid or the directory is not writable). The location of the disk cache can be overridden with the environment variable OPTIX_CACHE_PATH. This environment variable takes precedence over the RTcontext attribute.

RT_CONTEXT_ATTRIBUTE_DISK_CACHE_MEMORY_LIMITS sets the low and high watermarks for disk cache garbage collection. The limits must be passed in as a two-element array of RTsize values, with the low limit as the first element. OptiX will throw an exception if either limit is non-zero and the high limit is not greater than the low limit. Setting either limit to zero will disable garbage collection. Garbage collection is triggered whenever the cache data size exceeds the high watermark and proceeds until the size reaches the low watermark.

RT_CONTEXT_ATTRIBUTE_PREFER_WATERTIGHT_TRAVERSAL sets whether or not OptiX should prefer to use a watertight traversal method or not. The default behaviour is preferring to use watertight traversal. Note that OptiX might still choose to decide otherwise though. Please see the Programming Guide for more information about the different traversal methods.

Parameters
[in]contextThe context object to be modified
[in]attribAttribute to set
[in]sizeSize of the attribute being set
[in]pPointer 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:

History

rtContextSetAttribute was introduced in OptiX 2.5.

See also rtContextGetAttribute

RTresult RTAPI rtContextSetDevices ( RTcontext  context,
unsigned int  count,
const int *  devices 
)

Specify a list of hardware devices to be used by the kernel.

Description

rtContextSetDevices specifies a list of hardware devices to be used during execution of the subsequent trace kernels. Note that the device numbers are OptiX device ordinals, which may not be the same as CUDA device ordinals. Use rtDeviceGetAttribute with RT_DEVICE_ATTRIBUTE_CUDA_DEVICE_ORDINAL to query the CUDA device corresponding to a particular OptiX device.

Parameters
[in]contextThe context to which the hardware list is applied
[in]countThe number of devices in the list
[in]devicesThe list of devices

Return values

Relevant return values:

History

rtContextSetDevices was introduced in OptiX 1.0.

See also rtContextGetDevices, rtContextGetDeviceCount

RTresult RTAPI rtContextSetEntryPointCount ( RTcontext  context,
unsigned int  count 
)

Set the number of entry points for a given context.

Description

rtContextSetEntryPointCount sets the number of entry points associated with the given context to count.

Parameters
[in]contextThe context to be modified
[in]countThe number of entry points to use

Return values

Relevant return values:

History

rtContextSetEntryPointCount was introduced in OptiX 1.0.

See also rtContextGetEntryPointCount

RTresult RTAPI rtContextSetExceptionEnabled ( RTcontext  context,
RTexception  exception,
int  enabled 
)

Enable or disable an exception.

Description

rtContextSetExceptionEnabled is used to enable or disable specific exceptions. If an exception is enabled, the exception condition is checked for at runtime, and the exception program is invoked if the condition is met. The exception program can query the type of the caught exception by calling rtGetExceptionCode. exception may take one of the following values:

RT_EXCEPTION_PAYLOAD_ACCESS_OUT_OF_BOUNDS verifies that accesses to the ray payload are within valid bounds. This exception is only supported with the RTX execution strategy.

RT_EXCEPTION_USER_EXCEPTION_CODE_OUT_OF_BOUNDS verifies that the exception code passed to rtThrow is within the valid range from RT_EXCEPTION_USER to RT_EXCEPTION_USER_MAX.

RT_EXCEPTION_TRACE_DEPTH_EXCEEDED verifies that the depth of the rtTrace tree does not exceed the limit of 31. This exception is only supported with the RTX execution strategy.

RT_EXCEPTION_TEXTURE_ID_INVALID verifies that every access of a texture id is valid, including use of RT_TEXTURE_ID_NULL and IDs out of bounds.

RT_EXCEPTION_BUFFER_ID_INVALID verifies that every access of a buffer id is valid, including use of RT_BUFFER_ID_NULL and IDs out of bounds.

RT_EXCEPTION_INDEX_OUT_OF_BOUNDS checks that rtIntersectChild and rtReportIntersection are called with a valid index.

RT_EXCEPTION_STACK_OVERFLOW checks the runtime stack against overflow. The most common cause for an overflow is a too deep rtTrace recursion tree.

RT_EXCEPTION_BUFFER_INDEX_OUT_OF_BOUNDS checks every read and write access to rtBuffer objects to be within valid bounds. This exception is supported with the RTX execution strategy only.

RT_EXCEPTION_INVALID_RAY checks the each ray's origin and direction values against NaNs and infinity values.

RT_EXCEPTION_INTERNAL_ERROR indicates an unexpected internal error in the runtime.

RT_EXCEPTION_USER is used to enable or disable all user-defined exceptions. See rtThrow for more information.

RT_EXCEPTION_ALL is a placeholder value which can be used to enable or disable all possible exceptions with a single call to rtContextSetExceptionEnabled.

By default, RT_EXCEPTION_STACK_OVERFLOW is enabled and all other exceptions are disabled.

Parameters
[in]contextThe context for which the exception is to be enabled or disabled
[in]exceptionThe exception which is to be enabled or disabled
[in]enabledNonzero to enable the exception, 0 to disable the exception

Return values

Relevant return values:

History

rtContextSetExceptionEnabled was introduced in OptiX 1.1.

See also rtContextGetExceptionEnabled, rtContextSetExceptionProgram, rtContextGetExceptionProgram, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails, RTexception

RTresult RTAPI rtContextSetExceptionProgram ( RTcontext  context,
unsigned int  entryPointIndex,
RTprogram  program 
)

Specifies the exception program for a given context entry point.

Description

rtContextSetExceptionProgram sets context's exception program at entry point entryPointIndex. RT_ERROR_INVALID_VALUE is returned if entryPointIndex is outside of the range [0, rtContextGetEntryPointCount -1].

Parameters
[in]contextThe context node to which the exception program will be added
[in]entryPointIndexThe entry point the program will be associated with
[in]programThe exception program

Return values

Relevant return values:

History

rtContextSetExceptionProgram was introduced in OptiX 1.0.

See also rtContextGetEntryPointCount, rtContextGetExceptionProgram rtContextSetExceptionEnabled, rtContextGetExceptionEnabled, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails

RTresult RTAPI rtContextSetMaxCallableProgramDepth ( RTcontext  context,
unsigned int  maxDepth 
)

Set maximum callable program call depth for a given context.

Description

rtContextSetMaxCallableProgramDepth sets the maximum call depth of a chain of callable programs for the given context to maxDepth. This value is only used for stack size computation. Only supported for RTX execution mode. Default value is 5. Returns RT_ERROR_INVALID_VALUE if context is not valid.

Parameters
[in]contextThe context node to be modified
[in]maxDepthThe desired maximum depth

Return values

Relevant return values:

History

rtContextSetMaxCallableProgramDepth was introduced in OptiX 6.0

See also rtContextGetMaxCallableProgramDepth

RTresult RTAPI rtContextSetMaxTraceDepth ( RTcontext  context,
unsigned int  maxDepth 
)

Set the maximum trace depth for a given context.

Description

rtContextSetMaxTraceDepth sets the maximum trace depth for the given context to maxDepth. Only supported for RTX execution mode. Default value is 5. Maximum trace depth is 31. Returns RT_ERROR_INVALID_VALUE if context is not valid.

Parameters
[in]contextThe context node to be modified
[in]maxDepthThe desired maximum depth

Return values

Relevant return values:

History

rtContextSetMaxTraceDepth was introduced in OptiX 6.0

See also rtContextGetMaxTraceDepth

RTresult RTAPI rtContextSetMissProgram ( RTcontext  context,
unsigned int  rayTypeIndex,
RTprogram  program 
)

Specifies the miss program for a given context ray type.

Description

rtContextSetMissProgram sets context's miss program associated with ray type rayTypeIndex. RT_ERROR_INVALID_VALUE is returned if rayTypeIndex is outside of the range [0, rtContextGetRayTypeCount -1].

Parameters
[in]contextThe context node to which the miss program will be added
[in]rayTypeIndexThe ray type the program will be associated with
[in]programThe miss program

Return values

Relevant return values:

History

rtContextSetMissProgram was introduced in OptiX 1.0.

See also rtContextGetRayTypeCount, rtContextGetMissProgram

RTresult RTAPI rtContextSetPrintBufferSize ( RTcontext  context,
RTsize  bufferSizeBytes 
)

Set the size of the print buffer.

Description

rtContextSetPrintBufferSize is used to set the buffer size available to hold data generated by rtPrintf functions. Returns RT_ERROR_INVALID_VALUE if it is called after the first invocation of rtContextLaunch.

Parameters
[in]contextThe context for which to set the print buffer size
[in]bufferSizeBytesThe print buffer size in bytes

Return values

Relevant return values:

History

rtContextSetPrintBufferSize was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextSetPrintEnabled, rtContextGetPrintEnabled, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex

RTresult RTAPI rtContextSetPrintEnabled ( RTcontext  context,
int  enabled 
)

Enable or disable text printing from programs.

Description

rtContextSetPrintEnabled is used to control whether text printing in programs through rtPrintf functions is currently enabled for this context.

Parameters
[in]contextThe context for which printing is to be enabled or disabled
[in]enabledSetting this parameter to a nonzero value enables printing, 0 disables printing

Return values

Relevant return values:

History

rtContextSetPrintEnabled was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextGetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex

RTresult RTAPI rtContextSetPrintLaunchIndex ( RTcontext  context,
int  x,
int  y,
int  z 
)

Sets the active launch index to limit text output.

Description

rtContextSetPrintLaunchIndex is used to control for which launch indices rtPrintf functions generates output. The initial value of (x,y,z) is (-1,-1,-1), which generates output for all indices.

Parameters
[in]contextThe context for which to set the print launch index
[in]xThe launch index in the x dimension to which to limit the output of rtPrintf functions invocations. If set to -1, output is generated for all launch indices in the x dimension
[in]yThe launch index in the y dimension to which to limit the output of rtPrintf functions invocations. If set to -1, output is generated for all launch indices in the y dimension
[in]zThe launch index in the z dimension to which to limit the output of rtPrintf functions invocations. If set to -1, output is generated for all launch indices in the z dimension

Return values

Relevant return values:

History

rtContextSetPrintLaunchIndex was introduced in OptiX 1.0.

See also rtPrintf functions, rtContextGetPrintEnabled, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextGetPrintLaunchIndex

RTresult RTAPI rtContextSetRayGenerationProgram ( RTcontext  context,
unsigned int  entryPointIndex,
RTprogram  program 
)

Specifies the ray generation program for a given context entry point.

Description

rtContextSetRayGenerationProgram sets context's ray generation program at entry point entryPointIndex. RT_ERROR_INVALID_VALUE is returned if entryPointIndex is outside of the range [0, rtContextGetEntryPointCount -1].

Parameters
[in]contextThe context node to which the exception program will be added
[in]entryPointIndexThe entry point the program will be associated with
[in]programThe ray generation program

Return values

Relevant return values:

History

rtContextSetRayGenerationProgram was introduced in OptiX 1.0.

See also rtContextGetEntryPointCount, rtContextGetRayGenerationProgram

RTresult RTAPI rtContextSetRayTypeCount ( RTcontext  context,
unsigned int  rayTypeCount 
)

Sets the number of ray types for a given context.

Description

rtContextSetRayTypeCount Sets the number of ray types associated with the given context.

Parameters
[in]contextThe context node
[in]rayTypeCountThe number of ray types to be used

Return values

Relevant return values:

History

rtContextSetRayTypeCount was introduced in OptiX 1.0.

See also rtContextGetRayTypeCount

RTresult RTAPI rtContextSetStackSize ( RTcontext  context,
RTsize  bytes 
)

Set the stack size for a given context.

Description

rtContextSetStackSize sets the stack size for the given context to bytes bytes. Not supported with the RTX execution strategy. With RTX execution strategy rtContextSetMaxTraceDepth and rtContextSetMaxCallableProgramDepth should be used to control stack size. Returns RT_ERROR_INVALID_VALUE if context is not valid.

Parameters
[in]contextThe context node to be modified
[in]bytesThe desired stack size in bytes

Return values

Relevant return values:

History

rtContextSetStackSize was introduced in OptiX 1.0.

See also rtContextGetStackSize

RTresult RTAPI rtContextSetUsageReportCallback ( RTcontext  context,
RTusagereportcallback  callback,
int  verbosity,
void *  cbdata 
)

Set usage report callback function.

Description

rtContextSetUsageReportCallback sets an application-side callback function callback and a verbosity level verbosity.

RTusagereportcallback is defined as void (RTusagereportcallback)(int, const char, const char*, void*).

The provided callback will be invoked with the message's verbosity level as the first parameter. The second parameter is a descriptive tag string and the third parameter is the message itself. The fourth parameter is a pointer to user-defined data, which may be NULL. The descriptive tag will give a terse message category description (eg, 'SCENE STAT'). The messages will be unstructured and subject to change with subsequent releases. The verbosity argument specifies the granularity of these messages.

verbosity of 0 disables reporting. callback is ignored in this case.

verbosity of 1 enables error messages and important warnings. This verbosity level can be expected to be efficient and have no significant overhead.

verbosity of 2 additionally enables minor warnings, performance recommendations, and scene statistics at startup or recompilation granularity. This level may have a performance cost.

verbosity of 3 additionally enables informational messages and per-launch statistics and messages.

A NULL callback when verbosity is non-zero or a verbosity outside of [0, 3] will result in RT_ERROR_INVALID_VALUE return code.

Only one report callback function can be specified at any time.

Parameters
[in]contextThe context node to be modified
[in]callbackThe function to be called
[in]verbosityThe verbosity of report messages
[in]cbdataPointer to user-defined data that will be sent to the callback. Can be NULL.

Return values

Relevant return values:

History

rtContextSetUsageReportCallback was introduced in OptiX 5.0.

See also

RTresult RTAPI rtContextStopProgressive ( RTcontext  context)

Stops a Progressive Launch.

Description

If a progressive launch is currently in progress, calling rtContextStopProgressive terminates it. Otherwise, the call has no effect. If a launch is stopped using this function, no further subframes will arrive at the client, even if they have already been generated by the server and are currently in flight.

This call should only be used if the application must guarantee that frames generated by previous progressive launches won't be accessed. Do not call rtContextStopProgressive in the main rendering loop if the goal is only to change OptiX state (e.g. rtVariable values). The call is unnecessary in that case and will degrade performance.

Parameters
[in]contextThe context associated with the progressive launch

Return values

Relevant return values:

History

rtContextStopProgressive was introduced in OptiX 3.8.

See also rtContextLaunchProgressive2D

RTresult RTAPI rtContextValidate ( RTcontext  context)

Checks the given context for valid internal state.

Description

rtContextValidate checks the the given context and all of its associated OptiX objects for a valid state. These checks include tests for presence of necessary programs (e.g. an intersection program for a geometry node), invalid internal state such as NULL children in graph nodes, and presence of variables required by all specified programs. rtContextGetErrorString can be used to retrieve a description of a validation failure.

Parameters
[in]contextThe context to be validated

Return values

Relevant return values:

History

rtContextValidate was introduced in OptiX 1.0.

See also rtContextGetErrorString