NVIDIA OptiX 7.1 API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Device context


OptixResult optixDeviceContextCreate (CUcontext fromContext, const OptixDeviceContextOptions *options, OptixDeviceContext *context)
OptixResult optixDeviceContextDestroy (OptixDeviceContext context)
OptixResult optixDeviceContextGetProperty (OptixDeviceContext context, OptixDeviceProperty property, void *value, size_t sizeInBytes)
OptixResult optixDeviceContextSetLogCallback (OptixDeviceContext context, OptixLogCallback callbackFunction, void *callbackData, unsigned int callbackLevel)
OptixResult optixDeviceContextSetCacheEnabled (OptixDeviceContext context, int enabled)
OptixResult optixDeviceContextSetCacheLocation (OptixDeviceContext context, const char *location)
OptixResult optixDeviceContextSetCacheDatabaseSizes (OptixDeviceContext context, size_t lowWaterMark, size_t highWaterMark)
OptixResult optixDeviceContextGetCacheEnabled (OptixDeviceContext context, int *enabled)
OptixResult optixDeviceContextGetCacheLocation (OptixDeviceContext context, char *location, size_t locationSize)
OptixResult optixDeviceContextGetCacheDatabaseSizes (OptixDeviceContext context, size_t *lowWaterMark, size_t *highWaterMark)

Detailed Description

Function Documentation

OptixResult optixDeviceContextCreate ( CUcontext  fromContext,
const OptixDeviceContextOptions options,
OptixDeviceContext context 

Create a device context associated with the CUDA context specified with 'fromContext'.

If zero is specified for 'fromContext', OptiX will use the current CUDA context. The CUDA context should be initialized before calling optixDeviceContextCreate.

  • OPTIX_ERROR_CUDA_NOT_INITIALIZED If using zero for 'fromContext' and CUDA has not been initialized yet on the calling thread.
  • OPTIX_ERROR_CUDA_ERROR CUDA operation failed.
  • OPTIX_ERROR_HOST_OUT_OF_MEMORY Heap allocation failed.
OptixResult optixDeviceContextDestroy ( OptixDeviceContext  context)

Destroys all CPU and GPU state associated with the device.

It will attempt to block on CUDA streams that have launch work outstanding.

Any API objects, such as OptixModule and OptixPipeline, not already destroyed will be destroyed.

Thread safety: A device context must not be destroyed while it is still in use by concurrent API calls in other threads.

OptixResult optixDeviceContextGetCacheDatabaseSizes ( OptixDeviceContext  context,
size_t *  lowWaterMark,
size_t *  highWaterMark 

Returns the low and high water marks for disk cache garbage collection.

[in]contextthe device context
[out]lowWaterMarkthe low water mark
[out]highWaterMarkthe high water mark
OptixResult optixDeviceContextGetCacheEnabled ( OptixDeviceContext  context,
int *  enabled 

Indicates whether the disk cache is enabled or disabled.

[in]contextthe device context
[out]enabled1 if enabled, 0 if disabled
OptixResult optixDeviceContextGetCacheLocation ( OptixDeviceContext  context,
char *  location,
size_t  locationSize 

Returns the location of the disk cache.

[in]contextthe device context
[out]locationdirectory of disk cache, null terminated if locationSize > 0
OptixResult optixDeviceContextGetProperty ( OptixDeviceContext  context,
OptixDeviceProperty  property,
void *  value,
size_t  sizeInBytes 

Query properties of a device context.

[in]contextthe device context to query the property for
[in]propertythe property to query
[out]valuepointer to the returned
[in]sizeInBytessize of output
OptixResult optixDeviceContextSetCacheDatabaseSizes ( OptixDeviceContext  context,
size_t  lowWaterMark,
size_t  highWaterMark 

Sets the low and high water marks for disk cache garbage collection.

Garbage collection is triggered when a new entry is written to the cache and the current cache data size plus the size of the cache entry that is about to be inserted exceeds the high water mark. Garbage collection proceeds until the size reaches the low water mark. Garbage collection will always free enough space to insert the new entry without exceeding the low water mark. Setting either limit to zero will disable garbage collection. An error will be returned if both limits are non-zero and the high water mark is smaller than the low water mark.

Note that garbage collection is performed only on writes to the disk cache. No garbage collection is triggered on disk cache initialization or immediately when calling this function, but on subsequent inserting of data into the database.

If the size of a compiled module exceeds the value configured for the high water mark and garbage collection is enabled, the module will not be added to the cache and a warning will be added to the log.

[in]contextthe device context
[in]lowWaterMarkthe low water mark
[in]highWaterMarkthe high water mark
OptixResult optixDeviceContextSetCacheEnabled ( OptixDeviceContext  context,
int  enabled 

Enables or disables the disk cache.

If caching was previously disabled, enabling it will attempt to initialize the disk cache database using the currently configured cache location. An error will be returned if initialization fails.

Note that no in-memory cache is used, so no caching behavior will be observed if the disk cache is disabled.

[in]contextthe device context
[in]enabled1 to enabled, 0 to disable
OptixResult optixDeviceContextSetCacheLocation ( OptixDeviceContext  context,
const char *  location 

Sets the location of the disk cache.

The location is specified by a directory. This directory should not be used for other purposes and will be created if it does not exist. An error will be returned if is not possible to create the disk cache at the specified location for any reason (e.g., the path is invalid or the directory is not writable). Caching will be disabled if the disk cache cannot be initialized in the new location. If caching is disabled, no error will be returned until caching is enabled. If the disk cache is located on a network file share, behavior is undefined.

The location of the disk cache can be overridden with the environment variable OPTIX_CACHE_PATH. The environment variable takes precedence over this setting.

The default location depends on the operating system:

  • Windows: LOCALAPPDATA%\NVIDIA\OptixCache
  • Linux: /var/tmp/OptixCache_<username> (or /tmp/OptixCache_<username> if the first choice is not usable), the underscore and username suffix are omitted if the username cannot be obtained
  • MacOS X: /Library/Application Support/NVIDIA/OptixCache
[in]contextthe device context
[in]locationdirectory of disk cache
OptixResult optixDeviceContextSetLogCallback ( OptixDeviceContext  context,
OptixLogCallback  callbackFunction,
void *  callbackData,
unsigned int  callbackLevel 

Sets the current log callback method.

See OptixLogCallback for more details.

Thread safety: It is guaranteed that the callback itself (callbackFunction and callbackData) are updated atomically. It is not guaranteed that the callback itself (callbackFunction and callbackData) and the callbackLevel are updated atomically. It is unspecified when concurrent API calls using the same context start to make use of the new callback method.

[in]contextthe device context
[in]callbackFunctionthe callback function to call
[in]callbackDatapointer to data passed to callback function while invoking it
[in]callbackLevelcallback level