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 (AtRenderSession *render_session, AtDeviceType device_type, const AtArray *device_ids)
	Select render device. More...
AI_API int	AiDeviceAutoSelect (AtRenderSession *render_session)
	Automatically select render device based on options. More...
AI_API AtDeviceType	AiDeviceGetSelectedType (const AtRenderSession *render_session)
	Returns the currently selected render device type. More...
AI_API const AtArray *	AiDeviceGetSelectedIds (const AtRenderSession *render_session, 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 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)

Detailed Description

Render device querying and selection.

Typedef Documentation

AtGPUCachePopulateCallback

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

AtDeviceType

enum AtDeviceType

Device types.

Enumerator
AI_DEVICE_TYPE_CPU	Render using the CPU.
AI_DEVICE_TYPE_GPU	Render using the GPU.

AtDeviceMemory

enum AtDeviceMemory

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

AiDeviceTypeIsSupported()

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_type	Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
reason	Returns the reason if a device is unsupported.

\retrun true if the device is supported.

AiDeviceSelect()

AI_API int AiDeviceSelect	(	AtRenderSession *	render_session,
		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_type	Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_ids	Valid 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

AiDeviceAutoSelect()

AI_API int AiDeviceAutoSelect

(

AtRenderSession *

render_session

)

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.

AiDeviceGetSelectedType()

AI_API AtDeviceType AiDeviceGetSelectedType

(

const AtRenderSession *

render_session

)

Returns the currently selected render device type.

Returns

Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU

AiDeviceGetSelectedIds()

AI_API const AtArray * AiDeviceGetSelectedIds	(	const AtRenderSession *	render_session,
		AtDeviceType	device_type
	)

Returns the currently selected devices ids of a device type.

Returns the currently selected device ids by type.

Parameters

device_type

Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU

Returns

Pointer to an array of unsigned int device ids

AiDeviceGetCount()

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_type

Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU

Returns

number of devices, or 0 if called before AiBegin().

AiDeviceGetIds()

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_type	Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
size	Size 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.

AiDeviceGetName()

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_type	Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_id	Device id of device to be queried

Returns

Device name

AiDeviceGetMemoryMB()

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_type	Either AI_DEVICE_TYPE_CPU or AI_DEVICE_TYPE_GPU
device_id	Device id of device to be queried
memory	Device 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

AiGPUCacheSetDirectory()

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%\NVIDIA\OptixCache on Windows Note that the Arnold cache data is stored in the Arnold/ sub-directory.

AiGPUCacheGetDirectory()

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.