Render process operation and querying. More...

Data Structures
struct	AtRenderUpdateInfo
	Additional useful information about the render, received in the render callback. More...

Typedefs
typedef AtRenderStatus(*	AtRenderUpdateCallback) (void private_data, AtRenderUpdateType update_type, const AtRenderUpdateInfo update_info)
	Render update callback. More...

Enumerations
enum	AtRenderMode { AI_RENDER_MODE_CAMERA , AI_RENDER_MODE_FREE }
	Render modes. More...

enum	AtRenderErrorCode { AI_SUCCESS , AI_ABORT , AI_ERROR_NO_CAMERA , AI_ERROR_BAD_CAMERA , AI_ERROR_VALIDATION , AI_ERROR_RENDER_REGION , AI_INTERRUPT , AI_ERROR_NO_OUTPUTS , AI_ERROR_UNAVAILABLE_DEVICE , AI_ERROR }
	Render error codes. More...

enum	AtSessionMode { AI_SESSION_BATCH , AI_SESSION_INTERACTIVE }
	Session mode. More...

enum	AtDisplayOutput { AI_DISPLAY_OUTPUT_NONE , AI_DISPLAY_OUTPUT_INTERACTIVE , AI_DISPLAY_OUTPUT_PARTIAL_INTERACTIVE , AI_DISPLAY_OUTPUT_ALL }
	Outputs ready for display. More...

enum	AtRenderStatus { AI_RENDER_STATUS_NOT_STARTED , AI_RENDER_STATUS_PAUSED , AI_RENDER_STATUS_RESTARTING , AI_RENDER_STATUS_RENDERING , AI_RENDER_STATUS_FINISHED , AI_RENDER_STATUS_FAILED }
	Status of the current render. More...

enum	AtRenderUpdateType { AI_RENDER_UPDATE_INTERRUPT , AI_RENDER_UPDATE_BEFORE_PASS , AI_RENDER_UPDATE_DURING_PASS , AI_RENDER_UPDATE_AFTER_PASS , AI_RENDER_UPDATE_FINISHED , AI_RENDER_UPDATE_ERROR , AI_RENDER_UPDATE_IMAGERS }
	Reason for invoking the render update callback. More...

enum	AtSystemHandlerMask { AI_SYSTEM_HANDLER_NONE = 0x0 , AI_SYSTEM_HANDLER_ALL = 0xFF }
	System handler mask. More...

Functions
AI_API void	AiBegin (AtSessionMode default_rs_mode=AI_SESSION_BATCH)
	Marks the beginning of a block which uses the Arnold rendering interface API. More...

AI_API void	AiEnd ()
	Marks the end of a block which uses the Arnold rendering interface API. More...

AI_API bool	AiArnoldIsActive ()
	Check whether the Arnold API is active (AiBegin has been called) or not. More...

AI_API void	AiSetSystemHandlers (AtSystemHandlerMask mask)
	Sets active handlers used by Arnold, such as the crash handler. More...

AI_API AtRenderSession *	AiRenderSession (AtUniverse *universe, AtSessionMode mode=AI_SESSION_BATCH)
	Create a new render session. More...

AI_API AtUniverse *	AiRenderSessionGetUniverse (const AtRenderSession *render_session)
	Get the universe used by a given render session. More...

AI_API AI_PURE const AtNode *	AiRenderSessionGetOptions (const AtRenderSession *render_session)
	Get the render options node used by a given render session. More...

AI_API void	AiRenderSessionDestroy (AtRenderSession *render_session)
	Destroy a render session and release any allocated resources. More...

AI_API AtSessionMode	AiGetSessionMode (const AtRenderSession *render_session)
	Returns the current render session's mode. More...

AI_API void	AiRenderAddInteractiveOutput (AtRenderSession *render_session, uint32_t output_index)
	Add the output to be displayed during fast interactive rendering. More...

AI_API bool	AiRenderIsInteractiveOutput (AtRenderSession *render_session, uint32_t output_index)
	Get whether the output is displayed during fast interactive rendering. More...

AI_API bool	AiRenderRemoveInteractiveOutput (AtRenderSession *render_session, uint32_t output_index)
	Remove the output so it is not displayed during fast interactive rendering. More...

AI_API void	AiRenderRemoveAllInteractiveOutputs (AtRenderSession *render_session)
	Remove the output so it is not displayed during fast interactive rendering. More...

AI_API bool	AiRenderSetHintBool (AtRenderSession *render_session, AtString hint, bool value)
	Set a render hint. More...

AI_API bool	AiRenderSetHintInt (AtRenderSession *render_session, AtString hint, int32_t value)
	Set a render hint. More...

AI_API bool	AiRenderSetHintFlt (AtRenderSession *render_session, AtString hint, float value)
	Set a render hint. More...

AI_API bool	AiRenderSetHintStr (AtRenderSession *render_session, AtString hint, AtString value)
	Set a render hint. More...

AI_API bool	AiRenderSetHintArray (AtRenderSession render_session, AtString hint, AtArray value)
	Set a render hint. More...

AI_API bool	AiRenderGetHintBool (const AtRenderSession *render_session, AtString hint, bool &value)
	Get a render hint. More...

AI_API bool	AiRenderGetHintInt (const AtRenderSession *render_session, AtString hint, int32_t &value)
	Get a render hint. More...

AI_API bool	AiRenderGetHintFlt (const AtRenderSession *render_session, AtString hint, float &value)
	Get a render hint. More...

AI_API bool	AiRenderGetHintStr (const AtRenderSession *render_session, AtString hint, AtString &value)
	Get a render hint. More...

AI_API bool	AiRenderGetHintArray (const AtRenderSession render_session, AtString hint, const AtArray &value)
	Get a render hint. More...

AI_API AtRenderErrorCode	AiRenderBegin (AtRenderSession render_session, AtRenderMode mode=AI_RENDER_MODE_CAMERA, AtRenderUpdateCallback update_callback=NULL, void callback_private_data=NULL)
	Start a render asynchronously. More...

AI_API AtRenderErrorCode	AiRenderEnd (AtRenderSession *render_session)
	Finalize and clean up after beginning a render. More...

AI_API AtRenderStatus	AiRenderGetStatus (const AtRenderSession *render_session)
	Get the current status of a render session. More...

AI_API void	AiRenderInterrupt (AtRenderSession *render_session, AtBlockingCall blocking=AI_NON_BLOCKING)
	Stop rendering on a render session quickly and go to a paused state. More...

AI_API void	AiRenderAbort (AtRenderSession *render_session, AtBlockingCall blocking=AI_NON_BLOCKING)
	Stop rendering on a render session as quickly as possible. More...

AI_API void	AiRenderResume (AtRenderSession *render_session)
	Resume a render session after it was paused. More...

AI_API void	AiRenderRestart (AtRenderSession *render_session)
	Restart a render session after it was paused. More...

AI_API bool	AiRenderIsAnyActive ()
	Returns true if any of the existing universes is being rendered. More...

AI_API AtRenderErrorCode	AiRender (AtRenderSession *render_session, AtRenderMode mode=AI_RENDER_MODE_CAMERA)
	Prepares a render and wait synchronously until it is finished before returning. More...

Variables
AtRenderSession *	AtRenderUpdateInfo::render_session
	Pointer to the render session that is being executed (in case the callback is used for several render sessions)

AtDisplayOutput	AtRenderUpdateInfo::outputs_to_display
	Whether the outputs to be shown are none, partial, interactive, or all outputs

uint32_t	AtRenderUpdateInfo::pass_index
	The pass number we're on out of the total number of passes, useful for indicating progress to the user

uint32_t	AtRenderUpdateInfo::total_passes
	The total passes we expect to render, assuming no interruptions or errors

int32_t	AtRenderUpdateInfo::current_AA_samples
	The actual AA_samples for the current pass (options.AA_samples remains the original value)

int32_t	AtRenderUpdateInfo::current_AA_samples_max
	The actual AA_samples_max for the current pass (options.AA_samples_max remains the original value)

int32_t	AtRenderUpdateInfo::current_GI_diffuse_samples
	The actual GI_diffuse_samples for the current pass (options.GI_diffuse_samples remains the original value)

int32_t	AtRenderUpdateInfo::current_GI_specular_samples
	The actual GI_specular_samples for the current pass (options.GI_specular_samples remains the original value)

int32_t	AtRenderUpdateInfo::current_GI_transmission_samples
	The actual GI_transmission_samples for the current pass (options.GI_transmission_samples remains the original value)

int32_t	AtRenderUpdateInfo::current_GI_sss_samples
	The actual GI_sss_samples for the current pass (options.GI_sss_samples remains the original value)

int32_t	AtRenderUpdateInfo::current_GI_volume_samples
	The actual GI_volume_samples for the current pass (options.GI_volume_samples remains the original value)

Detailed Description

Render process operation and querying.

Typedef Documentation

◆ AtRenderUpdateCallback

typedef AtRenderStatus(* AtRenderUpdateCallback) (void *private_data, AtRenderUpdateType update_type, const AtRenderUpdateInfo *update_info)

Render update callback.

This is called in the following circumstances:

A render pass is about to start: update_type is AI_RENDER_UPDATE_BEFORE_PASS, and update_info->outputs_to_display will not be AI_DISPLAY_OUTPUT_NONE. This is a chance to prepare for the outputs that will be displayed during this render pass. It is also safe to change the scene at this point.
The render is ongoing and some number of buckets are finished: status is update_type is AI_RENDER_UPDATE_DURING_PASS, and update_info->outputs_to_display is AI_DISPLAY_OUTPUT_PARTIAL_INTERACTIVE or AI_DISPLAY_OUTPUT_ALL. It is NOT safe to change the scene at this point. Note that the callback is not currently invoked with this update type, but may be in a future release.
A render pass is done: update_type is AI_RENDER_UPDATE_AFTER_PASS, and update_info->outputs_to_display will not be AI_DISPLAY_OUTPUT_NONE. It is safe to change the scene at this point.
Rendering is completed: update_type is AI_RENDER_UPDATE_FINISHED, and update_info->outputs_to_display will not be AI_DISPLAY_OUTPUT_NONE. It is safe to change the scene at this point.
Rendering was interrupted: update_type is AI_RENDER_UPDATE_INTERRUPT, and update_info->outputs_to_display is AI_DISPLAY_OUTPUT_NONE if the interrupt happened very early in the pass, otherwise it will be AI_DISPLAY_OUTPUT_PARTIAL_INTERACTIVE. It is safe to change the scene at this point.
Rendering has failed: update_type is AI_RENDER_UPDATE_ERROR, and update_info->outputs_to_display is AI_DISPLAY_OUTPUT_NONE. The callback should return AI_RENDER_STATUS_FAILED and host code call AiRenderEnd() to get the error code. It is NOT safe to change the scene at this point.

If you need the new render status within the callback, use the following table which provides the equivalent status from the value of update_type:

Render status and render update type mapping
AtRenderUpdateType	AtRenderStatus
AI_RENDER_UPDATE_INTERRUPT	AI_RENDER_STATUS_PAUSED
AI_RENDER_UPDATE_BEFORE_PASS	AI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_DURING_PASS	AI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_AFTER_PASS	AI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_FINISHED	AI_RENDER_STATUS_FINISHED
AI_RENDER_UPDATE_ERROR	AI_RENDER_STATUS_FAILED

The callback returns the next status desired, but should never return AI_RENDER_STATUS_NOT_STARTED as that is reserved.

If you change the scene during the callback, it is recommended that you return AI_RENDER_STATUS_RESTARTING to go to the beginning of the pass sequence. When the scene doesn't change you probably want to return the status as listed above in the render_update_type_to_status table.

Note: It is optional to have a render update callback, but is quite helpful especially for interactive and progressive rendering (IPR). Aside from the information in AtRenderUpdateInfo all of the controlling of the render can be done without a callback, usually by polling AiRenderGetStatus() for state changes.

Parameters

private_data	Pointer passed to AiRenderBegin(), used for whatever the callback needs
update_type	Indicates when the callback is being called
update_info	Extra pass, sample, and output information

Returns: The next AtRenderStatus desired

Enumeration Type Documentation

◆ AtRenderMode

enum AtRenderMode

Render modes.

Enumerator
AI_RENDER_MODE_CAMERA	Render from a camera.
AI_RENDER_MODE_FREE	Process arbitrary ray-tracing requests, acting as a "ray server".

◆ AtRenderErrorCode

enum AtRenderErrorCode

Render error codes.

Enumerator
AI_SUCCESS	no error
AI_ABORT	render aborted
AI_ERROR_NO_CAMERA	camera not defined
AI_ERROR_BAD_CAMERA	bad camera data
AI_ERROR_VALIDATION	usage not validated
AI_ERROR_RENDER_REGION	invalid render region
AI_INTERRUPT	render interrupted by user
AI_ERROR_NO_OUTPUTS	no rendering outputs
AI_ERROR_UNAVAILABLE_DEVICE	Cannot create GPU context
AI_ERROR	generic error

◆ AtSessionMode

enum AtSessionMode

Session mode.

The session mode indicates to the renderer what the purpose of the session is. When it is intended to set up the scene fully, render, and afterwards end the session without modifying or reading parameters from existing nodes, use AI_SESSION_BATCH mode. If instead the nodes will be modified after render or have their parameters accessed for some other reason, and then another render invoked, use AI_SESSION_INTERACTIVE.

Enumerator
AI_SESSION_BATCH	batch mode, extra (possibly destructive) optimizations allowed
AI_SESSION_INTERACTIVE	interactive mode, can read/write nodes after rendering

◆ AtDisplayOutput

enum AtDisplayOutput

Outputs ready for display.

This indicates which outputs are ready for display during interactive rendering. For faster interactive rendering, Arnold may only provide pixel data on the main interactive output to improve responsiveness for the user. If the render gets to keep going, then Arnold will switch over to providing data for all AOVs/outputs.

Enumerator
AI_DISPLAY_OUTPUT_NONE	no updates ready; check render status or error code
AI_DISPLAY_OUTPUT_INTERACTIVE	interactive output updated fully, display on screen
AI_DISPLAY_OUTPUT_PARTIAL_INTERACTIVE	interactive output updated but not the whole image; put on screen anyway
AI_DISPLAY_OUTPUT_ALL	all outputs are getting updated, any output can be displayed

◆ AtRenderStatus

enum AtRenderStatus

Status of the current render.

Enumerator
AI_RENDER_STATUS_NOT_STARTED	Before AiRenderBegin(), or after AiRenderEnd()
AI_RENDER_STATUS_PAUSED	Update callback paused the render or AiRenderInterrupt() called
AI_RENDER_STATUS_RESTARTING	Update callback is restarting the render
AI_RENDER_STATUS_RENDERING	Currently actively rendering passes
AI_RENDER_STATUS_FINISHED	Render done, but AiRenderEnd() not called yet
AI_RENDER_STATUS_FAILED	Render failed, AiRenderEnd() will return the actual error code (AtRenderErrorCode)

◆ AtRenderUpdateType

enum AtRenderUpdateType

Reason for invoking the render update callback.

Enumerator
AI_RENDER_UPDATE_INTERRUPT	Callback invoked after render is interrupted and paused, can change the scene.
AI_RENDER_UPDATE_BEFORE_PASS	Callback invoked just before render pass is to begin, can change the scene
AI_RENDER_UPDATE_DURING_PASS	Callback invoked during render pass after some pixel data is ready; not currently invoked, but may be in a future release.
AI_RENDER_UPDATE_AFTER_PASS	Callback invoked after a non-final render pass is done, can change the scene
AI_RENDER_UPDATE_FINISHED	Callback invoked after the final render pass is done, can change the scene
AI_RENDER_UPDATE_ERROR	Callback invoked when an error or abort occurs, and the render has failed
AI_RENDER_UPDATE_IMAGERS	Callback invoked for an imager update

◆ AtSystemHandlerMask

enum AtSystemHandlerMask

System handler mask.

Enumerator
AI_SYSTEM_HANDLER_NONE	no handlers
AI_SYSTEM_HANDLER_ALL	all handlers

Function Documentation

◆ AiBegin()

AI_API void AiBegin ( AtSessionMode default_rs_mode )

Marks the beginning of a block which uses the Arnold rendering interface API.

This function initializes the Arnold rendering subsystem and "enables" the Arnold API. It must be paired with a matching AiEnd() call when all work with the Arnold API is completed.

This will also create a default universe and render session, that might be used if needed. Any other universe or render session will have to be created and destroyed explicitly.

For information about the render modes see AtSessionMode

Note: Parameter only applies to the default render session, not to the additional render sessions that get created via AiRenderSession()

Parameters

mode	Selects batch or interactive mode for the default render session

◆ AiEnd()

AI_API void AiEnd ( )

Marks the end of a block which uses the Arnold rendering interface API.

It must be coupled with a matching AiBegin() call. This function shuts down the Arnold rendering subsystem.

This will force end all active render sessions and also destroy them. All memory pools are free'd and the scene is destroyed. API calls should not be made after a call to AiEnd().

◆ AiArnoldIsActive()

AI_API bool AiArnoldIsActive ( )

Check whether the Arnold API is active (AiBegin has been called) or not.

This function is typically used to detect whether we are inside an AiBegin() / AiEnd() block.

Returns: true if Arnold is active. This can only be false if called outside of an AiBegin() / AiEnd() block.

◆ AiSetSystemHandlers()

AI_API void AiSetSystemHandlers ( AtSystemHandlerMask mask )

Sets active handlers used by Arnold, such as the crash handler.

This function can be called anytime.

◆ AiRenderSession()

AI_API AtRenderSession * AiRenderSession	(	AtUniverse *	universe,
		AtSessionMode	mode
	)

Create a new render session.

The created render session will be tied to the given universe.

NOTE: passing the default universe or NULL will just return the default render session, instead of creating a new one

Parameters

universe	Universe to be used by the new render session (NULL for default universe)
mode	Selects batch or interactive mode for the new render session

Returns: Pointer to the render session created (NULL if none was created)

◆ AiRenderSessionGetUniverse()

AI_API AtUniverse * AiRenderSessionGetUniverse ( const AtRenderSession * render_session )

Get the universe used by a given render session.

Parameters

render_session Pointer to a render session (NULL for default render session)

Returns: Pointer to the universe used by the given render session

◆ AiRenderSessionGetOptions()

AI_API AI_PURE const AtNode * AiRenderSessionGetOptions ( const AtRenderSession * render_session )

Get the render options node used by a given render session.

This render options node holds a separate set of options, initialized from the universe options but partially modified for render specific requirements. This render options are read-only. Any modification should be made through the universe options.

The differences with the universe copy of the options are mostly related to invalid values that are sanitized for rendering and temporary changes to sample values made during interactive render.

Parameters

render_session Pointer to a render session (NULL for default render session)

Returns: Pointer to the render options node (different from universe options node)

◆ AiRenderSessionDestroy()

AI_API void AiRenderSessionDestroy ( AtRenderSession * render_session )

Destroy a render session and release any allocated resources.

Note: Trying to destroy the default render session, or passing a NULL pointer, will do nothing. The default render session is internally managed and is destroyed with AiEnd()

Parameters

render_session Pointer to the render session to destroy

◆ AiGetSessionMode()

AI_API AtSessionMode AiGetSessionMode ( const AtRenderSession * render_session )

Returns the current render session's mode.

The session mode indicates whether node changes after render or .ass file writing are expected or not.

For information about the render modes see AtSessionMode

Parameters

render_session Pointer to the render session this function call applies to (NULL for default render session)

Returns: the current render session mode.

◆ AiRenderAddInteractiveOutput()

AI_API void AiRenderAddInteractiveOutput	(	AtRenderSession *	render_session,
		uint32_t	output_index
	)

Add the output to be displayed during fast interactive rendering.

This adds the index into options.outputs for the output that will be updated during interactive rendering when the scene is changing. After interactive rendering is allowed to run for a while, all outputs will start being updated instead of just those added for interactive rendering.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
output_index	The index into options.outputs for the output to display

◆ AiRenderIsInteractiveOutput()

AI_API bool AiRenderIsInteractiveOutput	(	AtRenderSession *	render_session,
		uint32_t	output_index
	)

Get whether the output is displayed during fast interactive rendering.

This checks the index into options.outputs whether the output will be updated during interactive rendering when the scene is changing. After interactive rendering is allowed to run for a while, all outputs will start being updated instead of just the interactive outputs.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
output_index	The index into options.outputs to check

Returns: whether the index into options.outputs will be displayed interactively

◆ AiRenderRemoveInteractiveOutput()

AI_API bool AiRenderRemoveInteractiveOutput	(	AtRenderSession *	render_session,
		uint32_t	output_index
	)

Remove the output so it is not displayed during fast interactive rendering.

This removes the index into options.outputs for the output so it will not be updated during interactive rendering when the scene is changing. After interactive rendering is allowed to run for a while, all outputs will start being updated instead of just those added for interactive rendering.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
output_index	The index into options.outputs for the output to not display

Returns: whether the output was previously added, and was successfully removed

◆ AiRenderRemoveAllInteractiveOutputs()

AI_API void AiRenderRemoveAllInteractiveOutputs ( AtRenderSession * render_session )

Remove the output so it is not displayed during fast interactive rendering.

This removes the index into options.outputs for the output so it will not be updated during interactive rendering when the scene is changing. After interactive rendering is allowed to run for a while, all outputs will start being updated instead of just those added for interactive rendering.

Parameters

render_session Pointer to the render session this function call applies to (NULL for default render session)

◆ AiRenderSetHintBool()

AI_API bool AiRenderSetHintBool	(	AtRenderSession *	render_session,
		AtString	hint,
		bool	value
	)

Set a render hint.

If a hint exists of this type and name, set it. Currently allowed hints of type bool:

"progressive", defaults to true for AI_SESSION_INTERACTIVE, false otherwise
"progressive_show_all_outputs", default false; if true show all outputs rather than just main interactive output for AI_SESSION_INTERACTIVE

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value to be set if the hint exists

Returns: whether the hint exists.

◆ AiRenderSetHintInt()

AI_API bool AiRenderSetHintInt	(	AtRenderSession *	render_session,
		AtString	hint,
		int32_t	value
	)

Set a render hint.

If a hint exists of this type and name, set it. Currently allowed hints of type int:

"progressive_min_AA_samples", default -4
"progressive_max_pass_seconds", default 0, meaning unlimited seconds; this is the longest a negative progressive AA pass can take before it starts skipping straight to AA 1 or final AA samples, whichever is lower

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be set if the hint exists

Returns: whether the hint exists.

◆ AiRenderSetHintFlt()

AI_API bool AiRenderSetHintFlt	(	AtRenderSession *	render_session,
		AtString	hint,
		float	value
	)

Set a render hint.

If a hint exists of this type and name, set it. Currently allowed hints of type float are:

"interactive_target_fps", default 20. Interactive FPS faster than this will cause Arnold to use higher quality sample settings while interacting with the scene.
"interactive_target_fps_min", default 5. FPS slower than this will cause Arnold to use lower quality sample settings. Recommended to be less than interactive_target_fps/4
"interactive_fps_min", default 2. FPS below this will cause arnold to interrupt the render and display a partial image once this FPS is hit.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be set if the hint exists

Returns: whether the hint exists.

◆ AiRenderSetHintStr()

AI_API bool AiRenderSetHintStr	(	AtRenderSession *	render_session,
		AtString	hint,
		AtString	value
	)

Set a render hint.

If a hint exists of this type and name, set it. There are currently no render hints of type string.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be set if the hint exists

Returns: whether the hint exists.

◆ AiRenderSetHintArray()

AI_API bool AiRenderSetHintArray	(	AtRenderSession *	render_session,
		AtString	hint,
		AtArray *	value
	)

Set a render hint.

If a hint exists of this type and name, set it. There are currently no render hints of type array.

Note: If the function succeeds the api takes ownership of the array. Do not call AiArrayDestroy.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be set if the hint exists

Returns: whether the hint exists.

◆ AiRenderGetHintBool()

AI_API bool AiRenderGetHintBool	(	const AtRenderSession *	render_session,
		AtString	hint,
		bool &	value
	)

Get a render hint.

If a hint exists of this type and name, return it. Currently allowed hints of type bool:

"progressive", default true for AI_SESSION_INTERACTIVE, false otherwise
"progressive_show_all_outputs", default false; if true show all outputs rather than just main interactive output for AI_SESSION_INTERACTIVE

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be written to this argument if the hint exists

Returns: whether the hint exists.

◆ AiRenderGetHintInt()

AI_API bool AiRenderGetHintInt	(	const AtRenderSession *	render_session,
		AtString	hint,
		int32_t &	value
	)

Get a render hint.

If a hint exists of this type and name, return it. Currently allowed hints of type int are:

"progressive_min_AA_samples", default -4
"progressive_max_pass_seconds", default 0, meaning unlimited seconds; this is the longest a negative progressive AA pass can take before it starts skipping straight to AA 1 or final AA samples, whichever is lower

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be written to this argument if the hint exists

Returns: whether the hint exists.

◆ AiRenderGetHintFlt()

AI_API bool AiRenderGetHintFlt	(	const AtRenderSession *	render_session,
		AtString	hint,
		float &	value
	)

Get a render hint.

If a hint exists of this type and name, return it. See AiRenderGetHintFlt for currently allowed float hints.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be written to this argument if the hint exists

Returns: whether the hint exists.

◆ AiRenderGetHintStr()

AI_API bool AiRenderGetHintStr	(	const AtRenderSession *	render_session,
		AtString	hint,
		AtString &	value
	)

Get a render hint.

If a hint exists of this type and name, return it. There are currently no render hints of type string.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be written to this argument if the hint exists

Returns: whether the hint exists.

◆ AiRenderGetHintArray()

AI_API bool AiRenderGetHintArray	(	const AtRenderSession *	render_session,
		AtString	hint,
		const AtArray *&	value
	)

Get a render hint.

If a hint exists of this type and name, return it. There are currently no render hints of type array.

Parameters

render_session	Pointer to the render session this function call applies to (NULL for default render session)
hint	The name of the hint
value	The value will be written to this argument if the hint exists

Returns: whether the hint exists.

◆ AiRenderBegin()

AI_API AtRenderErrorCode AiRenderBegin	(	AtRenderSession *	render_session,
		AtRenderMode	mode,
		AtRenderUpdateCallback	update_callback,
		void *	callback_private_data
	)

Start a render asynchronously.

Initializes frame-dependant data and launches bucket workers (if requested).

If the mode is set to AI_RENDER_MODE_CAMERA, then Arnold will launch a number of bucket workers (i.e. threads), render the image from the camera, and write the output images (if any). However, if AI_RENDER_MODE_FREE is passed instead, then Arnold will put itself in a mode where it services ray-tracing requests only. In this mode, the user instructs Arnold to shoot rays by calling functions like AiTrace() or AiIrradiance() directly. This mode is useful in situations where the user wants to use Arnold as a "ray-tracing engine" instead of an image generator, for example to "bake" or precompute illumination into light maps. In this mode, it is usually convenient to create the render session using AI_SESSION_INTERACTIVE, specially if the user will inspect node state and parameter values.

If a render update callback is supplied, it will be invoked periodically when render passes complete, when some bucket data is ready, or when an interrupt or error occurs. The callback can update the status of the render. For interactive renders, nodes may be modified in the callback under most circumstances and the render restarted. Or, the render may be left paused, and then resumed later with AiRenderResume() or AiRenderRestart(). See more information at AtRenderUpdateCallback.

Note: The render must be cleaned up by calling AiRenderEnd().

Parameters

render_session	The render session that will be used for this render (NULL for default render session)
mode	Either render an image from the camera or operate as a ray-tracing server (default is AI_RENDER_MODE_CAMERA)
update_callback	Invoked periodically for render status updates

Returns: AI_SUCCESS upon successful render startup, or an error code

◆ AiRenderEnd()

AI_API AtRenderErrorCode AiRenderEnd ( AtRenderSession * render_session )

Finalize and clean up after beginning a render.

This will return the final success or failure of the render, and must be called to clean up after beginning a render. The status (returned from AiRenderGetStatus() API function) will be AI_RENDER_STATUS_NOT_STARTED after calling this, so that a new render may be started afterward.

Parameters

render_session Pointer to the render session (NULL for default render session)

Returns: AI_SUCCESS if successful, or else an error code

◆ AiRenderGetStatus()

AI_API AtRenderStatus AiRenderGetStatus ( const AtRenderSession * render_session )

Get the current status of a render session.

Parameters

render_session Pointer to the render session (NULL for default render session)

Returns: the current render status, AI_RENDER_STATUS_NOT_STARTED etc.

◆ AiRenderInterrupt()

AI_API void AiRenderInterrupt	(	AtRenderSession *	render_session,
		AtBlockingCall	blocking
	)

Stop rendering on a render session quickly and go to a paused state.

This function is similar in operation to AiRenderAbort(). It instructs the render session to interrupt rendering as quickly and as cleanly as possible. This is often used by a GUI thread in an interactive rendering environment. Unlike AiRenderAbort() the render can be resumed afterwards.

If a render update callback is being used, it will be invoked as soon as the render is paused. The render may be restarted from the callback. If an update callback is not being used, then the render may be resumed via AiRenderResume() instead. The render may be ended after it is paused by calling AiRenderEnd().

Note: For the legacy render API, terminating a render with this function will cause AiRender() to return with the AI_INTERRUPT code.; This may be called from within an AtRenderUpdateCallback, but only in non-blocking mode, or else it will hang.

Parameters

render_session	Pointer to the render session (NULL for default render session)
blocking	Whether the call blocks until the render is fully paused or not

◆ AiRenderAbort()

AI_API void AiRenderAbort	(	AtRenderSession *	render_session,
		AtBlockingCall	blocking
	)

Stop rendering on a render session as quickly as possible.

This function instructs the render session to stop rendering as quickly and as cleanly as possible. This does not happen immediately, however, as it can take some time for the bucket workers to wrap up their work.

The renderer should only be aborted in situations where there is a serious problem. To interrupt the renderer for purposes of an interactive rendering system, AiRenderInterrupt() should be used instead.

Afterwards, AiRenderEnd() should still be called to conclude clean-up.

Note: For the legacy render API, terminating a render with this function will cause AiRender() to return with the AI_ABORT code.; This may be called from within an AtRenderUpdateCallback, but only in non-blocking mode, or else it will hang.

Parameters

render_session	Pointer to the render session (NULL for default render session)
blocking	Whether the call blocks until the render is fully aborted or not

◆ AiRenderResume()

AI_API void AiRenderResume ( AtRenderSession * render_session )

Resume a render session after it was paused.

After a render is paused via the render update callback returning AI_RENDER_STATUS_PAUSED, this is called to pick up where the render left off. If the render was interrupted (AiRenderInterrupt() for more info) then this will restart rendering like AiRenderRestart() does.

Note: This can also be used to continue a render that was finished, if sample settings are adjusted higher and more passes are desired.; This should not be called from within an AtRenderUpdateCallback, instead the callback should return AI_RENDER_STATUS_RENDERING.

Parameters

render_session Pointer to the render session (NULL for default render session)

◆ AiRenderRestart()

AI_API void AiRenderRestart ( AtRenderSession * render_session )

Restart a render session after it was paused.

After a render is paused via AiRenderInterrupt() or because of the render update callback returning AI_RENDER_STATUS_PAUSED, this is called to restart rendering after nodes have been modified in a way that invalidates pixels that have already been rendered so far.

Note: This can also be used to restart a render that was finished.; This should not be called from within an AtRenderUpdateCallback, instead the callback should return AI_RENDER_STATUS_RESTARTING.

Parameters

render_session Pointer to the render session (NULL for default render session)

◆ AiRenderIsAnyActive()

AI_API bool AiRenderIsAnyActive ( )

Returns true if any of the existing universes is being rendered.

Returns: true if any of the existing universes is being rendered; false otherwise.

◆ AiRender()

AI_API AtRenderErrorCode AiRender	(	AtRenderSession *	render_session,
		AtRenderMode	mode
	)

Prepares a render and wait synchronously until it is finished before returning.

This function is basically equivalent to calling AiRenderBegin(), then waiting for the render to be finished, then calling AiRenderEnd().

While the mode parameter can be used to select either CAMERA or FREE render mode (see AiRenderBegin()), it is only expected to be used in CAMERA mode, and even more specifically, only in a batch render session. This function is just a convenient way to quickly perform a render, but it is not optimized for interactive rendering.

Parameters

render_session	Render session where this render will happen
mode	Either render the image from the camera or operate as a ray-tracing server (default is AI_RENDER_MODE_CAMERA)

Returns: AI_SUCCESS upon successful rendering, or an error code

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ AtRenderUpdateCallback

Enumeration Type Documentation

◆ AtRenderMode

◆ AtRenderErrorCode

◆ AtSessionMode

◆ AtDisplayOutput

◆ AtRenderStatus

◆ AtRenderUpdateType

◆ AtSystemHandlerMask

Function Documentation

◆ AiBegin()

◆ AiEnd()

◆ AiArnoldIsActive()

◆ AiSetSystemHandlers()

◆ AiRenderSession()

◆ AiRenderSessionGetUniverse()

◆ AiRenderSessionGetOptions()

◆ AiRenderSessionDestroy()

◆ AiGetSessionMode()

◆ AiRenderAddInteractiveOutput()

◆ AiRenderIsInteractiveOutput()

◆ AiRenderRemoveInteractiveOutput()

◆ AiRenderRemoveAllInteractiveOutputs()

◆ AiRenderSetHintBool()

◆ AiRenderSetHintInt()

◆ AiRenderSetHintFlt()

◆ AiRenderSetHintStr()

◆ AiRenderSetHintArray()

◆ AiRenderGetHintBool()

◆ AiRenderGetHintInt()

◆ AiRenderGetHintFlt()

◆ AiRenderGetHintStr()

◆ AiRenderGetHintArray()

◆ AiRenderBegin()

◆ AiRenderEnd()

◆ AiRenderGetStatus()

◆ AiRenderInterrupt()

◆ AiRenderAbort()

◆ AiRenderResume()

◆ AiRenderRestart()

◆ AiRenderIsAnyActive()

◆ AiRender()