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...

Variables
uint8_t(*	AtFilterNodeMethods::FilterOutputType )(const AtNode *, uint8_t)

void(*	AtFilterNodeMethods::FilterPixel )(AtNode , AtAOVSampleIterator , void *, uint8_t)

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...

AI_API AI_PURE AtString	AiAOVSampleIteratorGetAOVName (const AtAOVSampleIterator *iter)
	Returns the name of the primary AOV. 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)

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...

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

◆ AI_FILTER_NODE_EXPORT_METHODS

#define AI_FILTER_NODE_EXPORT_METHODS ( tag )

Value:

AI_INSTANCE_COMMON_METHODS                      \
filter_output_type;                             \
filter_pixel;                                   \
static AtFilterNodeMethods ai_filter_mtds = {   \
   FilterOutputType,                            \
   FilterPixel                                  \
};                                              \
static AtNodeMethods ai_node_mtds = {           \
   &ai_common_mtds,                             \
   &ai_filter_mtds                              \
};                                              \
const AtNodeMethods *tag = &ai_node_mtds;

Filter Node methods exporter.

◆ filter_output_type

#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

node	The filter node
input_type	A 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

◆ filter_pixel

#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

node	The filter node
iterator	An 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_out	A pointer to where the filter writes the filtered pixel output.
data_type	This contains the data-type of the primary AOV.

Function Documentation

◆ AiFilterInitialize()

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

node	The pointer to the filter's node
requires_depth	A 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_aovs	This 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. The format of the required AOVs string should be in the form "AOV_TYPE AOV_NAME". For example, requesting the normal AOV could be done with the string "VECTOR N".

◆ AiFilterUpdate()

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

node	The pointer to the filter's node
width	The width of the filter

◆ AiAOVSampleIteratorInitPixel()

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

iter	the sample iterator
x	x pixel coordinate
y	y pixel coordinate

◆ AiAOVSampleIteratorGetPixel()

AI_API void AiAOVSampleIteratorGetPixel	(	AtAOVSampleIterator *	iter,
		int &	x,
		int &	y
	)

Returns the pixel coordinates that the iterator was initialized for.

Parameters

iter	the sample iterator
x	x pixel coordinate
y	y pixel coordinate

◆ AiAOVSampleIteratorReset()

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

iter	the sample iterator

◆ AiAOVSampleIteratorGetNext()

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

iter	the sample iterator

Returns: true while more samples are available

◆ AiAOVSampleIteratorGetNextDepth()

AI_API bool AiAOVSampleIteratorGetNextDepth ( AtAOVSampleIterator * iter )

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

Parameters

iter	the sample iterator

Returns: true while more "deep" samples are available

◆ AiAOVSampleIteratorGetOffset()

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

iter	the sample iterator

Returns: the x,y offset from the pixel center

◆ AiAOVSampleIteratorGetInvDensity()

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:

while (AiAOVSampleIteratorGetNext(iter))
{
   // for importance sampling to work, samples must be scaled by some
   // measure of the probability with which they were chosen
   float inv_density = AiAOVSampleIteratorGetInvDensity(iter);
   const AtVector2 offset = AiAOVSampleIteratorGetOffset(iter);
   float sample_weight = filter(offset) * inv_density;
   ...
}

Parameters

iter	the sample iterator

Returns: the inverse of the sampling density of the current sample

◆ AiAOVSampleIteratorGetDepth()

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

iter	the sample iterator

Returns: depth of the current sample

◆ AiAOVSampleIteratorHasValue()

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

iter	the sample iterator

Returns: true if a value was written to this sample

◆ AiAOVSampleIteratorHasAOVValue()

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

iter	the sample iterator
name	name of the AOV to lookup
type	type of the AOV to lookup

Returns: true if a value was written to this sample for the specified AOV

◆ AiAOVSampleIteratorGetAOVName()

AI_API AI_PURE AtString AiAOVSampleIteratorGetAOVName ( const AtAOVSampleIterator * iter )

Returns the name of the primary AOV.

Parameters

iter	the sample iterator

Returns: the name of the primary AOV if set otherwise a null AtString

Data Structures

Macros

Variables

API Methods for Filter Writers

API Methods to Loop over Samples

API Methods to Get Sample Value from Iterator

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

Node Method Declarations

Detailed Description

Macro Definition Documentation

◆ AI_FILTER_NODE_EXPORT_METHODS

◆ filter_output_type

◆ filter_pixel

Function Documentation

◆ AiFilterInitialize()

◆ AiFilterUpdate()

◆ AiAOVSampleIteratorInitPixel()

◆ AiAOVSampleIteratorGetPixel()

◆ AiAOVSampleIteratorReset()

◆ AiAOVSampleIteratorGetNext()

◆ AiAOVSampleIteratorGetNextDepth()

◆ AiAOVSampleIteratorGetOffset()

◆ AiAOVSampleIteratorGetInvDensity()

◆ AiAOVSampleIteratorGetDepth()

◆ AiAOVSampleIteratorHasValue()

◆ AiAOVSampleIteratorHasAOVValue()

◆ AiAOVSampleIteratorGetAOVName()