Data Structures | Macros
Pixel Sample Filter Nodes

Sample filters creation and operation. More...

Data Structures

struct  AtFilterNodeMethods
 Filter Node methods structure. More...
 

Macros

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

Node Method Declarations

#define filter_output_type   static uint8_t FilterOutputType(const AtNode* node, uint8_t input_type)
 Filter's filter_output_type method declaration. More...
 
#define filter_pixel   static void FilterPixel(AtNode* node, AtAOVSampleIterator* iterator, void* data_out, uint8_t 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)
 Initializes an AOV filter. More...
 
AI_API void AiFilterUpdate (AtNode *node, float width)
 Updates an AOV 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 AiAOVSampleIteratorGetPixel (AtAOVSampleIterator *iter, int &x, int &y)
 Returns the pixel coordinates that the iterator was initialized for. 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 AI_PURE AtVector2 AiAOVSampleIteratorGetOffset (const AtAOVSampleIterator *iter)
 Get the (x,y) offset from the pixel center. More...
 
AI_API AI_PURE float AiAOVSampleIteratorGetInvDensity (const AtAOVSampleIterator *iter)
 Get the inverse of the sampling density of the current sample. More...
 
AI_API AI_PURE int AiAOVSampleIteratorGetDepth (const AtAOVSampleIterator *iter)
 Get the depth of the current sample. More...
 
AI_API AI_PURE bool AiAOVSampleIteratorHasValue (const AtAOVSampleIterator *iter)
 Test if the iterator has a value for the primary AOV at the current location. More...
 
AI_API AI_PURE bool AiAOVSampleIteratorHasAOVValue (const AtAOVSampleIterator *iter, AtString name, uint8_t 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 AI_PURE bool AiAOVSampleIteratorGetBool (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE int AiAOVSampleIteratorGetInt (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE unsigned int AiAOVSampleIteratorGetUInt (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE float AiAOVSampleIteratorGetFlt (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE AtRGB AiAOVSampleIteratorGetRGB (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE AtRGBA AiAOVSampleIteratorGetRGBA (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE AtVector AiAOVSampleIteratorGetVec (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE AtVector2 AiAOVSampleIteratorGetVec2 (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE AtMatrix AiAOVSampleIteratorGetMatrix (const AtAOVSampleIterator *iter)
 
AI_API AI_PURE const void * AiAOVSampleIteratorGetPtr (const AtAOVSampleIterator *iter)
 

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

AI_API AI_PURE bool AiAOVSampleIteratorGetAOVBool (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE int AiAOVSampleIteratorGetAOVInt (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE unsigned int AiAOVSampleIteratorGetAOVUInt (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE float AiAOVSampleIteratorGetAOVFlt (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE AtRGB AiAOVSampleIteratorGetAOVRGB (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE AtRGBA AiAOVSampleIteratorGetAOVRGBA (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE AtVector AiAOVSampleIteratorGetAOVVec (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE AtVector2 AiAOVSampleIteratorGetAOVVec2 (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE AtMatrix AiAOVSampleIteratorGetAOVMatrix (const AtAOVSampleIterator *iter, const AtString name)
 
AI_API AI_PURE const void * AiAOVSampleIteratorGetAOVPtr (const AtAOVSampleIterator *iter, const AtString name)
 

Detailed Description

Sample filters creation and operation.

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:
static AtFilterNodeMethods ai_filter_mtds = { \
FilterOutputType, \
FilterPixel \
}; \
static AtNodeMethods ai_node_mtds = { \
&ai_common_mtds, \
&ai_filter_mtds \
}; \
const AtNodeMethods *tag = &ai_node_mtds;
#define filter_output_type
Filter's filter_output_type method declaration.
Definition: ai_filters.h:78
Filter Node methods structure.
Definition: ai_filters.h:39
Node methods.
Definition: ai_node_entry.h:83
#define filter_pixel
Filter's filter_pixel method declaration.
Definition: ai_filters.h:94

Filter Node methods exporter.

#define filter_output_type   static uint8_t FilterOutputType(const AtNode* node, uint8_t 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
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, AtAOVSampleIterator* iterator, void* data_out, uint8_t 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
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 
)

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.
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 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 AiAOVSampleIteratorGetPixel ( AtAOVSampleIterator *  iter,
int &  x,
int &  y 
)

Returns the pixel coordinates that the iterator was initialized for.

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 AI_PURE AtVector2 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 AI_PURE float AiAOVSampleIteratorGetInvDensity ( const AtAOVSampleIterator *  iter)

Get the inverse of the sampling density of the current sample.

This is needed by weighted-sum filters so that they may deal with samples having a non-uniform density, which happens for example when the adaptive sampling techniques is in use.

Usage example:

1 while (AiAOVSampleIteratorGetNext(iter))
2 {
3  // for importance sampling to work, samples must be scaled by some
4  // measure of the probability with which they were chosen
5  float inv_density = AiAOVSampleIteratorGetInvDensity(iter);
6  const AtVector2 offset = AiAOVSampleIteratorGetOffset(iter);
7  float sample_weight = filter(offset) * inv_density;
8  ...
9 }
Parameters
iterthe sample iterator
Returns
the inverse of the sampling density of the current sample
AI_API AI_PURE 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 AI_PURE 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 AI_PURE bool AiAOVSampleIteratorHasAOVValue ( const AtAOVSampleIterator *  iter,
AtString  name,
uint8_t  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

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