Typedefs | Enumerations | Functions
Render device API

Render device querying and selection. More...

Typedefs

typedef void(* AtGPUCachePopulateCallback) (void *user_ptr, AtRenderStatus status, float fraction_done, const char *msg)
 GPU cache population report callback. More...
 

Enumerations

enum  AtDeviceType { AI_DEVICE_TYPE_CPU = 0, AI_DEVICE_TYPE_GPU = 1 }
 Device types. More...
 
enum  AtDeviceMemory { AI_DEVICE_MEMORY_TOTAL, AI_DEVICE_MEMORY_FREE, AI_DEVICE_MEMORY_USED }
 Queriable memory attributes. More...
 
enum  AtGPUCachePopulateMode { AI_GPU_CACHE_POPULATE_BLOCKING, AI_GPU_CACHE_POPULATE_NON_BLOCKING }
 

Functions

AI_API bool AiDeviceTypeIsSupported (AtDeviceType device_type, AtString &reason)
 Returns if a given device is supported on the current system. More...
 
AI_API int AiDeviceSelect (AtDeviceType device_type, const AtArray *device_ids)
 Select render device. More...
 
AI_API int AiDeviceAutoSelect ()
 Automatically select render device based on options. More...
 
AI_API AtDeviceType AiDeviceGetSelectedType ()
 Returns the currently selected render device type. More...
 
AI_API const AtArray * AiDeviceGetSelectedIds (AtDeviceType device_type)
 Returns the currently selected devices ids of a device type. More...
 
AI_API unsigned int AiDeviceGetCount (AtDeviceType device_type)
 Returns the number of available devices of a given type. More...
 
AI_API const AtArray * AiDeviceGetIds (AtDeviceType device_type)
 Returns the ids of available devices of a given type. More...
 
AI_API AtString AiDeviceGetName (AtDeviceType device_type, unsigned int device_id)
 Returns the name of a device. More...
 
AI_API unsigned int AiDeviceGetMemoryMB (AtDeviceType device_type, unsigned int device_id, AtDeviceMemory memory)
 Returns memory information of a device. More...
 
AI_API AtRenderErrorCode AiGPUCachePopulate (AtGPUCachePopulateMode mode=AI_GPU_CACHE_POPULATE_NON_BLOCKING, unsigned int num_proc=0, AtGPUCachePopulateCallback report_callback=NULL, void *user_ptr=NULL)
 Pre-populates the GPU program cache. More...
 
AI_API AtRenderStatus AiGPUCachePopulateStatus (float *fraction_done)
 Poll for the current status of the GPU cache population. More...
 
AI_API float AiGPUCachePopulateRemainingSeconds ()
 Estimate for how many more seconds remain for the GPU cache population.
 
AI_API void AiGPUCachePopulateTerminate ()
 Request immediate termination of the GPU cache population. More...
 
AI_API void AiGPUCacheSetDirectory (const char *dir_path)
 Set the directory where the OptiX cache will be stored. More...
 
AI_API AtString AiGPUCacheGetDirectory ()
 Get the directory specified via AiGPUCacheSetDirectory (or if not specified, the default) More...
 
bool getDeviceIdx (unsigned int device_id, unsigned int &idx)
 
AI_API AtRenderErrorCode AiGPUCachePopulateInternal (unsigned int perm_index)
 

Detailed Description

Render device querying and selection.

Typedef Documentation

typedef void(* AtGPUCachePopulateCallback) (void *user_ptr, AtRenderStatus status, float fraction_done, const char *msg)

GPU cache population report callback.

This callback provides:

  • user_ptr: the user data pointer passed to AiGPUCachePopulate
  • status: status code as returned from AiGPUCachePopulateStatus (AI_RENDER_STATUS_FINISHED will occur only once, on completion)
  • fraction_done: the progress as a fraction in [0.0, 1.0]
  • msg: a report string

Enumeration Type Documentation

Device types.

Enumerator
AI_DEVICE_TYPE_CPU 

Render using the CPU.

AI_DEVICE_TYPE_GPU 

Render using the GPU.

Queriable memory attributes.

Enumerator
AI_DEVICE_MEMORY_TOTAL 

Total memory on device.

AI_DEVICE_MEMORY_FREE 

Total free memory available to device.

AI_DEVICE_MEMORY_USED 

Total used memory.

Function Documentation

AI_API bool AiDeviceTypeIsSupported ( AtDeviceType  device_type,
AtString reason 
)

Returns if a given device is supported on the current system.

Verifies if a device is supported on the called system.

For example, this API can be used to indicate to if GPU rendering is supported on the given system.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
reasonReturns the reason if a device is unsupported.

true if the device is supported.

AI_API int AiDeviceSelect ( AtDeviceType  device_type,
const AtArray *  device_ids 
)

Select render device.

Selects which devices of type (CPU/GPU) can be used by Arnold.

This API needs an active session.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_idsValid ids depend on which type of device is used.
Returns
AI_SUCCESS if the device selection is successful AI_ERROR if device selection unsuccessful or there is no active session
AI_API int AiDeviceAutoSelect ( )

Automatically select render device based on options.

Selects render devices based on options.

It will filter devices on names and then available memory. This API requires an active session to work.

Returns
AI_SUCCESS if device selection is successful. AI_ERROR_UNAVAILABLE_DEVICE if no devices can be found. AI_ERROR if unsuccessful or there is no active session.
AI_API AtDeviceType AiDeviceGetSelectedType ( )

Returns the currently selected render device type.

Returns
Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
AI_API const AtArray * AiDeviceGetSelectedIds ( AtDeviceType  device_type)

Returns the currently selected devices ids of a device type.

Returns the currently selected device ids by type.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
Returns
Pointer to an array of unsigned int device ids
AI_API unsigned int AiDeviceGetCount ( AtDeviceType  device_type)

Returns the number of available devices of a given type.

Returns how many devices are available for device_type.

This function returns the number of available devices for the selected type, it should also be used to detect if the device_type is supported. AI_DEVICE_TYPE_CPU will always return one device available, regardless of the number of actual CPUs used.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
Returns
number of devices, or 0 if called before AiBegin().
AI_API const AtArray * AiDeviceGetIds ( AtDeviceType  device_type)

Returns the ids of available devices of a given type.

Returns an array of unsigned int which contains the ids of all supported devices of a specified render type.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
sizeSize fo returned array
Returns
A pointer to an array of unsigned int of size of the return value which contains the device ids of all supported devices of type device_type.
AI_API AtString AiDeviceGetName ( AtDeviceType  device_type,
unsigned int  device_id 
)

Returns the name of a device.

Queries device name.

If device type is AI_DEVICE_TYPE_CPU or for some reason the requested device is not found an empty string will be returned

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_idDevice id of device to be queried
Returns
Device name
AI_API unsigned int AiDeviceGetMemoryMB ( AtDeviceType  device_type,
unsigned int  device_id,
AtDeviceMemory  memory 
)

Returns memory information of a device.

Queries the memory available to a device in MB.

If the device type is AI_DEVICE_TYPE_CPU or for some reason the device is not found 0 will be returned.

Parameters
device_typeEither AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_idDevice id of device to be queried
memoryDevice memory to be queried AI_DEVICE_MEMORY_TOTAL - Total memory of the device AI_DEVICE_MEMORY_FREE - Total free memory of the device AI_DEVICE_MEMORY_USED - Total used memory of the device
Returns
Queried memory of device in MB
AI_API AtRenderErrorCode AiGPUCachePopulate ( AtGPUCachePopulateMode  mode,
unsigned int  num_proc,
AtGPUCachePopulateCallback  cb,
void *  cb_data 
)

Pre-populates the GPU program cache.

Pre-populates the GPU program cache, which is likely to make subsequent GPU renders launch faster.

Plugins may want to automatically trigger this either at install or startup time. Users may want to manually re-run this pre-population when the program cache becomes stale due to changing the GPU hardware configuration or driver updates.

Parameters
modeRequest either blocking or non-blocking operation. If blocking, the cache population runs to completion before returning. If non-blocking, this function returns immediately and its progress can be monitored via the callback, or terminated via AiGPUCachePopulateTerminate.
num_procThe number of independent kick processes to run during the population. More processes may lead to faster progress, but will also consume more system resources. The default value 0 chooses a sensible value internally.
report_callbackOptional callback with a progress report
user_ptrOptional user data pointer for the callback
Returns
AI_SUCCESS if the cache population was initiated successfully.
AI_API AtRenderStatus AiGPUCachePopulateStatus ( float *  fraction_done)

Poll for the current status of the GPU cache population.

Poll for the current status of the GPU cache population (currently just a progress fraction and an overall status code).

The fraction_done value will be <1.0 if the population is still running since the last AiGPUCachePopulate call. If fraction_done is 1.0, the cache population has either not been run yet, or has finished since the last AiGPUCachePopulate call.

The returned status code is:

  • AI_RENDER_STATUS_NOT_STARTED if the cache population was never triggered, or was just triggered but not yet begun
  • AI_RENDER_STATUS_RENDERING if the AiGPUCachePopulate call is currently running
  • AI_RENDER_STATUS_FINISHED if the cache population has finished since the last AiGPUCachePopulate call
AI_API void AiGPUCachePopulateTerminate ( )

Request immediate termination of the GPU cache population.

Request immediate termination of the GPU cache population, if it is running.

This blocks until the existing population process terminates.

AI_API void AiGPUCacheSetDirectory ( const char *  dir_path)

Set the directory where the OptiX cache will be stored.

Set the directory where the OptiX cache database will be stored during GPU renders (this directory is created if it doesn't already exist).

If not called, this will be set to the default directory:

  • /var/tmp/OptixCache_<username> on Linux
  • LOCALAPPDATA% on Windows Note that the Arnold cache data is stored in the Arnold/ sub-directory.
AI_API AtString AiGPUCacheGetDirectory ( )

Get the directory specified via AiGPUCacheSetDirectory (or if not specified, the default)

Get the directory specified via AiGPUCacheSetDirectory (or if not specified, the default).

Note that the Arnold-specific caches are in the Arnold/ sub-directory.


© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com