Shader Message Passing API

Message Retrieval Macros

These macros allow a shader to retrieve messages which have been written to the message bank. If the named message does not exist (has not been written yet?), then false is returned. Otherwise, true indicates a successful read.

Please refer to ai_shader_message.h for a description of the message-reading functions called by these macros.

#define AiStateGetMsgByte(name, val)   AiMessageGetByteFunc (sg,name,val)
 
#define AiStateGetMsgBool(name, val)   AiMessageGetBoolFunc (sg,name,val)
 
#define AiStateGetMsgInt(name, val)   AiMessageGetIntFunc (sg,name,val)
 
#define AiStateGetMsgUInt(name, val)   AiMessageGetUIntFunc (sg,name,val)
 
#define AiStateGetMsgFlt(name, val)   AiMessageGetFltFunc (sg,name,val)
 
#define AiStateGetMsgRGB(name, val)   AiMessageGetRGBFunc (sg,name,val)
 
#define AiStateGetMsgRGBA(name, val)   AiMessageGetRGBAFunc (sg,name,val)
 
#define AiStateGetMsgVec(name, val)   AiMessageGetVecFunc (sg,name,val)
 
#define AiStateGetMsgPnt(name, val)   AiMessageGetPntFunc (sg,name,val)
 
#define AiStateGetMsgPnt2(name, val)   AiMessageGetPnt2Func (sg,name,val)
 
#define AiStateGetMsgStr(name, val)   AiMessageGetStrFunc (sg,name,val)
 
#define AiStateGetMsgPtr(name, val)   AiMessageGetPtrFunc (sg,name,val)
 
#define AiStateGetMsgArray(name, val)   AiMessageGetArrayFunc(sg,name,val)
 

Message Writing Macros

These macros allow a shader to write messages to the message bank. If the write has failed for some reason (perhaps there are already too many messages in the bank?) then false is returned. Otherwise, true indicates a successful write.

Please refer to ai_shader_message.h for a description of the message-writing functions called by these macros.

#define AiStateSetMsgByte(name, val)   AiMessageSetByteFunc (sg,name,val)
 
#define AiStateSetMsgBool(name, val)   AiMessageSetBoolFunc (sg,name,val)
 
#define AiStateSetMsgInt(name, val)   AiMessageSetIntFunc (sg,name,val)
 
#define AiStateSetMsgUInt(name, val)   AiMessageSetUIntFunc (sg,name,val)
 
#define AiStateSetMsgFlt(name, val)   AiMessageSetFltFunc (sg,name,val)
 
#define AiStateSetMsgRGB(name, val)   AiMessageSetRGBFunc (sg,name,val)
 
#define AiStateSetMsgRGBA(name, val)   AiMessageSetRGBAFunc (sg,name,val)
 
#define AiStateSetMsgVec(name, val)   AiMessageSetVecFunc (sg,name,val)
 
#define AiStateSetMsgPnt(name, val)   AiMessageSetPntFunc (sg,name,val)
 
#define AiStateSetMsgPnt2(name, val)   AiMessageSetPnt2Func (sg,name,val)
 
#define AiStateSetMsgStr(name, val)   AiMessageSetStrFunc (sg,name,val)
 
#define AiStateSetMsgPtr(name, val)   AiMessageSetPtrFunc (sg,name,val)
 
#define AiStateSetMsgArray(name, val)   AiMessageSetArrayFunc(sg,name,val)
 

Message Inspection Functions

These functions let you loop over all available messages for a given sample. This is mainly intended for debugging purposes.

typedef struct AtMessageIterator AtMessageIterator
 This represents a message iterator. More...
 
AI_API AtMessageIteratorAiMessageIterator (const AtShaderGlobals *sg)
 Create a new message iterator. More...
 
AI_API bool AiMessageIteratorGetNext (AtMessageIterator *iterator, const char **msg_name, int *msg_type)
 Fetch the next available message (if it exists) and return its name and type. More...
 

Detailed Description

This message passing API allows the shader to write a message into the messsage bank which can be retrieved by other shaders in the current/active shading network. A "message" consists of a value and an associated name. To retrieve a message (a value), one needs to provide the name of that message.

The "lifetime" of these messages is for a single screen sample (it's attached to the AtShaderGlobals of the current pixel/sample). So, if a single camera ray recursively fires new rays, then the messages created anywhere in that ray-tree will be accessible by any shader in that ray-tree. When the next camera ray is fired, the message bank will be completely emptied.

The message bank has a fixed number of slots, so it is possible that one could fill the message bank. In that case, all subsequent writes of new messages will fail.

Typedef Documentation

This represents a message iterator.

The actual contents of this struct are private.

Function Documentation

AI_API AtMessageIterator* AiMessageIterator ( const AtShaderGlobals sg)

Create a new message iterator.

The iterator is allocated in temporary memory and will be free'd automatically by the renderer.

Parameters
sgcurrent shader globals
Returns
a message iterator to be passed to AiMessageIteratorGetNext()
See Also
AiMessageIteratorGetNext
AI_API bool AiMessageIteratorGetNext ( AtMessageIterator iter,
const char **  msg_name,
int *  msg_type 
)

Fetch the next available message (if it exists) and return its name and type.

Parameters
itermessage iterator
[out]msg_namename of the fetched message (or NULL if this is not needed)
[out]msg_typetype of the fetched message (or NULL if this is not needed)
Returns
true if a message was available, false otherwise
See Also
AiMessageIterator

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