Creating Parameter Blocks

Parameter blocks are covered in detail in the Parameter Blocks section of the documentation. This section walks through the parameter block construction used by the widget how-to sample. See the file howto/objects/widget/widget.cpp .

Defining Parameter Block and Parameter Identifiers

The first step in creating a parameter block is to define identifiers for the parameter blocks and individual parameters. This is usually done by creating enumerations.

The enumerated value that identifies the different parameter block is:

enum { widget_params };

The next set of enumerated values identify the individual parameters:

enum {
  widget_size,
  widget_left,
  widget_right
};

Describing the Parameter Block

The next step in creating a parameter block is to create a parameter block descriptor. This is done using a ParamBlockDesc2. The Widget samples declares a static ParamBlockDesc2 object named widget_param_blk.

The following is the first component of the parameter block:


1    static  ParamBlockDesc2 widget_param_blk ( widget_params, _T("params"), 0, &WidgetDesc,
2        P_AUTO_CONSTRUCT + P_AUTO_UI, PBLOCK_REF,
3         //rollout
4         IDD_PANEL, IDS_PARAMS, 0, 0, NULL,
5         // params
6         widget_size,         _T("size"),         TYPE_FLOAT,     P_ANIMATABLE,     IDS_SPIN,
7            p_default,       0.1f,
8            p_range,         0.0f,1000.0f,
9            p_ui,            TYPE_SPINNER,       EDITTYPE_FLOAT, IDC_EDIT,    IDC_SPIN, 0.50f,
10           p_end,

Line 1

static  ParamBlockDesc2 widget_param_blk ( widget_params, _T("params"), 0, &WidgetDesc,

The first four arguments are required. They describe the plug-in to 3ds Max, and register a rollout control to display your parameters.

widget_params
This the parameter block ID.

_T("params")
This is a string containing a name that the parameter block uses internally.

0
This the resource ID of the localized string in the resource's string table.

&WidgetDesc
The is the address of a ClassDesc2 object that describes the plug-in.

Line 2

P_AUTO_CONSTRUCT + P_AUTO_UI, PBLOCK_REF,

The optional arguments on the second line are telling 3ds Max to automatically handle the user interface.

Lines 3-4

//rollout
IDD_PANEL, IDS_PARAMS, 0, 0, NULL,

The rollout comment points to more optional arguments.

The first argument, IDD_PANEL tells 3ds Max the resource ID of the dialog that will be displayed for the rollout. This parameter will be further discussed further below in the section dealing with setting up the user interface.
The second argument is a string table resource ID, and points to the name that will be on the rollout bar.
The rest of the parameters on the fourth line are not discussed here, see

Lines 5-10

5         // params
6         widget_size,   _T("size"), TYPE_FLOAT, P_ANIMATABLE, IDS_SPIN,
7            p_default, 0.1f,
8            p_range,   0.0f, 1000.0f,
9            p_ui,      TYPE_SPINNER, EDITTYPE_FLOAT, IDC_SIZE_EDIT, IDC_SIZE_SPIN, 0.50f,
10           p_end,

The individual parameter specification for the widget size begins after the comment. A parameter block descriptor can be a variable number of individual parameter specs, ours at this point holds only one.

To start a new parameter you will first supply the enumerated value for your parameter. In this case widget_size.
The text describing the control is next and is a string. In this case _T("size").
The argument TYPE_FLOAT tells what type of value it is. This tells 3ds Max what type of value to store internally for this control.
The argument P_ANIMATABLE, says that the parameter can be animated.
The last argument on this line, IDS_SPIN specifies a string table resource ID.
The next line contains an optional parameter tag, followed by 1 argument specifying the default value of the control.
The next line contains an optional parameter tag, followed by 2 argument specifying the range of values for the control.
The next line contains an optional parameter tag, followed by 5 arguments specifying what type of control this parameter is linked to:
- p_ui is the user interface control spec. This is followed by a variable list of arguments depending on the type of UI control specified.
- TYPE_SPINNER tells what kind of control this is.
- EDITTYPE_FLOAT tells how to display the values in the edit box that will be linked with this spinner. If we wanted to display these floating point values in inches or in the user specified system units, we would use EDITTYPE_UNIVERSE.
- IDC_SIZE_EDIT is the identifier of the edit control in the resource editor.
- IDC_SIZE_SPIN is the identifier of the spinner control in the resource editor.
- 0.5f is a increment value for the spinner. We will change this to 0.50f so we will get a better viewport response.
p_ui is the user interface control spec. This is followed by a variable list of arguments depending on the type of UI control specified.
TYPE_SPINNER tells what kind of control this is.
EDITTYPE_FLOAT tells how to display the values in the edit box that will be linked with this spinner. If we wanted to display these floating point values in inches or in the user specified system units, we would use EDITTYPE_UNIVERSE.
IDC_SIZE_EDIT is the identifier of the edit control in the resource editor.
IDC_SIZE_SPIN is the identifier of the spinner control in the resource editor.
0.5f is a increment value for the spinner. We will change this to 0.50f so we will get a better viewport response.
The parameter tag end indicates the end of the parameter description.

The rest of the parameter block describes the two other parameter: widget_left and widget_right.

    widget_left,   _T("Left"), TYPE_FLOAT, P_ANIMATABLE, IDS_SPIN,
        p_default, 0.0f,
        p_range,   0.0f,100.0f,
        p_ui,      TYPE_SPINNER, EDITTYPE_UNIVERSE,IDC_LEFT_EDIT, IDC_LEFT_SPIN, 0.50f,
        p_end,
    widget_right,  _T("Right"),  TYPE_FLOAT,     P_ANIMATABLE,     IDS_SPIN,
        p_default, 0.0f,
        p_range,   0.0f,100.0f,
        p_ui,      TYPE_SPINNER, EDITTYPE_UNIVERSE, IDC_RIGHT_EDIT,    IDC_RIGHT_SPIN, 0.50f,
        p_end,

The end of the entire parameter block is indicated by an additional p_end parameter tag.

    p_end
    );

Creating the IParamBlock2

The final step in creating a parameter block is to instantiate the IParamBlock2 object. If we set the P_AUTO_CONSTRUCT flag in the ParamBlockDesc2 constructor the construction is handled by 3ds Max. However the method ClassDesc2::MakeAutoParamBlocks() must be called in a plug-in's constructor:

Widget::Widget()
{
  WidgetDesc.MakeAutoParamBlocks(this);
}

Once 3ds Max creates the parameter block is will call Animatable::SetReference() (implemented by your plug-in) passing the parameter block as a ReferenceTarget parameter.