Data Structures | Typedefs | Enumerations | Functions
Rendering API

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
}
 Reason for invoking the render update callback. More...
 

Functions

AI_API void AiBegin (AtSessionMode 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 AtSessionMode AiGetSessionMode ()
 Returns the current render session's mode. More...
 
AI_API void AiRenderAddInteractiveOutput (uint32_t output_index)
 Add the output to be displayed during fast interactive rendering. More...
 
AI_API bool AiRenderIsInteractiveOutput (uint32_t output_index)
 Get whether the output is displayed during fast interactive rendering. More...
 
AI_API bool AiRenderRemoveInteractiveOutput (uint32_t output_index)
 Remove the output so it is not displayed during fast interactive rendering. More...
 
AI_API void AiRenderRemoveAllInteractiveOutputs ()
 Remove the output so it is not displayed during fast interactive rendering. More...
 
AI_API AI_DEPRECATED void AiRenderSetInteractiveOutput (uint32_t output_index)
 Set the output displayed during fast interactive rendering. More...
 
AI_API AI_DEPRECATED uint32_t AiRenderGetInteractiveOutput ()
 Get the output displayed during fast interactive rendering. More...
 
AI_API bool AiRenderSetHintBool (AtString hint, bool value)
 Set a render hint. More...
 
AI_API bool AiRenderSetHintInt (AtString hint, int32_t value)
 Set a render hint. More...
 
AI_API bool AiRenderSetHintFlt (AtString hint, float value)
 Set a render hint. More...
 
AI_API bool AiRenderSetHintStr (AtString hint, AtString value)
 Set a render hint. More...
 
AI_API bool AiRenderSetHintArray (AtString hint, AtArray *value)
 Set a render hint. More...
 
AI_API bool AiRenderGetHintBool (AtString hint, bool &value)
 Get a render hint. More...
 
AI_API bool AiRenderGetHintInt (AtString hint, int32_t &value)
 Get a render hint. More...
 
AI_API bool AiRenderGetHintFlt (AtString hint, float &value)
 Get a render hint. More...
 
AI_API bool AiRenderGetHintStr (AtString hint, AtString &value)
 Get a render hint. More...
 
AI_API bool AiRenderGetHintArray (AtString hint, const AtArray *&value)
 Get a render hint. More...
 
AI_API AtRenderErrorCode AiRenderBegin (AtRenderMode mode=AI_RENDER_MODE_CAMERA, AtRenderUpdateCallback update_callback=NULL, void *callback_private_data=NULL)
 Start a render asynchronously. More...
 
AI_API AtRenderErrorCode AiRenderEnd ()
 Finalize and clean up after beginning a render. More...
 
AI_API AtRenderStatus AiRenderGetStatus ()
 Get the current status of rendering. More...
 
AI_API void AiRenderInterrupt (AtBlockingCall blocking=AI_NON_BLOCKING)
 Tell the renderer to interrupt itself quickly and go to a paused state. More...
 
AI_API void AiRenderResume ()
 Resume a render after it was paused. More...
 
AI_API void AiRenderRestart ()
 Restart a render after it was paused. More...
 
AI_API void AiRenderAbort (AtBlockingCall blocking=AI_NON_BLOCKING)
 Tell the renderer to abort itself as quickly as possible. More...
 
AI_API AI_DEPRECATED AtRenderErrorCode AiRender (AtRenderMode mode=AI_RENDER_MODE_CAMERA)
 Initializes frame-dependant data and launches bucket workers (if requested) More...
 
AI_API AI_DEPRECATED bool AiRendering ()
 Returns the rendering status of the renderer. More...
 

Detailed Description

Render process operation and querying.

Typedef Documentation

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

Render update callback.

This is called in the following circumstances:

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
AtRenderUpdateTypeAtRenderStatus
AI_RENDER_UPDATE_INTERRUPTAI_RENDER_STATUS_PAUSED
AI_RENDER_UPDATE_BEFORE_PASSAI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_DURING_PASSAI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_AFTER_PASSAI_RENDER_STATUS_RENDERING
AI_RENDER_UPDATE_FINISHEDAI_RENDER_STATUS_FINISHED
AI_RENDER_UPDATE_ERRORAI_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_dataPointer passed to AiRenderBegin(), used for whatever the callback needs
update_typeIndicates when the callback is being called
update_infoExtra pass, sample, and output information
Returns
The next AtRenderStatus desired

Enumeration Type Documentation

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".

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

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

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

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)

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.

Function Documentation

AI_API void AiBegin ( AtSessionMode  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 rendering is completed.

For information about the render modes see AtSessionMode

Parameters
modeThe session-wide mode, indicating the actions to be taken for the session
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. All memory pools are free'd and the scene is destroyed. API calls should not be made after a call to AiEnd().

AI_API AtSessionMode AiGetSessionMode ( )

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

Returns
the current render session mode.
AI_API void AiRenderAddInteractiveOutput ( 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
output_indexThe index into options.outputs for the output to display
AI_API bool AiRenderIsInteractiveOutput ( 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
output_indexThe index into options.outputs to check
Returns
whether the index into options.outputs will be displayed interactively
AI_API bool AiRenderRemoveInteractiveOutput ( 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
output_indexThe index into options.outputs for the output to not display
Returns
whether the output was previously added, and was successfully removed
AI_API void AiRenderRemoveAllInteractiveOutputs ( )

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
output_indexThe index into options.outputs for the output to not display
AI_API AI_DEPRECATED void AiRenderSetInteractiveOutput ( uint32_t  output_index)

Set the output displayed during fast interactive rendering.

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

Note
This function is deprecated, so interactive outputs should instead be managed by adding and removing instead of this function, which clears the list of interactive outputs and adds this single output.
Parameters
output_indexThe index into options.outputs for the output to display
AI_API AI_DEPRECATED uint32_t AiRenderGetInteractiveOutput ( )

Get the output displayed during fast interactive rendering.

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

Note
This function is deprecated, so interactive outputs should instead be managed by adding and removing instead of this function.
Returns
the index into options.outputs for the output to display.
AI_API bool AiRenderSetHintBool ( 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:

Parameters
hintThe name of the hint
valueThe value to be set if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderSetHintInt ( 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
hintThe name of the hint
valueThe value will be set if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderSetHintFlt ( 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 30.0
  • "interactive_target_fps_min", default 20.0
  • "interactive_fps_min", default 5.0
Parameters
hintThe name of the hint
valueThe value will be set if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderSetHintStr ( 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
hintThe name of the hint
valueThe value will be set if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderSetHintArray ( 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
hintThe name of the hint
valueThe value will be set if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderGetHintBool ( 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:

Parameters
hintThe name of the hint
valueThe value will be written to this argument if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderGetHintInt ( 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
hintThe name of the hint
valueThe value will be written to this argument if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderGetHintFlt ( AtString  hint,
float &  value 
)

Get a render hint.

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

  • "interactive_target_fps", default 30.0
  • "interactive_target_fps_min", default 20.0
  • "interactive_fps_min", default 5.0
Parameters
hintThe name of the hint
valueThe value will be written to this argument if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderGetHintStr ( 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
hintThe name of the hint
valueThe value will be written to this argument if the hint exists
Returns
whether the hint exists.
AI_API bool AiRenderGetHintArray ( 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
hintThe name of the hint
valueThe value will be written to this argument if the hint exists
Returns
whether the hint exists.
AI_API AtRenderErrorCode AiRenderBegin ( 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
modeEither render an image from the camera or operate as a ray-tracing server (default is AI_RENDER_MODE_CAMERA)
update_callbackInvoked periodically for render status updates
Returns
AI_SUCCESS upon successful render startup, or an error code
AI_API AtRenderErrorCode AiRenderEnd ( )

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.

Returns
AI_SUCCESS if successful, or else an error code
AI_API AtRenderStatus AiRenderGetStatus ( )

Get the current status of rendering.

Returns
the current render status, AI_RENDER_STATUS_NOT_STARTED etc.
AI_API void AiRenderInterrupt ( AtBlockingCall  blocking)

Tell the renderer to interrupt itself quickly and go to a paused state.

This function is similar in operation to AiRenderAbort(). It instructs the renderer to interrupt itself 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
blockingWhether the call blocks until the render is fully paused or not
AI_API void AiRenderResume ( )

Resume a render 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.
AI_API void AiRenderRestart ( )

Restart a render 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.
AI_API void AiRenderAbort ( AtBlockingCall  blocking)

Tell the renderer to abort itself as quickly as possible.

This function instructs the renderer to abort itself 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
blockingWhether the call blocks until the render is fully aborted or not
AI_API AI_DEPRECATED AtRenderErrorCode AiRender ( AtRenderMode  mode)

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.

Warning
This function is deprecated, use AiRenderBegin() and AiRenderEnd() instead
Parameters
modeEither 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
AI_API AI_DEPRECATED bool AiRendering ( )

Returns the rendering status of the renderer.

This function returns whether the renderer is currently rendering or not.

Warning
This function is deprecated, use AiRenderGetStatus() instead. This is equivalent to checking if AiRenderGetStatus() returns AI_RENDER_STATUS_RENDERING
Returns
true if the renderer is rendering; false otherwise.

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