Functions
Rendering API

Functions

AI_API void AiBegin ()
 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 int AiRender (int mode=AI_RENDER_MODE_CAMERA)
 Initializes frame-dependant data and launches bucket workers (if requested) More...
 
AI_API void AiRenderAbort ()
 Tell the renderer to abort itself as quickly as possible. More...
 
AI_API void AiRenderInterrupt ()
 Tell the renderer to interrupt itself as quickly as possible. More...
 
AI_API bool AiRendering ()
 Returns the rendering status of the renderer. More...
 

Rendering Modes

#define AI_RENDER_MODE_CAMERA   0x00
 Render from a camera.
 
#define AI_RENDER_MODE_FREE   0x01
 Process arbitrary ray-tracing requests, acting as a "ray server".
 

Error Codes

#define AI_SUCCESS   0x00
 no error
 
#define AI_ABORT   0x01
 render aborted
 
#define AI_ERROR_WRONG_OUTPUT   0x02
 can't open output file
 
#define AI_ERROR_NO_CAMERA   0x03
 camera not defined
 
#define AI_ERROR_BAD_CAMERA   0x04
 bad camera data
 
#define AI_ERROR_VALIDATION   0x05
 usage not validated
 
#define AI_ERROR_RENDER_REGION   0x06
 invalid render region
 
#define AI_ERROR_OUTPUT_EXISTS   0x07
 output file already exists
 
#define AI_ERROR_OPENING_FILE   0x08
 can't open file
 
#define AI_INTERRUPT   0x09
 render interrupted by user
 
#define AI_ERROR_UNRENDERABLE_SCENEGRAPH   0x0A
 unrenderable scenegraph
 
#define AI_ERROR_NO_OUTPUTS   0x0B
 no rendering outputs
 
#define AI_ERROR   -1
 generic error
 

Detailed Description

Function Documentation

AI_API void AiBegin ( )

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.

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 int AiRender ( int  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 or point clouds.

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 void AiRenderAbort ( )

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.

Terminating a render with this function will cause AiRender() to return with the AI_ABORT code.

AI_API void AiRenderInterrupt ( )

Tell the renderer to interrupt itself as quickly as possible.

This function is very 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.

Terminating a render with this function will cause AiRender() to return with the AI_INTERRUPT code.

AI_API bool AiRendering ( )

Returns the rendering status of the renderer.

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

Returns
true if the renderer is rendering; false otherwise.

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com