Class Sampler
See Also: Class SpecialFX, Class SamplingCallback, Class SFXParamDlg, Class ShadeContext, Class Point3, Class Point2, Class ILoad, Class ISave.
class Sampler : public SpecialFX
Description:
This class is available in release 3.0 and later only.
This is the base class for the creation of Sampler plug-ins which work with the Standard material. These appear in the Super Sampling rollout in the Sampler dropdown. They have an Enable checkbox and a Quality spinner for their user interface. An optional modal dialog may also be presented.
A Sampler is a plug-in that determines where inside a single pixel the shading and texture samples are computed. For some Samplers this pattern is the same for each pixel, for others a different pattern is chosen for each pixel. After determining the sample locations, the sampler calls back to the renderer to compute the shading values. It then averages the resluting shading values and returns its estimate of the final color.
Some Samplers are adaptive. This means that the Sampler decides on-the-fly how many samples to take to achieve its goal. There are many subtleties to adaptive Samplers and many ways to define the adaptive mechanism. The adaptive mechanism used by the R3 Samplers is very simple: take 4 samples, look for the maximum change in any of the color channels, if it's greater than the threshold, then sample the entire pixel according to the given quality. Threshold is an optional parameter that may, but need not be used by adaptive Samplers.
The transfer of control from 3ds max to the Sampler plug-in is as follows: A Sampler is responsible for the sampling loop. It samples until it is done and computes the sum of its samples upon completion. Once the Sampler's DoSample() method is called 3ds max no longer has control. This is how adaptive samplers are handled. The DoSample() routine will determine how often and where it samples, then it calls the provided SamplingCallback::SampleAtOffset() method to have 3ds max compute the shading value.
Plug-In Information:
Class Defined In SAMPLER.H
Super Class ID SAMPLER_CLASS_ID
Standard File Name Extension DLH
Extra Include File Needed None
Methods:
public:
Prototype:
virtual void DoSamples(Color& c, Color& t, SamplingCallback* cb, ShadeContext* sc, MASK mask=NULL)=0;
Remarks:
This is the method where the Sampler plug-in does its sampling loop. Upon completion it returns the color and transparency back to 3ds max in c and t.
A sampler samples a range of 0.0 to 1.0. For a pixel sampler this range gets mapped to a single pixel. The sampler doesn't need to be concerned with this however. It just works within the 0.0 to 1.0 space determining where to put the samples. Essentially, this method generates a set of points and calls SamplingCallback::SampleAtOffset() for each one. Then it sums up the results of the values returned from SampleAtOffset(), divides by the number of samples, and stores the results in c and t.
Parameters:
Color& c
This is the output color.
Color& t
This is the output transparency.
SamplingCallback* cb
This is the callback provided by 3ds max which the sampler uses to actually do the sampling.
ShadeContext* sc
The Shade Context which provides information about the pixel being sampled.
MASK mask=NULL
The 64 bit pixel mask. This mask coresponds to the 8x8 sub-pixel area grid. The actual geometry covers only some portion of these bits. This is essentially an 8x8 raster for the inside of the pixel where bits are set over the polygon being rendered and bits are off for areas not over the polygon. Developers typically only want to sample where the geometry is and thus when the bits are on. If not the results are very poor visually.
Note: Most polygons are quite small in a typically complex scene being rendered. In other words, most polygons that need to get sampled will only have a small number of these mask bits on since the polygons are very small relative to the pixel. For instance, edge on polygons may project down to only a few bits within the pixel. Consequently it is quite possible that there may be zero samples, i.e. no geometry in the mask. Developers need to check for this zero samples condition. If this is the case then a method of ShadeContext called SurfacePtScreen() is used. This method returns a point which is guaranteed to be on the fragment no matter how small it is. This point can then be used for at least a single sample.
Sample Code:
The following is a brief analysis of the DoSamples() method from the Uniform Sampler of 3ds max. This sampler sub-divides the sample area into a grid and samples the pixel at the center point of each grid unit.
This code is from the file \MAXSDK\SAMPLES\RENDER\SAMPLERS\STDSAMPLERS.CPP.
The complete code is shown below and then a code fragment analysis follows:
void UniformSampler::DoSamples(Color& clr, Color&trans, SamplingCallback* cb, ShadeContext* sc, MASK mask )
{
int sideSamples = GetSideSamples();
int numSamples = sideSamples * sideSamples;
DbgAssert( sideSamples > 0 );
// we map 0...sideSz into 0..1
float sideSzInv = 1.0f / float(sideSamples);
float sampleScale = sideSzInv;
Point2 sample;
float nSamples = 0.0f;
clr.r = clr.g = clr.b = trans.r = trans.g = trans.b = 0;
// Sampling loop
for( int y = 0; y < sideSamples; ++y ) {
sample.y = (float(y) + 0.5f) * sideSzInv;
for( int x = 0; x < sideSamples; ++x ) {
sample.x = (float(x) + 0.5f) * sideSzInv;
if ( sampleInMask( sample, mask ) ) {
Color c, t;
// NB, returns true for unclipped samples
if (cb->SampleAtOffset( c, t, sample, sampleScale )) {
clr += c;
trans += t;
nSamples += 1.0f;
}
}
}
}
// Check for 0 samples
if ( nSamples == 0.0f ){
// use frag center if no other samples
sample = sc->SurfacePtScreen();
sample.x = frac(sample.x ); sample.y = frac( sample.y );
cb->SampleAtOffset( clr, trans, sample, 1.0f );
} else {
clr /= nSamples;
trans /= nSamples;
}
}
The above code is broken into smaller fragments to look at below:
int sideSamples = GetSideSamples();
Here the sampler is just getting the number of sides in the sampling grid. This is computed based on the Quality spinner in the user interface. In this sampler this results in a number between 2 and 6 (developers can look at the UniformSampler::GetSideSamples() method to see this). Thus the resulting sampling grid is 2x2 or 3x3, up to 6x6. Then the number of samples is computed by multiplying the number of sides times itself.
int numSamples = sideSamples * sideSamples;
Next the side size inverse is computed to know how big the step size is. This is the amount to step along each time.
The sample scale is how large is the piece that's being sampled. For example, if the grid is 2x2 then each sample is scaled by 1/2
float sideSzInv = 1.0f / float(sideSamples);
float sampleScale = sideSzInv;
Next the number of samples, and the color and transparency are initialized to zero:
Point2 sample;
float nSamples = 0.0f;
clr.r = clr.g = clr.b = trans.r = trans.g = trans.b = 0;
Then the sampling loop begins. Here the positions of individual sampling points are computed. Each point is then checked to see if it corresponds to a point in the mask (is over a polygon). (The sampleInMask function is defined in \MAXSDK\SAMPLES\RENDER\SAMPLERS\SAMPLERUTIL.CPP). If it is a point that's over a polygon then SampleAtOffset() is called. What SampleAtOffset() does is turn the passed 2D sample into a 3D sample and returns a color and transparency. These returned values are summed up over the sampling loop (clr += c; trans += t;).
// Sampling loop
for( int y = 0; y < sideSamples; ++y ) {
sample.y = (float(y) + 0.5f) * sideSzInv;
for( int x = 0; x < sideSamples; ++x ) {
sample.x = (float(x) + 0.5f) * sideSzInv;
if ( sampleInMask( sample, mask ) ) {
Color c, t;
// NB, returns true for unclipped samples
if (cb->SampleAtOffset( c, t, sample, sampleScale )) {
clr += c;
trans += t;
nSamples += 1.0f;
}
}
}
}
At the end of the sampling loop a check is done to see if there were zero samples. This is the case if the geometry is very small relative to the pixel. There are two approaches that one might take when there are zero samples. One is to simply return black. A strict 'jitter-type' sampler might do this since, in fact, no samples were hit. This will result in artifacts to the image however. A better approach is to use the ShadeContext method SurfacePtScreen() to return a point which is guaranteed to be at the center of the fragment. Then this point is passed to SampleAtOffset() so a single sample which is on the fragment is used.
If a single sample point was used, DoSamples() is finished. The reults are in clr and trans as returned from SampleAtOffset().
If a number of samples was taken, the Colors clr and trans are divided by the number of samples (nSamples) to get the final colors.
// Check for 0 samples
if ( nSamples == 0.0f ){
// use frag center if no other samples
sample = sc->SurfacePtScreen();
sample.x = frac(sample.x ); sample.y = frac( sample.y );
cb->SampleAtOffset( clr, trans, sample, 1.0f );
} else {
clr /= nSamples;
trans /= nSamples;
}
Prototype:
virtual int GetNSamples()=0;
Remarks:
This methods returns the integer number of samples given the current quality setting. If doing adaptive sampling (where the number of samples may vary) return the maximum number of samples possible.
Prototype:
virtual float GetQuality()=0;
Remarks:
Returns the sampling quality in the range of 0.0 to 1.0. Quality means how many samples are taken to compute the shade in a pixel. Higher quality is of course achieved by more samples. Quality 0.0 means "minimal", Quality 1.0 means "best", and Quality 0.5 means "good, the default ". Some samplers do not have adjustable quality (like 3ds max 2.5 Star), in which case the quality spinner is disabled and this method is ignored.
Prototype:
virtual void SetQuality(float value)=0;
Remarks:
Sets the sampling quality. This is the one default parameter.
Parameters:
float value
Quality is nominal with a range of 0.0 to 1.0.
Prototype:
virtual int SupportsQualityLevels()=0;
Remarks:
This method returns 0 on "unchangeable", otherwise the number of quality levels.
Prototype:
virtual BOOL GetEnable()=0;
Remarks:
Returns TRUE if sampling is enabled; otherwise FALSE.
Prototype:
virtual void SetEnable(BOOL samplingOn)=0;
Remarks:
Sets the Enable Sampler state to on or off.
Parameters:
BOOL samplingOn
TRUE for on; FALSE for off.
Prototype:
virtual TCHAR* GetDefaultComment()=0;
Remarks:
Returns a comment string for the Sampler which appears in the Materials Editor user inteface.
Prototype:
virtual SamplerParamDlg *CreateParamDialog(HWND hWndParent);
Remarks:
This method creates and puts up a pop-up modal dialog that allows editing the sampler extended parameters (if any).
Parameters:
HWND hWndParent
The window handle of the parent.
Return Value:
Points to the object to manage the dialog. Note: typedef SFXParamDlg SamplerParamDlg;
See Class SFXParamDlg.
Default Implementation:
{return NULL;}
Prototype:
virtual BOOL SetDlgThing(EffectParamDlg* dlg);
Remarks:
You should implement this method if you are using the ParamMap2 AUTO_UI system and the sampler has secondary dialogs that have something other than the incoming effect as their 'thing'. Called once for each secondary dialog for you to install the correct thing. Return TRUE if you process the dialog, FALSE otherwise, in which case the incoming effect will be set into the dialog.
Note: Developers needing more information on this method can see the remarks for MtlBase::CreateParamDlg() which describes a similar example of this method in use (in that case it's for use by a texture map plug-in).
Parameters:
EffectParamDlg* dlg
Points to the ParamDlg.
Default Implementation:
{ return FALSE; }
Prototype:
IOResult Save(ISave *isave);
Remarks:
Implemented by the System.
This method saves the name of the sampler. This should be called at the start of a plug-in's save methods.
Parameters:
ISave *isave
An interface for saving data.
Prototype:
IOResult Load(ILoad *iload);
Remarks:
Implemented by the System.
This method loads the name of the sampler. This should be called at the start of a plug-in's load methods.
Parameters:
ILoad *iload
An interface for loading data.
Optional Adaptive Sampling Methods (with default implementations)
Prototype:
virtual BOOL SupportsAdaptive();
Remarks:
Returns TRUE if the sampler is adaptive; otherwise FALSE. If this method returns TRUE the Adaptive On checkbox appears along with the Threshold spinner.
Default Implementation:
{ return FALSE; }
Prototype:
virtual ULONG SupportsStdParams();
Remarks:
This method determines which of the various optional parameters are displayed. Zero or more of the following values (which may be added together):
IS_ADAPTIVE -- Samples is adaptive in some way.
ADAPTIVE_CHECK_BOX -- Enable the Adaptive check box.
ADAPTIVE_THRESHOLD -- Enable the adaptive Threshold spinner.
SUPER_SAMPLE_TEX_CHECK_BOX -- Enable the texture Super Sampling check box.
ADVANCED_DLG_BUTTON -- Enable the Advanced button. This allows an additional popup dialog to be presented to the user. See the method ExecuteParamDialog().
OPTIONAL_PARAM_0 -- Enable optional spinner 0. See the methods GetOptionalParamName(), GetOptionalParamMax(), etc.
OPTIONAL_PARAM_1 -- Enable optional spinner 1.
The following option is simply a set of these:
R3_ADAPTIVE = (IS_ADAPTIVE+ADAPTIVE_CHECK_BOX+ADAPTIVE_THRESHOLD)
Default Implementation:
{ return 0; }
Prototype:
virtual void SetTextureSuperSampleOn(BOOL on);
Remarks:
This method is called on the Sampler to reflect the change in the 'Supersamp. Tex.' checkbox state. This determines whether to cut down the texture sample size of each sample, or whether to always use 1 pixel texture sample size.
Parameters:
BOOL on
TRUE for on; FALSE for off.
Default Implementation:
{}
Prototype:
virtual BOOL GetTextureSuperSampleOn();
Remarks:
Returns TRUE if Super Sampling is on; otherwise FALSE. See SetTextureSuperSampleOn() above.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void SetAdaptiveOn(BOOL on);
Remarks:
This method is called on the Sampler to reflect the change in the 'Adaptive' checkbox state.
Parameters:
BOOL on
TRUE for on; FALSE for off.
Default Implementation:
{}
Prototype:
virtual BOOL IsAdaptiveOn();
Remarks:
Returns TRUE if Adaptive is on (cheched in the user interface); otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void SetAdaptiveThreshold(float value);
Remarks:
This method is called on the Sampler to reflect the change in the 'Threshold' spinner.
Parameters:
float value
The value to set. Range 0-1.
Default Implementation:
{}
Prototype:
virtual float GetAdaptiveThreshold();
Remarks:
Returns the adaptive threshold setting.
Default Implementation:
{ return 0.0f; }
Optional Parameter Related Methods
Prototype:
virtual long GetNOptionalParams();
Remarks:
Samplers plug-ins support two optional parameter which may be used by the plug-in for its own needs. This methods returns the number of parameters it supports. Note that the max value is 2.
Default Implementation:
{ return 0; }
Prototype:
virtual TCHAR *GetOptionalParamName(long nParam);
Remarks:
Returns the name of the specified parameter.
Parameters:
long nParam
The zero based index of the optional parameter: 0 for the first one, 1 for the second.
Default Implementation:
{ return _T(""); }
Prototype:
virtual float GetOptionalParamMax(long nParam);
Remarks:
Returns the maximum value of the specified optional parameter.
Parameters:
long nParam
The zero based index of the optional parameter: 0 for the first one, 1 for the second.
Default Implementation:
{ return 1.0f; }
Prototype:
virtual float GetOptionalParam(long nParam);
Remarks:
Returns the value of the specified optional parameter.
Parameters:
long nParam
The zero based index of the optional parameter: 0 for the first one, 1 for the second.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual void SetOptionalParam(long nParam, float val);
Remarks:
Sets the value of the specified optional parameter.
Parameters:
long nParam
The zero based index of the optional parameter: 0 for the first one, 1 for the second.
float val
The value to set.
Default Implementation:
{}
Prototype:
virtual void ExecuteParamDialog(HWND hWndParent, StdMat2* mtl);
Remarks:
This method is called to put up a modal dialog which allows editing of the extended parameters. The rest of the operation of 3ds max should be disalbed by this modal dialog (which is why you should use GetMAXHWnd()). This method is called when the Advanced button is pressed (which is enabled by using the ADVANCED_DLG_BUTTON flag returned from SupportsStdParams().
Parameters:
HWND hWndParent
The parent window handle. Use Interface::GetMAXHWnd().
StdMat2* mtl
Points to the owning Standard material.
Default Implementation:
{}