Class FilterKernel
See Also: Class SpecialFX, Class SFXParamDlg.
class FilterKernel : public SpecialFX
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
Methods:
public:
Prototype:
virtual double KernelFn(double x, double y = 0.0)=0;
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).
Prototype:
virtual bool Is2DKernel()=0;
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.
Prototype:
virtual long GetKernelSupport()=0;
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.
Prototype:
virtual long GetKernelSupportY()=0;
Remarks:
For 2D kernels returns the Y support. See GetKernelSupport() above.
Prototype:
virtual bool IsVariableSz()=0;
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.
Prototype:
virtual void GetKernelSz(double& x, double& y)=0;
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.
Prototype:
virtual void SetKernelSz(double x, double y = 0.0)=0;
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.
Prototype:
virtual bool IsNormalized();
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; }
Prototype:
virtual bool HasNegativeLobes()=0;
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.
Prototype:
virtual TCHAR* GetDefaultComment()=0;
Remarks:
Returns a pointer to a string which describes the filter. This string is displayed in the static text box in the user interface.
Prototype:
virtual long GetNFilterParams()=0;
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.
Prototype:
virtual TCHAR *GetFilterParamName(long nParam)=0;
Remarks:
Returns a pointer to the string containing the name of the specified parameter.
Parameters:
long nParam
The index of the parameter (0 or 1).
Prototype:
virtual double GetFilterParam(long nParam)=0;
Remarks:
Returns the specified parameter value.
Parameters:
long nParam
The index of the parameter (0 or 1).
Prototype:
virtual void SetFilterParam(long nParam, double val)=0;
Remarks:
Stores the value passed for the specified parameter.
Parameters:
long nParam
The index of the parameter (0 or 1).
double val
The value to set.
Prototype:
IOResult Save(ISave *isave);
Remarks:
Saves the filter name. This should be called at the start of a plug-in's save method.
Prototype:
IOResult Load(ILoad *iload);
Remarks:
Loads the filter name. This should be called at the start of a plug-in's load method.