Data Structures | Macros | Typedefs
Pixel Sample Filter Nodes

Data Structures

struct  AtFilterNodeMethods
 Filter Node methods structure. More...
 

Macros

#define AI_FILTER_NODE_EXPORT_METHODS(tag)
 Filter Node methods exporter. More...
 

Typedefs

typedef struct AtFilterNodeMethods AtFilterNodeMethods
 Filter Node methods structure.
 

Node Method Declarations

#define filter_output_type   static AtByte FilterOutputType(const AtNode* node, const AtParamValue* params, AtByte input_type)
 Filter's filter_output_type method declaration. More...
 
#define filter_pixel   static void FilterPixel(AtNode* node, AtParamValue* params, AtAOVSampleIterator* iterator, void* data_out, AtByte data_type)
 Filter's filter_pixel method declaration. More...
 

API Methods for Filter Writers

AI_API void AiFilterInitialize (AtNode *node, bool requires_depth, const char **required_aovs, void *data)
 Initializes an AOV filter. More...
 
AI_API void AiFilterUpdate (AtNode *node, float width)
 Updates an AOV filter. More...
 
AI_API void AiFilterDestroy (AtNode *node)
 Filter destructor. More...
 
AI_API void * AiFilterGetLocalData (const AtNode *node)
 Retrieve local data pointer for the specified filter. More...
 

API Methods to Loop over Samples

AI_API void AiAOVSampleIteratorInitPixel (AtAOVSampleIterator *iter, int x, int y)
 Initialize the iterator for looping over the sample of the specified pixel. More...
 
AI_API void AiAOVSampleIteratorReset (AtAOVSampleIterator *iter)
 Reset the iterator to its initial state (start of the same pixel). More...
 
AI_API bool AiAOVSampleIteratorGetNext (AtAOVSampleIterator *iter)
 Advance iterator to next sample (or return false if none are left). More...
 
AI_API bool AiAOVSampleIteratorGetNextDepth (AtAOVSampleIterator *iter)
 Advance the iterator through the "deep" sample off of the current sub-pixel sample. More...
 
AI_API AtPoint2 AiAOVSampleIteratorGetOffset (const AtAOVSampleIterator *iter)
 Get the (x,y) offset from the pixel center. More...
 
AI_API float AiAOVSampleIteratorGetInvDensity (const AtAOVSampleIterator *iter)
 
AI_API int AiAOVSampleIteratorGetDepth (const AtAOVSampleIterator *iter)
 Get the depth of the current sample. More...
 
AI_API bool AiAOVSampleIteratorHasValue (const AtAOVSampleIterator *iter)
 Test if the iterator has a value for the primary AOV at the current location. More...
 
AI_API bool AiAOVSampleIteratorHasAOVValue (const AtAOVSampleIterator *iter, const char *name, AtByte type)
 Test if the iterator has a value for an arbitrary AOV at the current location. More...
 

API Methods to Get Sample Value from Iterator

AI_API bool AiAOVSampleIteratorGetBool (const AtAOVSampleIterator *iter)
 
AI_API int AiAOVSampleIteratorGetInt (const AtAOVSampleIterator *iter)
 
AI_API float AiAOVSampleIteratorGetFlt (const AtAOVSampleIterator *iter)
 
AI_API AtRGB AiAOVSampleIteratorGetRGB (const AtAOVSampleIterator *iter)
 
AI_API AtRGBA AiAOVSampleIteratorGetRGBA (const AtAOVSampleIterator *iter)
 
AI_API AtVector AiAOVSampleIteratorGetVec (const AtAOVSampleIterator *iter)
 
AI_API AtPoint AiAOVSampleIteratorGetPnt (const AtAOVSampleIterator *iter)
 
AI_API AtPoint2 AiAOVSampleIteratorGetPnt2 (const AtAOVSampleIterator *iter)
 
AI_API const void * AiAOVSampleIteratorGetPtr (const AtAOVSampleIterator *iter)
 

API Methods to Get Sample Value from Iterator for an Arbitrary AOV

AI_API bool AiAOVSampleIteratorGetAOVBool (const AtAOVSampleIterator *iter, const char *name)
 
AI_API int AiAOVSampleIteratorGetAOVInt (const AtAOVSampleIterator *iter, const char *name)
 
AI_API float AiAOVSampleIteratorGetAOVFlt (const AtAOVSampleIterator *iter, const char *name)
 
AI_API AtRGB AiAOVSampleIteratorGetAOVRGB (const AtAOVSampleIterator *iter, const char *name)
 
AI_API AtRGBA AiAOVSampleIteratorGetAOVRGBA (const AtAOVSampleIterator *iter, const char *name)
 
AI_API AtVector AiAOVSampleIteratorGetAOVVec (const AtAOVSampleIterator *iter, const char *name)
 
AI_API AtPoint AiAOVSampleIteratorGetAOVPnt (const AtAOVSampleIterator *iter, const char *name)
 
AI_API AtPoint2 AiAOVSampleIteratorGetAOVPnt2 (const AtAOVSampleIterator *iter, const char *name)
 
AI_API const void * AiAOVSampleIteratorGetAOVPtr (const AtAOVSampleIterator *iter, const char *name)
 

Detailed Description

Arnold has support for pluggable sample filters. The filter will process a bucket of AOV subsamples and filter them down to a single AOV sample per pixel.

Filters operate on a "primary" AOV; this is the AOV which is specified on the same "outputs" line as where the filter is specified. However, filters can also query supporting, or auxiliary, AOVs which can assist in filtering. These are specified when a filter is initialized (see AiFilterInitialize()).

Macro Definition Documentation

#define AI_FILTER_NODE_EXPORT_METHODS (   tag)
Value:
filter_pixel; \
static AtFilterNodeMethods ai_filter_mtds = { \
FilterOutputType, \
FilterPixel \
}; \
static AtNodeMethods ai_node_mtds = { \
&ai_common_mtds, \
&ai_filter_mtds \
}; \
AtNodeMethods *tag = &ai_node_mtds;

Filter Node methods exporter.

#define filter_output_type   static AtByte FilterOutputType(const AtNode* node, const AtParamValue* params, AtByte input_type)

Filter's filter_output_type method declaration.

This function describes how a pixel sample filter will map a particular input type to an output type. For example, if a filter is asked to filter an Integer AOV, then the filter might decide to convert the integers to floats first and then output a float containing the filtered values. Most filters' "output" type will match their "input" type. The system will use this information to ensure that a filter is only connected to an output driver which can write the filter's output type.

Parameters
nodeThe filter node
paramsThe filter node's parameters array
input_typeA particular input type (e.g. AI_TYPE_RGB, AI_TYPE_FLOAT, etc)
Returns
returns the output type of this filter for a given input type
#define filter_pixel   static void FilterPixel(AtNode* node, AtParamValue* params, AtAOVSampleIterator* iterator, void* data_out, AtByte data_type)

Filter's filter_pixel method declaration.

This function peforms pixel filtering. Generally, this function will contain a loop which iterates over all the samples of the primary AOV which are contained in this pixel.

Parameters
nodeThe filter node
paramsThe filter node's parameter list
iteratorAn iterator which the filter uses to iterate over all the samples of the primary AOV for the current pixel. The user advances to the next sample by calling AiAOVSampleIteratorGetNext().
data_outA pointer to where the filter writes the filtered pixel output.
data_typeThis contains the data-type of the primary AOV.

Function Documentation

AI_API void AiFilterInitialize ( AtNode node,
bool  requires_depth,
const char **  required_aovs,
void *  data 
)

Initializes an AOV filter.

This function must be called by a pluggable AOV-filter when the node is initialized in the node_initialize method. It serves to initialize the filter and instructs the system as to the capabilities/requirements of the filter.

Parameters
nodeThe pointer to the filter's node
requires_depthA boolean telling the system whether this filter is capable of filtering both spatially and with respect to sample depth. If this boolean is set to true, then the system will store all the writes of the required AOVs regardless of depth.
required_aovsThis is a list of the AOVs required by this filter in order to perform filtering. Some filters require "auxiliary" AOVs to assist in filtering the primary AOV. For example, a "closest_filter" would require an AOV containing depth information in order to find the closest occurence of the primary AOV.
dataA pointer to data local to a particular instance of a filter node. This pointer can be retrieved by calling AiFilterGetLocalData().
AI_API void AiFilterUpdate ( AtNode node,
float  width 
)

Updates an AOV filter.

This function must be called by a pluggable AOV-filter when the node is updated in the node_update method. It will reconfigure the filter taking into account any change.

Parameters
nodeThe pointer to the filter's node
widthThe width of the filter
AI_API void AiFilterDestroy ( AtNode node)

Filter destructor.

This function serves to destroy and unregister a particular AOV filter from the system. This should be called in a filter node's node_finish method.

Parameters
nodePointer to the filter node
AI_API void* AiFilterGetLocalData ( const AtNode node)

Retrieve local data pointer for the specified filter.

Parameters
nodePointer to the filter node
Returns
Local data pointer, as passed to AiFilterInitialize()
AI_API void AiAOVSampleIteratorInitPixel ( AtAOVSampleIterator *  iter,
int  x,
int  y 
)

Initialize the iterator for looping over the sample of the specified pixel.

This method only needs to be called inside raw drivers which need to access multiple pixels. Regular filters receive an iterator which has already been initialized to the correct pixel location.

Parameters
iterthe sample iterator
xx pixel coordinate
yy pixel coordinate
AI_API void AiAOVSampleIteratorReset ( AtAOVSampleIterator *  iter)

Reset the iterator to its initial state (start of the same pixel).

This can be useful for filters or raw drivers which need to loop over the same pixel several times.

Parameters
iterthe sample iterator
AI_API bool AiAOVSampleIteratorGetNext ( AtAOVSampleIterator *  iter)

Advance iterator to next sample (or return false if none are left).

This function should be called inside a while loop to process all available samples.

Parameters
iterthe sample iterator
Returns
true while more samples are available
AI_API bool AiAOVSampleIteratorGetNextDepth ( AtAOVSampleIterator *  iter)

Advance the iterator through the "deep" sample off of the current sub-pixel sample.

Parameters
iterthe sample iterator
Returns
true while more "deep" samples are available
AI_API AtPoint2 AiAOVSampleIteratorGetOffset ( const AtAOVSampleIterator *  iter)

Get the (x,y) offset from the pixel center.

This can be used to compute the exact weight a sample should receive. Each component is guaranteed to lie within the filter radius. Raw-drivers only have a radius of 0.5 (one pixel wide).

Parameters
iterthe sample iterator
Returns
the x,y offset from the pixel center
AI_API int AiAOVSampleIteratorGetDepth ( const AtAOVSampleIterator *  iter)

Get the depth of the current sample.

This is only useful for deep raw drivers or deep-filters which need to examine more than one hit within a pixel. The depth is numbered such that the sample closest to the screen is depth=0.

Parameters
iterthe sample iterator
Returns
depth of the current sample
AI_API bool AiAOVSampleIteratorHasValue ( const AtAOVSampleIterator *  iter)

Test if the iterator has a value for the primary AOV at the current location.

The primary is defined by the filter. Not all samples are guaranteed to have a value. It is generally safe to avoid calling this method unless the sample count is of specific importance. Samples that did not receive a value will be 0.

Parameters
iterthe sample iterator
Returns
true if a value was written to this sample
AI_API bool AiAOVSampleIteratorHasAOVValue ( const AtAOVSampleIterator *  iter,
const char *  name,
AtByte  type 
)

Test if the iterator has a value for an arbitrary AOV at the current location.

Not all samples are guaranteed to have a value. It is generally safe to avoid calling this method unless the sample count is of specific importance. Samples that did not receive a value will be 0. The AOV queried must have been requested as a secondary AOV from the filter or the raw-driver in order to be visible.

Parameters
iterthe sample iterator
namename of the AOV to lookup
typetype of the AOV to lookup
Returns
true if a value was written to this sample for the specified AOV

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