OpenVDB: ParmFactory Class Reference

OpenVDB 9.1.0

Public Types | Public Member Functions | List of all members
ParmFactory Class Reference

Helper class to simplify construction of PRM_Templates and dynamic user interfaces. More...

`#include <openvdb_houdini/ParmFactory.h>`

## Public Types
using | AttrFilterFunc = std::function< bool(const GA_Attribute &, const PRM_Parm &, const SOP_Node &)>
| Functor to filter a list of attributes from a SOP's input. More...

## Public Member Functions
| ParmFactory (PRM_Type, const std::string &token, const std::string &label)
| ParmFactory (PRM_MultiType, const std::string &token, const std::string &label)
ParmFactory & | setCallbackFunc (const PRM_Callback &)
ParmFactory & | setChoiceList (const PRM_ChoiceList *)
| Specify a menu of values for this parameter. More...
ParmFactory & | setChoiceListItems (PRM_ChoiceListType typ, const std::vector< std::string > &items)
| Specify a menu type and a list of token, label, token, label,... pairs for this parameter. More...
ParmFactory & | setChoiceListItems (PRM_ChoiceListType typ, const char *const *items)
| Specify a menu type and a list of token, label, token, label,... pairs for this parameter. More...
ParmFactory & | setGroupChoiceList (size_t inputIndex, PRM_ChoiceListType typ=PRM_CHOICELIST_TOGGLE)
| Specify a menu of primitive group names for this parameter. More...
ParmFactory & | setAttrChoiceList (size_t inputIndex, GA_AttributeOwner attrOwner, PRM_ChoiceListType typ=PRM_CHOICELIST_TOGGLE, AttrFilterFunc attrFilter=AttrFilterFunc{})
| Specify a menu of attribute names for this parameter. More...
ParmFactory & | setChoiceList (PRM_ChoiceListType typ, const std::vector< std::string > &items, bool paired=false)
| Specify a menu type and either a list of menu item labels or a list of token, label, token, label,... pairs for this parameter. More...
ParmFactory & | setChoiceList (PRM_ChoiceListType typ, const char *const *items, bool paired=false)
| Specify a menu type and either a list of menu item labels or a list of token, label, token, label,... pairs for this parameter. More...
ParmFactory & | setConditional (const PRM_ConditionalBase *)
ParmFactory & | setDefault (fpreal, const char *=nullptr, CH_StringMeaning=CH_STRING_LITERAL)
| Specify a default value for this parameter. More...
ParmFactory & | setDefault (const std::string &, CH_StringMeaning=CH_STRING_LITERAL)
| Specify a default string value for this parameter. More...
ParmFactory & | setDefault (const std::vector< fpreal > &)
| Specify default numeric values for the vector elements of this parameter (assuming its vector size is > 1). More...
ParmFactory & | setDefault (const std::vector< PRM_Default > &)
| Specify default values for the vector elements of this parameter (assuming its vector size is > 1). More...
ParmFactory & | setDefault (const PRM_Default *)
| Specify a default value or values for this parameter. More...
ParmFactory & | setHelpText (const char *)
| Specify a plain text tooltip for this parameter. More...
ParmFactory & | setTooltip (const char *)
| Specify a plain text tooltip for this parameter. More...
ParmFactory & | setDocumentation (const char *)
| Add documentation for this parameter. More...
ParmFactory & | setParmGroup (int)
ParmFactory & | setRange (PRM_RangeFlag minFlag, fpreal minVal, PRM_RangeFlag maxFlag, fpreal maxVal)
| Specify a range for this parameter's values. More...
ParmFactory & | setRange (const std::vector< PRM_Range > &)
| Specify range for the values of this parameter's vector elements (assuming its vector size is > 1). More...
ParmFactory & | setRange (const PRM_Range *)
| Specify a range or ranges for this parameter's values. More...
ParmFactory & | setSpareData (const SpareDataMap &)
| Specify (key, value) pairs of spare data for this parameter. More...
ParmFactory & | setSpareData (const PRM_SpareData *)
| Specify spare data for this parameter. More...
ParmFactory & | setMultiparms (const ParmList &)
| Specify the list of parameters for each instance of a multiparm. More...
ParmFactory & | setTypeExtended (PRM_TypeExtended)
| Specify an extended type for this parameter. More...
ParmFactory & | setVectorSize (int)
| Specify the number of vector elements for this parameter. More...
ParmFactory & | setInvisible ()
| Mark this parameter as hidden from the UI. More...
PRM_Template | get () const
| Construct and return the parameter template. More...

## Detailed Description

Helper class to simplify construction of PRM_Templates and dynamic user interfaces.

Example
  houdini_utils::ParmList parms;
  parms.add(houdini_utils::ParmFactory(PRM_STRING, "group", "Group")
  .setHelpText("Specify a subset of the input VDB grids to be processed.")
  .setChoiceList(&houdini_utils::PrimGroupMenu));
  parms.add(houdini_utils::ParmFactory(PRM_FLT_J, "tolerance", "Pruning Tolerance")
  .setDefault(PRMzeroDefaults)
  .setRange(PRM_RANGE_RESTRICTED, 0, PRM_RANGE_UI, 1));
  houdini_utils::ParmFactory
  Helper class to simplify construction of PRM_Templates and dynamic user interfaces.
  Definition: ParmFactory.h:148
  houdini_utils::ParmFactory::setDefault
  ParmFactory & setDefault(fpreal, const char *=nullptr, CH_StringMeaning=CH_STRING_LITERAL)
  Specify a default value for this parameter.
  houdini_utils::ParmFactory::setRange
  ParmFactory & setRange(PRM_RangeFlag minFlag, fpreal minVal, PRM_RangeFlag maxFlag, fpreal maxVal)
  Specify a range for this parameter's values.
  houdini_utils::ParmFactory::setChoiceList
  ParmFactory & setChoiceList(const PRM_ChoiceList *)
  Specify a menu of values for this parameter.
  houdini_utils::ParmFactory::setHelpText
  ParmFactory & setHelpText(const char *)
  Specify a plain text tooltip for this parameter.
  houdini_utils::ParmList
  Parameter template list that is always terminated.
  Definition: ParmFactory.h:74
  houdini_utils::ParmList::add
  ParmList & add(const PRM_Template &)
  Add a parameter to this list.
  houdini_utils::PrimGroupMenu
  OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenu

## Member Typedef Documentation

## ◆ AttrFilterFunc

using AttrFilterFunc = std::function<bool (const GA_Attribute&, const PRM_Parm&, const SOP_Node&)>

Functor to filter a list of attributes from a SOP's input.

Arguments to the functor are an attribute to be filtered and the parameter and SOP for which the filter is being called. The functor should return `true` for attributes that should be added to the list and `false` for attributes that should be ignored.

## Constructor & Destructor Documentation

## ◆ ParmFactory() [1/2]

ParmFactory | ( | PRM_Type | ,
|  | const std::string & | token,
|  | const std::string & | label
| ) |  |

## ◆ ParmFactory() [2/2]

ParmFactory | ( | PRM_MultiType | ,
|  | const std::string & | token,
|  | const std::string & | label
| ) |  |

## Member Function Documentation

## ◆ get()

PRM_Template get | ( |  | ) | const

Construct and return the parameter template.

## ◆ setAttrChoiceList()

ParmFactory & setAttrChoiceList | ( | size_t | inputIndex,
|  | GA_AttributeOwner | attrOwner,
|  | PRM_ChoiceListType | typ = `PRM_CHOICELIST_TOGGLE`,
|  | AttrFilterFunc | attrFilter = `AttrFilterFunc{}`
| ) |  |

Specify a menu of attribute names for this parameter.

Parameters

  inputIndex | the zero-based index of the input from which to get attributes
  attrOwner | the class of attribute with which to populate the menu: either per-vertex (`GA_ATTRIB_VERTEX`), per-point (`GA_ATTRIB_POINT`), per-primitive (`GA_ATTRIB_PRIMITIVE`), global (`GA_ATTRIB_GLOBAL`), or all of the above (`GA_ATTRIB_INVALID` or any other value)
  typ | the menu behavior (toggle, replace, etc.)
  attrFilter | an optional filter functor that returns `true` for each attribute that should appear in the menu; the functor will be moved, if possible, or else copied

Note
  This method is supported only for SOPs.

Example
  Create a menu that allows multiple selection from among all the string attributes on a SOP's first input:
  houdini_utils::ParmList parms;
  parms.add(houdini_utils::ParmFactory(PRM_STRING, "stringattr", "String Attribute")
  .setAttrChoiceList(/*input=*/0, GA_ATTRIB_INVALID, PRM_CHOICELIST_TOGGLE,
  [](const GA_Attribute& attr, const PRM_Parm&, const SOP_Node&) {
  return (attr.getStorageClass() == GA_STORECLASS_STRING);
  }));
  houdini_utils::ParmFactory::setAttrChoiceList
  ParmFactory & setAttrChoiceList(size_t inputIndex, GA_AttributeOwner attrOwner, PRM_ChoiceListType typ=PRM_CHOICELIST_TOGGLE, AttrFilterFunc attrFilter=AttrFilterFunc{})
  Specify a menu of attribute names for this parameter.

## ◆ setCallbackFunc()

ParmFactory & setCallbackFunc | ( | const PRM_Callback & |  | ) |

## ◆ setChoiceList() [1/3]

ParmFactory & setChoiceList | ( | const PRM_ChoiceList * |  | ) |

Specify a menu of values for this parameter.

## ◆ setChoiceList() [2/3]

ParmFactory & setChoiceList | ( | PRM_ChoiceListType | typ,
|  | const char *const * | items,
|  | bool | paired = `false`
| ) |  |

Specify a menu type and either a list of menu item labels or a list of token, label, token, label,... pairs for this parameter.

Parameters

  typ | specifies the menu behavior (toggle, replace, etc.)
  items | a list of menu item labels or token, label, token, label,... pairs
  paired | if `false`, treat all the elements of items as labels and assign them numeric tokens starting from zero; otherwise, treat the elements of items as token, label, token, label,... pairs

Note
  The items array must be null-terminated.

Deprecated:
  Use setChoiceListItems() instead. Using unpaired items may mean less typing now, but it prevents you from reordering or deleting entries later.

## ◆ setChoiceList() [3/3]

ParmFactory & setChoiceList | ( | PRM_ChoiceListType | typ,
|  | const std::vector< std::string > & | items,
|  | bool | paired = `false`
| ) |  |

Specify a menu type and either a list of menu item labels or a list of token, label, token, label,... pairs for this parameter.

Parameters

  typ | specifies the menu behavior (toggle, replace, etc.)
  items | a list of menu item labels or token, label, token, label,... pairs
  paired | if `false`, treat all the elements of items as labels and assign them numeric tokens starting from zero; otherwise, treat the elements of items as token, label, token, label,... pairs

Deprecated:
  Use setChoiceListItems() instead. Using unpaired items may mean less typing now, but it prevents you from reordering or deleting entries later.

## ◆ setChoiceListItems() [1/2]

ParmFactory & setChoiceListItems | ( | PRM_ChoiceListType | typ,
|  | const char *const * | items
| ) |  |

Specify a menu type and a list of token, label, token, label,... pairs for this parameter.

Parameters

  typ | specifies the menu behavior (toggle, replace, etc.)
  items | a list of token, label, token, label,... string pairs

Note
  The items array must be null-terminated.

## ◆ setChoiceListItems() [2/2]

ParmFactory & setChoiceListItems | ( | PRM_ChoiceListType | typ,
|  | const std::vector< std::string > & | items
| ) |  |

Specify a menu type and a list of token, label, token, label,... pairs for this parameter.

Parameters

  typ | specifies the menu behavior (toggle, replace, etc.)
  items | a list of token, label, token, label,... string pairs

## ◆ setConditional()

ParmFactory & setConditional | ( | const PRM_ConditionalBase * |  | ) |

## ◆ setDefault() [1/5]

ParmFactory & setDefault | ( | const PRM_Default * |  | ) |

Specify a default value or values for this parameter.

## ◆ setDefault() [2/5]

ParmFactory & setDefault | ( | const std::string & | ,
|  | CH_StringMeaning | = `CH_STRING_LITERAL`
| ) |  |

Specify a default string value for this parameter.

## ◆ setDefault() [3/5]

ParmFactory & setDefault | ( | const std::vector< fpreal > & |  | ) |

Specify default numeric values for the vector elements of this parameter (assuming its vector size is > 1).

Floating-point values will be rounded if this parameter is integer-valued.

## ◆ setDefault() [4/5]

ParmFactory & setDefault | ( | const std::vector< PRM_Default > & |  | ) |

Specify default values for the vector elements of this parameter (assuming its vector size is > 1).

## ◆ setDefault() [5/5]

ParmFactory & setDefault | ( | fpreal | ,
|  | const char * | = `nullptr`,
|  | CH_StringMeaning | = `CH_STRING_LITERAL`
| ) |  |

Specify a default value for this parameter.

If the string is null, the floating-point value will be used (but rounded if this parameter is integer-valued).

Note
  The string pointer must not point to a temporary.

## ◆ setDocumentation()

ParmFactory & setDocumentation | ( | const char * |  | ) |

Add documentation for this parameter.

Pass a null pointer or an empty string to inhibit the generation of documentation for this parameter.

The text is parsed as wiki markup. See the Houdini Wiki Markup Reference for the syntax.

## ◆ setGroupChoiceList()

ParmFactory & setGroupChoiceList | ( | size_t | inputIndex,
|  | PRM_ChoiceListType | typ = `PRM_CHOICELIST_TOGGLE`
| ) |  |

Specify a menu of primitive group names for this parameter.

Parameters

  inputIndex | the zero-based index of the input from which to get primitive groups
  typ | the menu behavior (toggle, replace, etc.)

Calling this method with the default (toggle) behavior is equivalent to calling `setChoiceList(&houdini_utils::PrimGroupMenuInput1)`, `setChoiceList(&houdini_utils::PrimGroupMenuInput2)`, etc.

Example
  To limit the user to choosing a single primitive group, replace
  parms.add(houdini_utils::ParmFactory(PRM_STRING, "reference", "Reference")
  .setChoiceList(&houdini_utils::PrimGroupMenuInput2);
  houdini_utils::PrimGroupMenuInput2
  OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenuInput2
  with
  parms.add(houdini_utils::ParmFactory(PRM_STRING, "reference", "Reference")
  .setGroupChoiceList(1, PRM_CHOICELIST_REPLACE); // input index is zero based
  houdini_utils::ParmFactory::setGroupChoiceList
  ParmFactory & setGroupChoiceList(size_t inputIndex, PRM_ChoiceListType typ=PRM_CHOICELIST_TOGGLE)
  Specify a menu of primitive group names for this parameter.

## ◆ setHelpText()

ParmFactory & setHelpText | ( | const char * |  | ) |

Specify a plain text tooltip for this parameter.

This method is equivalent to setTooltip()

## ◆ setInvisible()

ParmFactory & setInvisible | ( |  | ) |

Mark this parameter as hidden from the UI.

Note
  Marking parameters as obsolete is preferable to making them invisible as changing invisible parameter values will still trigger a re-cook, however this is not possible when using multi-parms.

## ◆ setMultiparms()

ParmFactory & setMultiparms | ( | const ParmList & |  | ) |

Specify the list of parameters for each instance of a multiparm.

Note
  This setting is ignored for non-multiparm parameters.
  Parameter name tokens should include a '#' character.

## ◆ setParmGroup()

ParmFactory & setParmGroup | ( | int |  | ) |

## ◆ setRange() [1/3]

ParmFactory & setRange | ( | const PRM_Range * |  | ) |

Specify a range or ranges for this parameter's values.

## ◆ setRange() [2/3]

ParmFactory & setRange | ( | const std::vector< PRM_Range > & |  | ) |

Specify range for the values of this parameter's vector elements (assuming its vector size is > 1).

## ◆ setRange() [3/3]

ParmFactory & setRange | ( | PRM_RangeFlag | minFlag,
|  | fpreal | minVal,
|  | PRM_RangeFlag | maxFlag,
|  | fpreal | maxVal
| ) |  |

Specify a range for this parameter's values.

## ◆ setSpareData() [1/2]

ParmFactory & setSpareData | ( | const PRM_SpareData * |  | ) |

Specify spare data for this parameter.

## ◆ setSpareData() [2/2]

ParmFactory & setSpareData | ( | const SpareDataMap & |  | ) |

Specify (key, value) pairs of spare data for this parameter.

## ◆ setTooltip()

ParmFactory & setTooltip | ( | const char * |  | ) |

Specify a plain text tooltip for this parameter.

This method is equivalent to setHelpText()

## ◆ setTypeExtended()

ParmFactory & setTypeExtended | ( | PRM_TypeExtended |  | ) |

Specify an extended type for this parameter.

## ◆ setVectorSize()

ParmFactory & setVectorSize | ( | int |  | ) |

Specify the number of vector elements for this parameter.

(The default vector size is one element.)