Macros | Functions
AOV (Arbitrary Output Variables) API

This API is for writing AOVs (Arbitrary Ouput Values) from inside a shader. More...

Macros

#define AI_AOV_BLEND_NONE   0
 
#define AI_AOV_BLEND_OPACITY   1
 

Functions

AI_API bool AiAOVEnabled (const char *name, AtByte type)
 Query whether an AOV is enabled (exists) or not. More...
 
AI_API bool AiAOVRegister (const char *name, AtByte type, int blend_mode=AI_AOV_BLEND_NONE)
 Register a new AOV in the global AOV list. More...
 

AOV-writing Functions

These functions allow the user to write AOVs. Shaders may write AOVs indiscriminately without hesitation because the system understands the "context" in which an AOV write is performed. This means Arnold can store AOVs when it "makes sense" and ignore writes when it doesn't.

For example, Arnold will not store "deep" AOV values (AOVs which are written at different depths for a singe pixel-sample) unless a driver specifically requests "deep" AOV values. An example of a driver requiring "deep" AOV values would be one which writes deep-texture/volume-shadow files.

Arnold will only perform AOV writes from within the main trunk of a pixel-sample ray-tree. AOV writes made from inside a side-branch of the primary ray's ray-tree (such as a reflection) will be ignored. Also, AOV writes are ignored during shadow evaluations.

Parameters
sgthe current shader globals structure (pixel-sample state)
namethe name of the AOV to write into
valthe value to write into the AOV
Returns
a boolean indicating whether the write was successfully stored or not. A failure could indicate that the AOV is not enabled, or is of the wrong type, or is being written in the wrong "state" (such as not from within the trunk of the primary ray-tree).
AI_API bool AiAOVSetBool (AtShaderGlobals *sg, const char *name, bool val)
 
AI_API bool AiAOVSetInt (AtShaderGlobals *sg, const char *name, int val)
 
AI_API bool AiAOVSetFlt (AtShaderGlobals *sg, const char *name, float val)
 
AI_API bool AiAOVSetRGB (AtShaderGlobals *sg, const char *name, AtColor val)
 
AI_API bool AiAOVSetRGBA (AtShaderGlobals *sg, const char *name, AtRGBA val)
 
AI_API bool AiAOVSetVec (AtShaderGlobals *sg, const char *name, AtVector val)
 
AI_API bool AiAOVSetPnt (AtShaderGlobals *sg, const char *name, AtPoint val)
 
AI_API bool AiAOVSetPnt2 (AtShaderGlobals *sg, const char *name, AtPoint2 val)
 
AI_API bool AiAOVSetPtr (AtShaderGlobals *sg, const char *name, void *val)
 

AOV-reading Functions

These functions allow the user to read AOVs.

Parameters
sgthe current shader globals structure (pixel-sample state)
namethe name of the AOV to read from
valthe variable to store the read value
Returns
a boolean indicating whether the read was successfully done or not. A failure could indicate that the AOV is not enabled, or is of the wrong type.
AI_API bool AiAOVGetBool (const AtShaderGlobals *sg, const char *name, bool &val)
 
AI_API bool AiAOVGetInt (const AtShaderGlobals *sg, const char *name, int &val)
 
AI_API bool AiAOVGetFlt (const AtShaderGlobals *sg, const char *name, float &val)
 
AI_API bool AiAOVGetRGB (const AtShaderGlobals *sg, const char *name, AtColor &val)
 
AI_API bool AiAOVGetRGBA (const AtShaderGlobals *sg, const char *name, AtRGBA &val)
 
AI_API bool AiAOVGetVec (const AtShaderGlobals *sg, const char *name, AtVector &val)
 
AI_API bool AiAOVGetPnt (const AtShaderGlobals *sg, const char *name, AtPoint &val)
 
AI_API bool AiAOVGetPnt2 (const AtShaderGlobals *sg, const char *name, AtPoint2 &val)
 
AI_API bool AiAOVGetPtr (const AtShaderGlobals *sg, const char *name, void *&val)
 

Detailed Description

This API is for writing AOVs (Arbitrary Ouput Values) from inside a shader.

Arnold can route any number of AOVs into any number of drivers that can write to any number of output files.

Function Documentation

AI_API bool AiAOVEnabled ( const char *  name,
AtByte  type 
)

Query whether an AOV is enabled (exists) or not.

AOVs are only enabled if there is an output driver which depends on a specific AOV for its input. Writes to an AOV which is not "read" by any driver will be ignored.

For example, if a shader knows that a particular AOV isn't needed (not active), then it could conceivably save itself some work.

Warning
This function is meant to be called from the shader_evaluate method. It won't work if called from the node_initialize method.
Parameters
namethe name of the AOV
typethe type of the AOV (AI_TYPE_INT, AI_TYPE_RGB, etc)
Returns
a boolean indicating whether the AOV is enabled or not
AI_API bool AiAOVRegister ( const char *  name,
AtByte  type,
int  blend_mode 
)

Register a new AOV in the global AOV list.

Warning
This function is meant to be called from the node_update method.
Parameters
namethe name of the AOV
typethe type of the AOV (AI_TYPE_INT, AI_TYPE_RGB, etc)
blend_modethe blend operation used to compose semi-opaque layers of the AOV (AI_AOV_BLEND_NONE (default) or AI_AOV_BLEND_OPACITY)
Returns
a boolean indicating whether the AOV is registered or not

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