Detailed Description

See also:: Class SpecialFX, Class SFXParamDlg.

Description:: This class is available in release 3.0 and later only.

This is the plug-in class from which developers sub-class their Anti-aliasing filters. These filters appear in the Render Scene dialog in the Anti-Aliasing section in the Filter dropdown list.

Filter are a very simple plug-in as there are only a few methods that define them. The KernelFn() method is the one that does the filtering. The other methods are simply informational.

A filter kernel is nothing but a curve that starts (usually at 0) at some distance R from a center pole. This curve is swept around the center pole forming a volume that is centered at the center of a pixel (0.5,0.5) and extends to cover some of the near neighboring pixels. The height of this filter "hat" gives the weight for each pixel under the filter. To achieve high resolution and good quality this convolution is done at full 8x8 sub-pixel resolution: each subpixel is weighted by the height of the curve above it. This is what the KernelFn() method returns. It is given the distance from the center pole and it returns the weight. This is the only method that computes anything.

Note: When things get rasterized in 3ds Max it is done so at a resolution higher than that of the final output raster. 3ds Max actually rasterizes the geometry to an 8x8 raster within each pixel. This mask is used do hiding and shading operations properly inside each pixel. Each of these 64 inside-a-pixel pixels is called a subpixel.

Theoretically, the KernelFn() function could get called once for each sub-pixel with the distance of the center of that subpix to the center pole. Of course that would take a great deal of time. Instead 3ds Max builds a table at the beginning of a render. This table is slow to build (it requires many calls to KernelFn()) but fast to use and gives exactly the same answer as doing the computationly intense approach at the sub-pixel level. Thus the KernelFn() function can be fairly slow yet the render still happens relatively fast.

Plug-In Information:: Class Defined In RENDER.H

Super Class ID FILTER_KERNEL_CLASS_ID

Standard File Name Extension DLK

Extra Include File Needed None

#include <sfx.h>

Inheritance diagram for FilterKernel:

Public Member Functions
RefResult	NotifyRefChanged (Interval changeInt, RefTargetHandle hTarget, PartID &partID, RefMessage message)
	Receives and responds to messages.
SClass_ID	SuperClassID ()
	Retrieves a constant representing the type of the plugin.
IOResult	Save (ISave *isave)
IOResult	Load (ILoad *iload)
virtual FilterKernelParamDlg *	CreateParamDialog (IRendParams *ip)
virtual double	KernelFn (double x, double y=0.0)=0
virtual long	GetKernelSupport ()=0
virtual long	GetKernelSupportY ()=0
virtual bool	Is2DKernel ()=0
virtual bool	IsVariableSz ()=0
virtual void	SetKernelSz (double x, double y=0.0)=0
virtual void	GetKernelSz (double &x, double &y)=0
virtual bool	IsNormalized ()
virtual bool	HasNegativeLobes ()=0
virtual MCHAR *	GetDefaultComment ()=0
virtual long	GetNFilterParams ()
virtual MCHAR *	GetFilterParamName (long nParam)
virtual double	GetFilterParamMax (long nParam)
virtual double	GetFilterParam (long nParam)
virtual void	SetFilterParam (long nParam, double val)

Member Function Documentation

RefResult NotifyRefChanged	(	Interval	changeInt,
		RefTargetHandle	hTarget,
		PartID &	partID,
		RefMessage	message
	)		`[inline, virtual]`

Search for all occurrences

Receives and responds to messages.

A plugin which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged(). The plugin developer usually implements this method as a switch statement where each case is one of the messages the plugin needs to respond to. The Method StdNotifyRefChanged calls this, which can change the partID to new value. If it doesn't depend on the particular message& partID, it should return REF_DONTCARE.

For developer that need to update a dialog box with data about an object you reference note the following related to this method: This method may be called many times. For instance, say you have a dialog box that displays data about an object you reference. This method will get called many time during the drag operations on that object. If you updated the display every time you'd wind up with a lot of 'flicker' in the dialog box. Rather than updating the dialog box each time, you should just invalidate the window in response to the NotifyRefChanged() call. Then, as the user drags the mouse your window will still receive paint messages. If the scene is complex the user may have to pause (but not let up on the mouse) to allow the paint message to go through since they have a low priority. This is the way many windows in 3ds Max work.

Parameters:

changeInt	- This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.
hTarget	- This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message.
partID	- This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages.
message	- The message parameters passed into this method is the specific message which needs to be handled.

Returns:: The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.

Implements ReferenceMaker.

                                                    { return REF_SUCCEED; }

SClass_ID SuperClassID ( ) [inline, virtual]

Search for all occurrences

Retrieves a constant representing the type of the plugin.

Returns:: A super class id that uniquely identifies the type (category) of the plugin. Note that several plugin classes can be of the same type, thus return the same super class id. Plugins are uniquely identified by their class ids. List of Super Class IDs.

See also:: SClass_ID

Reimplemented from ReferenceTarget.

{ return FILTER_KERNEL_CLASS_ID; }

IOResult Save ( ISave * isave ) [inline, virtual]

Search for all occurrences

Remarks:: Saves the filter name. This should be called at the start of a plug-in's save method.

Reimplemented from SpecialFX.

{ return SpecialFX::Save(isave); }

IOResult Load ( ILoad * iload ) [inline, virtual]

Search for all occurrences

Remarks:: Loads the filter name. This should be called at the start of a plug-in's load method.

Reimplemented from SpecialFX.

{ return SpecialFX::Load(iload); }

virtual FilterKernelParamDlg* CreateParamDialog ( IRendParams * ip ) [inline, virtual]

Search for all occurrences

Remarks:: This method creates and returns a new instance of a class derived from SFXParamDlg to manage the user interface. This put up a modal dialog that lets the user edit the plug-ins parameters.

Parameters:: IRendParams *ip

This is the interface given to the plug-in so it may display its parameters.

Default Implementation:: { return NULL; }

Reimplemented from SpecialFX.

{ return NULL; }

virtual double KernelFn	(	double	x,
		double	y = `0.0`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the function that is called to sample the kernel values. This returns the weight of the filtering curve at the specified distance from the center pole of the curve.

Parameters:: double x

The distance from the center pole of the curve.

double y = 0.0

The distance from the center pole of the curve in y (for 2D filters).

virtual long GetKernelSupport ( ) [pure virtual]

Search for all occurrences

Remarks:: This method returns the kernel 'support'. Support is the integer number of pixels beyond the center pixel that are touch in some part by the kernel. Support of 0 is 1x1: the area filter. A support value of 1 is a 3x3 filter, one pixel on all sides of the center. A support of 2 is 5x5. The size of a side of the block is always 2*Support+1. Support confides how many pixels might be touched, but not the exact size of the filter.

virtual long GetKernelSupportY ( ) [pure virtual]

Search for all occurrences

Remarks:: For 2D kernels returns the Y support. See GetKernelSupport() above.

virtual bool Is2DKernel ( ) [pure virtual]

Search for all occurrences

Remarks:: Most kernels are 1D and hence circularly symmetric about the center pole, but some are 2D like a box or diamond. This method returns true if the filter is 2D and false if 1D.

A 2D kernel uses both parameters of the methods GetKernelSz() and SetKernelSz(). A 1D kernel only uses x; y need not be included in the set. Note that GetKernelSz() always requires both x & y since they are return parameters while a 1D kernel ignores y. Also note that a 2D filter provides a filter function that uses both the x and y parameters.

virtual bool IsVariableSz ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns true if the filter is variable size; otherwise false. Size means the distance from the center pole where the filter function becomes essentially 0. In non-variable size filters this width is returned in GetKernelSz() and is usually displayed in the greyed out Size box in the user interface. In variable size filters get & set size control the bluriness.

virtual void SetKernelSz	(	double	x,
		double	y = `0.0`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Stores the kernel size. A 2D kernel stores both parameters of this method. A 1D kernel stores only x.

Parameters:: double x

The x value to store.

double y = 0.0

The y value to store.

virtual void GetKernelSz	(	double &	x,
		double &	y
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Retrieves the kernel size. A 2D kernel uses both parameters of this method. A 1D kernel only uses x (y is set to 0).

Parameters:: double& x

The x size is returned here.

double& y

The y size is returned here.

virtual bool IsNormalized ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returning true from this method will disable the built-in normalizer. Normalized means that if you have some solid color and you filter it, you get the same color out;. it is not brighter or darker than the original. With positive only filters this is always possible, but with some negative lobe filters the colors overflow, so they are toned down (produce a slightly darker image, but don't overflow).

The normalizer computes the positive and negative volumes of an arbitrary filter and scales all the filter values by 1/volume where volume is (posVolume - abs( negVolume )). This whole process is turned off and the filter values direct from the plug-in have already been scaled internally when this method returns true.

Default Implementation:: { return FALSE; }

{ return FALSE; }

virtual bool HasNegativeLobes ( ) [pure virtual]

Search for all occurrences

Remarks:: This method tells the filtering code that it can speed things up potentially by dealing with the positive common only case. Currently this is not taken advantage of.

virtual MCHAR* GetDefaultComment ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns a pointer to a string which describes the filter. This string is displayed in the static text box in the user interface.

virtual long GetNFilterParams ( ) [inline, virtual]

Search for all occurrences

Remarks:: There are two optional parameters that may be used by the filter (besides Filter Size). This method returns the number used. If two parameters are used both hidden spinners appear in the Anti-aliasing section of the Render Scene dialog. If only one parameter is used just the top spinner appears. If this method returns nonzero then the methods below are used to supply the names for the parameter(s) and to provide and receive the values.