[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

General Operators

Using Parameters

Each operator contains a list of 0 or more parameters. These parameters are used to define how the operator functions. Each parameter is stored as a vector of a specific type (i.e. integer, float, or string data). If the vector size is 1, this indicates a single value.

The parameter definition gives hints as to how the parameter's UI should be represented and determines what the channel names for the animated parameters should be.

The parameter's characteristics are defined using the PRM_Template class. These are not C++ templates ; that is just an unfortunate collision in nomenclature. The constructor for this class is explained below. All parameters which default to 0 are optional parameters and do not have to be provided.

    PRM_Template(PRM_Type	 thetype,
		 int		 thevectorsize,
		 PRM_Name	*thename,
		 PRM_Default	*thedefaults = 0,
		 PRM_ChoiceList	*thechoicelistptr = 0,
		 PRM_Range	*therangeptr = 0,
		 PRM_Callback	 thecallbackfunction = 0,
		 void		*thespareptr = 0);
The type of the parameter determines what the storage format will be. It indicates whether the parameter can be animated, is represented as a color, is a filename, etc. The PRM_Type is an enumeration and not a class. Some types are fully described below.

The vectorsize determines how many data elements there are in the parameter. For example, to represent an RGB color, the vector size should be set to 3.

The name is a pointer to a PRM_Name class. The class constructor looks like this:

   PRM_Name (const char *thetoken = 0, const char *thelabel = 0);
This class contains a token and a label. The token has many purposes. It is used for saving/loading the parameter. It is also used to determine the channel names for animating parameters. Think of it as a symbolic name. Because of its uses, there are some restrictions on what can be used as a token name. It should not contain any special characters (i.e. standard C variable names should be ok), and should not contain any spaces. The label is used for UI purposes and should be as descriptive as possible (without being too long). It is the actual text that is displayed to a user.

The defaults points to an array of PRM_Default structures.

   PRM_Default(float thefloat, const char *thestring = 0);
The PRM_Default has two parts: a float and a string. For floating point parameters, if the default string is defined, then the parameter will start off being animated and have the channel expression defined by the string. Otherwise, the floating point default is used for float and integer types, while the string is used to initialize string types.

The choicelist pointer is used to set menu choices for a parameter.

The range pointer can be used to specify a range (UI limited or hard limited) for integer or floating point parameters.

The callback function allows a function to be executed if the user chooses that parameter. This is mostly used for initializing other parameters.

There are many default parameter values which are used throughout the Houdini code. You can find these defined in PRM_Shared.h. There are many names, ranges, choice lists, etc. which allow you to re-use the same code.


Parameter Types

There are many parameter types currently defined for Houdini. As stated above, the parameter type determines how the raw data for the parameter should be interpreted. Parameters types are generated by using a bit mask. Part of the mask determines the storage type, another part determines the naming conventions, other types are used to store hints about how to interpret the parameters. Any parameters types which end in _J are considered to be animated and have the channel editor available for them. Some common parameter types are listed below. For a full list, refer to PRM_Type.h.

Parameter Type Description
PRM_SWITCHER
PRM_SWITCHER_REFRESH
Used to define a page or folder tab within the parameter list. In this case, the default float values determine the number of parameters per page, while the string component specifies the title for the folder tab. The vector size of the parameter specifies the number of pages contained. The parameters directly following this parameter make up the parameters in the folder tabs.
PRM_SWITCHER_REFRESH This parameter will cause the operator to re-cook whenever the current folder is changed.
PRM_FLT
PRM_FLT_J
PRM_INT
PRM_INT_J
Non-animated and animated float/integer parameters. To create channel names, the token of the parameter name will have a number appended to it starting at one. For example, if the parameter's name token is "size", the channels will be "size1", "size2", ...
PRM_XYZ
PRM_XYZ_J
PRM_INT_XYZ
PRM_INT_XYZ_J
Non-animated and animated float/integer parameters. However, the channel names for these types will have "x", "y", "z" appended instead of numbers. For example, the translate parameter "t", is usually an XYZ parameter, yielding channel names "tx", "ty", "tz".
PRM_UVW
PRM_UVW_J
Non-animated and animated parameters which have "u", "v", "w" appended for channel names.
PRM_RGB
PRM_RGB_J
PRM_RGBA
PRM_RGBA_J
Non-animated and animated parameters which have "r", "g", "b", "a" appended for channel names.
PRM_BEGINEND
PRM_BEGINEND_J
Non-animated and animated parameters which have "begin", "end" prepended for channel names.
PRM_STARTEND
PRM_STARTEND_J
Non-animated and animated parameters which have "start" and "end" appended for channel names.
PRM_FLT_MINMAX_J
PRM_INT_MINMAX_J
PRM_ANGLE_MINMAX_J
Non-animated and animated parameters which have "min", "max" appended for channel names. The angle parameter will also have an 2-D angle jack in the UI.
PRM_TOGGLE
PRM_CROSSTOGGLE
An integer value which is represented as a boolean. The cross toggle parameter is shown as a button with a cross in it.
PRM_FILE
PRM_PICFILE
PRM_GEOFILE
PRM_RAMPFILE
These types define different file types. Each type expects a string to be used and that string will represent a file. Therefore, in the UI, there will be a file prompter available for the parameter. However, for geo files, the filter on the file prompter will be set to only show geometry files. For pictures, only image files will be displayed, etc.
PRM_STRING A simple string.

This is actually a small sample of all the parameter types available for use. For a full list of types, refer to PRM_Type.h.


Table of Contents
Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
Material & Texture | Objects | Command and Expression | Render Output |
Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
Customizing UI | Questions & Answers

Copyright © 2004 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7