OpenVDB: openvdb_houdini/ParmFactory.h Source File

OpenVDB 9.0.0

ParmFactory.h
Go to the documentation of this file.
1// Copyright Contributors to the OpenVDB Project
2// SPDX-License-Identifier: MPL-2.0
3//
4/// @file ParmFactory.h
5/// @author FX R&D OpenVDB team
6///
7/// @brief A collection of factory methods and helper functions
8/// to simplify Houdini plugin development and maintenance.
9
10#ifndef HOUDINI_UTILS_PARM_FACTORY_HAS_BEEN_INCLUDED
11#define HOUDINI_UTILS_PARM_FACTORY_HAS_BEEN_INCLUDED
12
13#include <GA/GA_Attribute.h>
14#include <OP/OP_AutoLockInputs.h>
15#include <OP/OP_Operator.h>
16#include <PRM/PRM_Include.h>
17#include <PRM/PRM_SpareData.h>
18#include <SOP/SOP_Node.h>
19#include <SOP/SOP_NodeVerb.h>
20#if defined(PRODDEV_BUILD) || defined(DWREAL_IS_DOUBLE)
21 // OPENVDB_HOUDINI_API, which has no meaning in a DWA build environment but
22 // must at least exist, is normally defined by including openvdb/Platform.h.
23 // For DWA builds (i.e., if either PRODDEV_BUILD or DWREAL_IS_DOUBLE exists),
24 // that introduces an unwanted and unnecessary library dependency.
25 #ifndef OPENVDB_HOUDINI_API
26 #define OPENVDB_HOUDINI_API
27 #endif
28#else
29 #include <openvdb/version.h>
30#endif
31#include <exception>
32#include <functional>
33#include <map>
34#include <memory>
35#include <string>
36#include <vector>
37
38
39#ifdef SESI_OPENVDB
40 #ifdef OPENVDB_HOUDINI_API
41 #undef OPENVDB_HOUDINI_API
42 #define OPENVDB_HOUDINI_API
43 #endif
44#endif
45
46
47class GU_Detail;
48class OP_OperatorTable;
49class PRM_Parm;
50
51 namespace houdini_utils {
52
53class ParmFactory;
54
55 using SpareDataMap = std::map<std::string, std::string>;
56
57/// @brief Return the spare data associated with the given operator.
58/// @details Only operators created with OpFactory will have spare data.
59/// @sa @link addOperatorSpareData() addOperatorSpareData@endlink,
60/// @link OpFactory::addSpareData() OpFactory::addSpareData@endlink
61 const SpareDataMap& getOperatorSpareData(const OP_Operator&);
62
63/// @brief Specify (@e key, @e value) pairs of spare data for the given operator.
64/// @details For existing keys, the new value replaces the old one.
65/// @throw std::runtime_error if the given operator does not support spare data
66/// (only operators created with OpFactory will have spare data)
67/// @sa @link getOperatorSpareData() getOperatorSpareData@endlink,
68/// @link OpFactory::addSpareData() OpFactory::addSpareData@endlink
69 void addOperatorSpareData(OP_Operator&, const SpareDataMap&);
70
71
72/// @brief Parameter template list that is always terminated.
73 class OPENVDB_HOUDINI_API ParmList
74{
75public:
76 using PrmTemplateVec = std::vector<PRM_Template>;
77
78 ParmList() {}
79
80 /// @brief Return @c true if this list contains no parameters.
81 bool empty() const { return mParmVec.empty(); }
82 /// @brief Return the number of parameters in this list.
83 /// @note Some parameter types have parameter lists of their own.
84 /// Those nested lists are not included in this count.
85 size_t size() const { return mParmVec.size(); }
86
87 /// @brief Remove all parameters from this list.
88 void clear() { mParmVec.clear(); mSwitchers.clear(); }
89
90 /// @{
91 /// @brief Add a parameter to this list.
92 ParmList& add(const PRM_Template&);
93 ParmList& add(const ParmFactory&);
94 /// @}
95
96 /// @brief Begin a collection of tabs.
97 /// @details Tabs may be nested.
98 ParmList& beginSwitcher(const std::string& token, const std::string& label = "");
99 /// @brief Begin an exclusive collection of tabs. Only one tab is "active" at a time.
100 /// @details Tabs may be nested.
101 ParmList& beginExclusiveSwitcher(const std::string& token, const std::string& label = "");
102 /// @brief End a collection of tabs.
103 /// @throw std::runtime_error if not inside a switcher or if no tabs
104 /// were added to the switcher
105 ParmList& endSwitcher();
106
107 /// @brief Add a tab with the given label to the current tab collection.
108 /// @details Parameters subsequently added to this ParmList until the next
109 /// addFolder() or endSwitcher() call will be displayed on the tab.
110 /// @throw std::runtime_error if not inside a switcher
111 ParmList& addFolder(const std::string& label);
112
113 /// Return a heap-allocated copy of this list's array of parameters.
114 PRM_Template* get() const;
115
116private:
117 struct SwitcherInfo { size_t parmIdx; std::vector<PRM_Default> folders; bool exclusive; };
118 using SwitcherStack = std::vector<SwitcherInfo>;
119
120 void incFolderParmCount();
121 SwitcherInfo* getCurrentSwitcher();
122
123 PrmTemplateVec mParmVec;
124 SwitcherStack mSwitchers;
125}; // class ParmList
126
127
128////////////////////////////////////////
129
130
131/// @class ParmFactory
132/// @brief Helper class to simplify construction of PRM_Templates and
133/// dynamic user interfaces.
134///
135/// @par Example
136/// @code
137/// houdini_utils::ParmList parms;
138///
139/// parms.add(houdini_utils::ParmFactory(PRM_STRING, "group", "Group")
140/// .setHelpText("Specify a subset of the input VDB grids to be processed.")
141/// .setChoiceList(&houdini_utils::PrimGroupMenu));
142///
143/// parms.add(houdini_utils::ParmFactory(PRM_FLT_J, "tolerance", "Pruning Tolerance")
144/// .setDefault(PRMzeroDefaults)
145/// .setRange(PRM_RANGE_RESTRICTED, 0, PRM_RANGE_UI, 1));
146/// @endcode
147 class OPENVDB_HOUDINI_API ParmFactory
148{
149public:
150 ParmFactory(PRM_Type, const std::string& token, const std::string& label);
151 ParmFactory(PRM_MultiType, const std::string& token, const std::string& label);
152
153 // Settings
154 ParmFactory& setCallbackFunc(const PRM_Callback&);
155
156 /// Specify a menu of values for this parameter.
157 ParmFactory& setChoiceList(const PRM_ChoiceList*);
158 /// @brief Specify a menu type and a list of token, label, token, label,... pairs
159 /// for this parameter.
160 /// @param typ specifies the menu behavior (toggle, replace, etc.)
161 /// @param items a list of token, label, token, label,... string pairs
162 ParmFactory& setChoiceListItems(PRM_ChoiceListType typ, const std::vector<std::string>& items);
163 /// @brief Specify a menu type and a list of token, label, token, label,... pairs
164 /// for this parameter.
165 /// @param typ specifies the menu behavior (toggle, replace, etc.)
166 /// @param items a list of token, label, token, label,... string pairs
167 /// @note The @a items array must be null-terminated.
168 ParmFactory& setChoiceListItems(PRM_ChoiceListType typ, const char* const* items);
169
170 /// @brief Specify a menu of primitive group names for this parameter.
171 ///
172 /// @param inputIndex the zero-based index of the input from which to get primitive groups
173 /// @param typ the menu behavior (toggle, replace, etc.)
174 ///
175 /// @details Calling this method with the default (toggle) behavior is equivalent
176 /// to calling @c setChoiceList(&houdini_utils::PrimGroupMenuInput1),
177 /// @c setChoiceList(&houdini_utils::PrimGroupMenuInput2), etc.
178 ///
179 /// @par Example
180 /// To limit the user to choosing a single primitive group, replace
181 /// @code
182 /// parms.add(houdini_utils::ParmFactory(PRM_STRING, "reference", "Reference")
183 /// .setChoiceList(&houdini_utils::PrimGroupMenuInput2);
184 /// @endcode
185 /// with
186 /// @code
187 /// parms.add(houdini_utils::ParmFactory(PRM_STRING, "reference", "Reference")
188 /// .setGroupChoiceList(1, PRM_CHOICELIST_REPLACE); // input index is zero based
189 /// @endcode
190 ParmFactory& setGroupChoiceList(size_t inputIndex,
191 PRM_ChoiceListType typ = PRM_CHOICELIST_TOGGLE);
192
193 /// @brief Functor to filter a list of attributes from a SOP's input
194 /// @details Arguments to the functor are an attribute to be filtered
195 /// and the parameter and SOP for which the filter is being called.
196 /// The functor should return @c true for attributes that should be added
197 /// to the list and @c false for attributes that should be ignored.
198 using AttrFilterFunc =
199 std::function<bool (const GA_Attribute&, const PRM_Parm&, const SOP_Node&)>;
200
201 /// @brief Specify a menu of attribute names for this parameter.
202 ///
203 /// @param inputIndex the zero-based index of the input from which to get attributes
204 /// @param attrOwner the class of attribute with which to populate the menu:
205 /// either per-vertex (@c GA_ATTRIB_VERTEX), per-point (@c GA_ATTRIB_POINT),
206 /// per-primitive (@c GA_ATTRIB_PRIMITIVE), global (@c GA_ATTRIB_GLOBAL),
207 /// or all of the above (@c GA_ATTRIB_INVALID or any other value)
208 /// @param typ the menu behavior (toggle, replace, etc.)
209 /// @param attrFilter an optional filter functor that returns @c true for each
210 /// attribute that should appear in the menu; the functor will be moved,
211 /// if possible, or else copied
212 ///
213 /// @note This method is supported only for SOPs.
214 ///
215 /// @par Example
216 /// Create a menu that allows multiple selection from among all the string attributes
217 /// on a SOP's first input:
218 /// @code
219 /// houdini_utils::ParmList parms;
220 /// parms.add(houdini_utils::ParmFactory(PRM_STRING, "stringattr", "String Attribute")
221 /// .setAttrChoiceList(/*input=*/0, GA_ATTRIB_INVALID, PRM_CHOICELIST_TOGGLE,
222 /// [](const GA_Attribute& attr, const PRM_Parm&, const SOP_Node&) {
223 /// return (attr.getStorageClass() == GA_STORECLASS_STRING);
224 /// }));
225 /// @endcode
226 ParmFactory& setAttrChoiceList(size_t inputIndex, GA_AttributeOwner attrOwner,
227 PRM_ChoiceListType typ = PRM_CHOICELIST_TOGGLE,
228 AttrFilterFunc attrFilter = AttrFilterFunc{});
229
230
231#if defined(GCC3)
232 #define IS_DEPRECATED __attribute__ ((deprecated))
233#elif defined(_MSC_VER)
234 #define IS_DEPRECATED __declspec(deprecated)
235#else
236 #define IS_DEPRECATED
237#endif
238
239 /// @brief Specify a menu type and either a list of menu item labels or a list of
240 /// token, label, token, label,... pairs for this parameter.
241 /// @param typ specifies the menu behavior (toggle, replace, etc.)
242 /// @param items a list of menu item labels or token, label, token, label,... pairs
243 /// @param paired if @c false, treat all the elements of @a items as labels and assign
244 /// them numeric tokens starting from zero; otherwise, treat the elements of @a items
245 /// as token, label, token, label,... pairs
246 /// @deprecated Use setChoiceListItems() instead. Using unpaired items may mean
247 /// less typing now, but it prevents you from reordering or deleting entries later.
248 IS_DEPRECATED ParmFactory& setChoiceList(PRM_ChoiceListType typ,
249 const std::vector<std::string>& items, bool paired = false);
250 /// @brief Specify a menu type and either a list of menu item labels or a list of
251 /// token, label, token, label,... pairs for this parameter.
252 /// @param typ specifies the menu behavior (toggle, replace, etc.)
253 /// @param items a list of menu item labels or token, label, token, label,... pairs
254 /// @param paired if @c false, treat all the elements of @a items as labels and assign
255 /// them numeric tokens starting from zero; otherwise, treat the elements of @a items
256 /// as token, label, token, label,... pairs
257 /// @note The @a items array must be null-terminated.
258 /// @deprecated Use setChoiceListItems() instead. Using unpaired items may mean
259 /// less typing now, but it prevents you from reordering or deleting entries later.
260 IS_DEPRECATED ParmFactory& setChoiceList(PRM_ChoiceListType typ,
261 const char* const* items, bool paired = false);
262
263#undef IS_DEPRECATED
264
265 ParmFactory& setConditional(const PRM_ConditionalBase*);
266
267 /// @brief Specify a default value for this parameter.
268 /// @details If the string is null, the floating-point value will be used
269 /// (but rounded if this parameter is integer-valued).
270 /// @note The string pointer must not point to a temporary.
271 ParmFactory& setDefault(fpreal, const char* = nullptr, CH_StringMeaning = CH_STRING_LITERAL);
272 /// @brief Specify a default string value for this parameter.
273 ParmFactory& setDefault(const std::string&, CH_StringMeaning = CH_STRING_LITERAL);
274 /// @brief Specify default numeric values for the vector elements of this parameter
275 /// (assuming its vector size is > 1).
276 /// @details Floating-point values will be rounded if this parameter is integer-valued.
277 ParmFactory& setDefault(const std::vector<fpreal>&);
278 /// @brief Specify default values for the vector elements of this parameter
279 /// (assuming its vector size is > 1).
280 ParmFactory& setDefault(const std::vector<PRM_Default>&);
281 /// Specify a default value or values for this parameter.
282 ParmFactory& setDefault(const PRM_Default*);
283
284 /// @brief Specify a plain text tooltip for this parameter.
285 /// @details This method is equivalent to setTooltip()
286 ParmFactory& setHelpText(const char*);
287 /// @brief Specify a plain text tooltip for this parameter.
288 /// @details This method is equivalent to setHelpText()
289 ParmFactory& setTooltip(const char*);
290 /// @brief Add documentation for this parameter.
291 /// @details Pass a null pointer or an empty string to inhibit
292 /// the generation of documentation for this parameter.
293 /// @details The text is parsed as wiki markup.
294 /// See the Houdini <A HREF="http://www.sidefx.com/docs/houdini/help/format">
295 /// Wiki Markup Reference</A> for the syntax.
296 ParmFactory& setDocumentation(const char*);
297
298 ParmFactory& setParmGroup(int);
299
300 /// Specify a range for this parameter's values.
301 ParmFactory& setRange(
302 PRM_RangeFlag minFlag, fpreal minVal,
303 PRM_RangeFlag maxFlag, fpreal maxVal);
304 /// @brief Specify range for the values of this parameter's vector elements
305 /// (assuming its vector size is > 1).
306 ParmFactory& setRange(const std::vector<PRM_Range>&);
307 /// Specify a range or ranges for this parameter's values.
308 ParmFactory& setRange(const PRM_Range*);
309
310 /// Specify (@e key, @e value) pairs of spare data for this parameter.
311 ParmFactory& setSpareData(const SpareDataMap&);
312 /// Specify spare data for this parameter.
313 ParmFactory& setSpareData(const PRM_SpareData*);
314
315 /// @brief Specify the list of parameters for each instance of a multiparm.
316 /// @note This setting is ignored for non-multiparm parameters.
317 /// @note Parameter name tokens should include a '#' character.
318 ParmFactory& setMultiparms(const ParmList&);
319
320 /// Specify an extended type for this parameter.
321 ParmFactory& setTypeExtended(PRM_TypeExtended);
322
323 /// @brief Specify the number of vector elements for this parameter.
324 /// @details (The default vector size is one element.)
325 ParmFactory& setVectorSize(int);
326
327 /// @brief Mark this parameter as hidden from the UI.
328 /// @note Marking parameters as obsolete is preferable to making them invisible as changing
329 /// invisible parameter values will still trigger a re-cook, however this is not possible
330 /// when using multi-parms.
331 ParmFactory& setInvisible();
332
333 /// Construct and return the parameter template.
334 PRM_Template get() const;
335
336private:
337 struct Impl;
338 std::shared_ptr<Impl> mImpl;
339
340 // For internal use only, and soon to be removed:
341 ParmFactory& doSetChoiceList(PRM_ChoiceListType, const std::vector<std::string>&, bool);
342 ParmFactory& doSetChoiceList(PRM_ChoiceListType, const char* const* items, bool);
343}; // class ParmFactory
344
345
346////////////////////////////////////////
347
348
349class OpPolicy;
350 using OpPolicyPtr = std::shared_ptr<OpPolicy>;
351
352
353/// @brief Helper class to simplify operator registration
354///
355/// @par Example
356/// @code
357/// void
358/// newPopOperator(OP_OperatorTable* table)
359/// {
360/// houdini_utils::ParmList parms;
361///
362/// parms.add(houdini_utils::ParmFactory(PRM_STRING, "group", "Group")
363/// .setHelpText("Specify a subset of the input VDB grids to be processed.")
364/// .setChoiceList(&houdini_utils::PrimGroupMenu));
365///
366/// parms.add(...);
367///
368/// ...
369///
370/// houdini_utils::OpFactory(MyOpPolicy(), My Node",
371/// POP_DW_MyNode::factory, parms, *table, houdini_utils::OpFactory::POP)
372/// .addInput("Input geometry") // input 0 (required)
373/// .addOptionalInput("Reference geometry"); // input 1 (optional)
374/// }
375/// @endcode
376 class OPENVDB_HOUDINI_API OpFactory
377{
378public:
379 enum OpFlavor { SOP, POP, ROP, VOP, HDA };
380
381 /// @brief Return "SOP" for the SOP flavor, "POP" for the POP flavor, etc.
382 /// @details Useful in OpPolicy classes for constructing type and icon names.
383 static std::string flavorToString(OpFlavor);
384
385 /// @brief Construct a factory that on destruction registers a new operator type.
386 /// @param english the operator's UI name, as it should appear in menus
387 /// @param ctor a factory function that creates operators of this type
388 /// @param parms the parameter template list for operators of this type
389 /// @param table the registry to which to add this operator type
390 /// @param flavor the operator's class (SOP, POP, etc.)
391 /// @details @c OpPolicyType specifies the type of OpPolicy to be used to control
392 /// the factory's behavior. The (unused) @c OpPolicyType argument is required
393 /// to enable the compiler to infer the type of the template argument
394 /// (there is no other way to invoke a templated constructor).
395 template<typename OpPolicyType>
396 OpFactory(const OpPolicyType& /*unused*/, const std::string& english,
397 OP_Constructor ctor, ParmList& parms, OP_OperatorTable& table, OpFlavor flavor = SOP)
398 {
399 this->init(OpPolicyPtr(new OpPolicyType), english, ctor, parms, table, flavor);
400 }
401
402 /// @note Factories initialized with this constructor use the DWAOpPolicy.
403 OpFactory(const std::string& english, OP_Constructor ctor,
404 ParmList& parms, OP_OperatorTable& table, OpFlavor flavor = SOP);
405
406 /// Register the operator.
407#if OPENVDB_ABI_VERSION_NUMBER >= 7
408 virtual ~OpFactory();
409#else
410 ~OpFactory();
411#endif
412
413 OpFactory(const OpFactory&) = delete;
414 OpFactory& operator=(const OpFactory&) = delete;
415
416 /// @brief Return the new operator's flavor (SOP, POP, etc.).
417 /// @details This accessor is mainly for use by OpPolicy objects.
418 OpFlavor flavor() const;
419 /// @brief Return the new operator's flavor as a string ("SOP", "POP", etc.).
420 /// @details This accessor is mainly for use by OpPolicy objects.
421 std::string flavorString() const;
422 /// @brief Return the new operator's type name.
423 /// @details This accessor is mainly for use by OpPolicy objects.
424 const std::string& name() const;
425 /// @brief Return the new operator's UI name.
426 /// @details This accessor is mainly for use by OpPolicy objects.
427 const std::string& english() const;
428 /// @brief Return the new operator's icon name.
429 /// @details This accessor is mainly for use by OpPolicy objects.
430 const std::string& iconName() const;
431 /// @brief Return the new operator's help URL.
432 /// @details This accessor is mainly for use by OpPolicy objects.
433 /// @note A help URL takes precedence over help text.
434 /// @sa helpText(), setHelpText()
435 const std::string& helpURL() const;
436 /// @brief Return the new operator's documentation.
437 /// @note If the help URL is nonempty, the URL takes precedence over any help text.
438 /// @sa helpURL(), setDocumentation()
439 const std::string& documentation() const;
440 /// @brief Return the operator table with which this factory is associated.
441 /// @details This accessor is mainly for use by OpPolicy objects.
442 const OP_OperatorTable& table() const;
443
444 /// @brief Construct a type name for this operator from the given English name
445 /// and add it as an alias.
446 /// @details For backward compatibility when an operator needs to be renamed,
447 /// add the old name as an alias.
448 OpFactory& addAlias(const std::string& english);
449 /// @brief Add an alias for this operator.
450 /// @details For backward compatibility when an operator needs to be renamed,
451 /// add the old name as an alias.
452 /// @note This variant takes an operator type name rather than an English name.
453 OpFactory& addAliasVerbatim(const std::string& name);
454 /// @brief Add documentation for this operator.
455 /// @details The text is parsed as wiki markup.
456 /// @note If this factory's OpPolicy specifies a help URL, that URL
457 /// takes precedence over documentation supplied with this method.
458 OpFactory& setDocumentation(const std::string&);
459 /// Add a required input with the given name.
460 OpFactory& addInput(const std::string& name);
461 /// Add an optional input with the given name.
462 OpFactory& addOptionalInput(const std::string& name);
463 /// @brief Set the maximum number of inputs allowed by this operator.
464 /// @note It is only necessary to set this limit if there are inputs
465 /// that have not been named with addInput() or addOptionalInput().
466 OpFactory& setMaxInputs(unsigned = 9999);
467 /// Specify obsolete parameters to this operator.
468 OpFactory& setObsoleteParms(const ParmList&);
469 /// Add one or more local variables to this operator.
470 OpFactory& setLocalVariables(CH_LocalVariable*);
471 OpFactory& setFlags(unsigned);
472 OpFactory& setInternalName(const std::string& name);
473 OpFactory& setOperatorTable(const std::string& name);
474
475 /// @brief Functor that returns newly-allocated node caches
476 /// for instances of this operator
477 /// @details A node cache encapsulates a SOP's cooking logic for thread safety.
478 /// Input geometry and parameter values are baked into the cache.
479 using CacheAllocFunc = std::function<SOP_NodeCache* (void)>;
480
481 /// @brief Register this operator as a
482 /// <A HREF="http://www.sidefx.com/docs/houdini/model/compile">compilable</A>&nbsp;SOP.
483 /// @details "Verbifying" a SOP separates its input and parameter management
484 /// from its cooking logic so that cooking can be safely threaded.
485 /// @param cookMode how to initialize the output detail
486 /// @param allocator a node cache allocator for instances of this operator
487 /// @throw std::runtime_error if this operator is not a SOP
488 /// @throw std::invalid_argument if @a allocator is empty
489 OpFactory& setVerb(SOP_NodeVerb::CookMode cookMode, const CacheAllocFunc& allocator);
490
491 /// @brief Mark this node as hidden from the UI tab menu.
492 /// @details This is equivalent to using the hscript ophide method.
493 OpFactory& setInvisible();
494
495 /// @brief Specify (@e key, @e value) pairs of spare data for this operator.
496 /// @details If a key already exists, its corresponding value will be
497 /// overwritten with the new value.
498 /// @sa @link addOperatorSpareData() addOperatorSpareData@endlink,
499 /// @link getOperatorSpareData() getOperatorSpareData@endlink
500 OpFactory& addSpareData(const SpareDataMap&);
501
502protected:
503 /// @brief Return the operator table with which this factory is associated.
504 /// @details This accessor is mainly for use by derived OpFactory classes.
505 OP_OperatorTable& table();
506
507private:
508 void init(OpPolicyPtr, const std::string& english, OP_Constructor,
509 ParmList&, OP_OperatorTable&, OpFlavor);
510
511 struct Impl;
512 std::shared_ptr<Impl> mImpl;
513}; // class OpFactory
514
515
516////////////////////////////////////////
517
518
519/// @brief An OpPolicy customizes the behavior of an OpFactory.
520/// This base class specifies the required interface.
521 class OPENVDB_HOUDINI_API OpPolicy
522{
523public:
524 OpPolicy() {}
525 virtual ~OpPolicy() {}
526
527 /// @brief Return a type name for the operator defined by the given factory.
528 std::string getName(const OpFactory& factory) { return getName(factory, factory.english()); }
529
530 /// @brief Convert an English name into a type name for the operator defined by
531 /// the given factory, and return the result.
532 /// @details In this base class implementation, the operator's type name is generated
533 /// by calling @c UT_String::forceValidVariableName() on the English name.
534 /// @note This function might be called (from OpFactory::addAlias(), for example)
535 /// with an English name other than the one returned by
536 /// factory.@link OpFactory::english() english()@endlink.
537 virtual std::string getName(const OpFactory& factory, const std::string& english);
538
539 /// @brief Return an icon name for the operator defined by the given factory.
540 /// @details Return an empty string to use Houdini's default icon naming scheme.
541 virtual std::string getIconName(const OpFactory&) { return ""; }
542
543 /// @brief Return a help URL for the operator defined by the given factory.
544 virtual std::string getHelpURL(const OpFactory&) { return ""; }
545
546 /// @brief Return a label name for the operator defined by the given factory.
547 /// @details In this base class implementation, this method simply returns
548 /// factory.@link OpFactory::english() english()@endlink.
549 virtual std::string getLabelName(const OpFactory&);
550
551 /// @brief Return the inital default name of the operator.
552 /// @note An empty first name will disable, reverting to the usual rules.
553 virtual std::string getFirstName(const OpFactory&) { return ""; }
554
555 /// @brief Return the tab sub-menu path of the op.
556 /// @note An empty path will disable, reverting to the usual rules.
557 virtual std::string getTabSubMenuPath(const OpFactory&) { return ""; }
558};
559
560
561////////////////////////////////////////
562
563
564/// @brief Helper class to manage input locking.
565 class OPENVDB_HOUDINI_API ScopedInputLock
566{
567public:
568 ScopedInputLock(SOP_Node& node, OP_Context& context)
569 {
570 mLock.setNode(&node);
571 if (mLock.lock(context) >= UT_ERROR_ABORT) {
572 throw std::runtime_error("failed to lock inputs");
573 }
574 }
575 ~ScopedInputLock() {}
576
577 void markInputUnlocked(exint input) { mLock.markInputUnlocked(input); }
578
579private:
580 OP_AutoLockInputs mLock;
581};
582
583
584////////////////////////////////////////
585
586
587// Extended group name drop-down menu incorporating "@<attr>=<value" syntax
588
589 OPENVDB_HOUDINI_API extern const PRM_ChoiceList PrimGroupMenuInput1;
590 OPENVDB_HOUDINI_API extern const PRM_ChoiceList PrimGroupMenuInput2;
591 OPENVDB_HOUDINI_API extern const PRM_ChoiceList PrimGroupMenuInput3;
592 OPENVDB_HOUDINI_API extern const PRM_ChoiceList PrimGroupMenuInput4;
593
594/// @note Use this if you have more than 4 inputs, otherwise use
595/// the input specific menus instead which automatically
596/// handle the appropriate spare data settings.
597 OPENVDB_HOUDINI_API extern const PRM_ChoiceList PrimGroupMenu;
598
599
600} // namespace houdini_utils
601
602#endif // HOUDINI_UTILS_PARM_FACTORY_HAS_BEEN_INCLUDED
IS_DEPRECATED
#define IS_DEPRECATED
Definition: ParmFactory.h:236
OPENVDB_HOUDINI_API
#define OPENVDB_HOUDINI_API
Definition: Platform.h:262
houdini_utils::OpFactory
Helper class to simplify operator registration.
Definition: ParmFactory.h:377
houdini_utils::OpFactory::CacheAllocFunc
std::function< SOP_NodeCache *(void)> CacheAllocFunc
Functor that returns newly-allocated node caches for instances of this operator.
Definition: ParmFactory.h:479
houdini_utils::OpFactory::setVerb
OpFactory & setVerb(SOP_NodeVerb::CookMode cookMode, const CacheAllocFunc &allocator)
Register this operator as a compilable&#160;SOP.
houdini_utils::OpFactory::setMaxInputs
OpFactory & setMaxInputs(unsigned=9999)
Set the maximum number of inputs allowed by this operator.
houdini_utils::OpFactory::addAliasVerbatim
OpFactory & addAliasVerbatim(const std::string &name)
Add an alias for this operator.
houdini_utils::OpFactory::addSpareData
OpFactory & addSpareData(const SpareDataMap &)
Specify (key, value) pairs of spare data for this operator.
houdini_utils::OpFactory::flavorToString
static std::string flavorToString(OpFlavor)
Return "SOP" for the SOP flavor, "POP" for the POP flavor, etc.
houdini_utils::OpFactory::name
const std::string & name() const
Return the new operator's type name.
houdini_utils::OpFactory::setLocalVariables
OpFactory & setLocalVariables(CH_LocalVariable *)
Add one or more local variables to this operator.
houdini_utils::OpFactory::setDocumentation
OpFactory & setDocumentation(const std::string &)
Add documentation for this operator.
houdini_utils::OpFactory::OpFactory
OpFactory(const OpFactory &)=delete
houdini_utils::OpFactory::english
const std::string & english() const
Return the new operator's UI name.
houdini_utils::OpFactory::helpURL
const std::string & helpURL() const
Return the new operator's help URL.
houdini_utils::OpFactory::flavorString
std::string flavorString() const
Return the new operator's flavor as a string ("SOP", "POP", etc.).
houdini_utils::OpFactory::addAlias
OpFactory & addAlias(const std::string &english)
Construct a type name for this operator from the given English name and add it as an alias.
houdini_utils::OpFactory::OpFactory
OpFactory(const std::string &english, OP_Constructor ctor, ParmList &parms, OP_OperatorTable &table, OpFlavor flavor=SOP)
houdini_utils::OpFactory::addOptionalInput
OpFactory & addOptionalInput(const std::string &name)
Add an optional input with the given name.
houdini_utils::OpFactory::OpFlavor
OpFlavor
Definition: ParmFactory.h:379
houdini_utils::OpFactory::flavor
OpFlavor flavor() const
Return the new operator's flavor (SOP, POP, etc.).
houdini_utils::OpFactory::addInput
OpFactory & addInput(const std::string &name)
Add a required input with the given name.
houdini_utils::OpFactory::setFlags
OpFactory & setFlags(unsigned)
houdini_utils::OpFactory::setInvisible
OpFactory & setInvisible()
Mark this node as hidden from the UI tab menu.
houdini_utils::OpFactory::table
OP_OperatorTable & table()
Return the operator table with which this factory is associated.
houdini_utils::OpFactory::operator=
OpFactory & operator=(const OpFactory &)=delete
houdini_utils::OpFactory::setOperatorTable
OpFactory & setOperatorTable(const std::string &name)
houdini_utils::OpFactory::setObsoleteParms
OpFactory & setObsoleteParms(const ParmList &)
Specify obsolete parameters to this operator.
houdini_utils::OpFactory::OpFactory
OpFactory(const OpPolicyType &, const std::string &english, OP_Constructor ctor, ParmList &parms, OP_OperatorTable &table, OpFlavor flavor=SOP)
Construct a factory that on destruction registers a new operator type.
Definition: ParmFactory.h:396
houdini_utils::OpFactory::table
const OP_OperatorTable & table() const
Return the operator table with which this factory is associated.
houdini_utils::OpFactory::documentation
const std::string & documentation() const
Return the new operator's documentation.
houdini_utils::OpFactory::~OpFactory
virtual ~OpFactory()
Register the operator.
houdini_utils::OpFactory::iconName
const std::string & iconName() const
Return the new operator's icon name.
houdini_utils::OpFactory::setInternalName
OpFactory & setInternalName(const std::string &name)
houdini_utils::OpPolicy
An OpPolicy customizes the behavior of an OpFactory. This base class specifies the required interface...
Definition: ParmFactory.h:522
houdini_utils::OpPolicy::getIconName
virtual std::string getIconName(const OpFactory &)
Return an icon name for the operator defined by the given factory.
Definition: ParmFactory.h:541
houdini_utils::OpPolicy::getTabSubMenuPath
virtual std::string getTabSubMenuPath(const OpFactory &)
Return the tab sub-menu path of the op.
Definition: ParmFactory.h:557
houdini_utils::OpPolicy::getName
std::string getName(const OpFactory &factory)
Return a type name for the operator defined by the given factory.
Definition: ParmFactory.h:528
houdini_utils::OpPolicy::getName
virtual std::string getName(const OpFactory &factory, const std::string &english)
Convert an English name into a type name for the operator defined by the given factory,...
houdini_utils::OpPolicy::getHelpURL
virtual std::string getHelpURL(const OpFactory &)
Return a help URL for the operator defined by the given factory.
Definition: ParmFactory.h:544
houdini_utils::OpPolicy::~OpPolicy
virtual ~OpPolicy()
Definition: ParmFactory.h:525
houdini_utils::OpPolicy::OpPolicy
OpPolicy()
Definition: ParmFactory.h:524
houdini_utils::OpPolicy::getLabelName
virtual std::string getLabelName(const OpFactory &)
Return a label name for the operator defined by the given factory.
houdini_utils::OpPolicy::getFirstName
virtual std::string getFirstName(const OpFactory &)
Return the inital default name of the operator.
Definition: ParmFactory.h:553
houdini_utils::ParmFactory
Helper class to simplify construction of PRM_Templates and dynamic user interfaces.
Definition: ParmFactory.h:148
houdini_utils::ParmFactory::get
PRM_Template get() const
Construct and return the parameter template.
houdini_utils::ParmFactory::setInvisible
ParmFactory & setInvisible()
Mark this parameter as hidden from the UI.
houdini_utils::ParmFactory::setConditional
ParmFactory & setConditional(const PRM_ConditionalBase *)
houdini_utils::ParmFactory::setDefault
ParmFactory & setDefault(const std::string &, CH_StringMeaning=CH_STRING_LITERAL)
Specify a default string value for this parameter.
houdini_utils::ParmFactory::setSpareData
ParmFactory & setSpareData(const PRM_SpareData *)
Specify spare data for this parameter.
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::setVectorSize
ParmFactory & setVectorSize(int)
Specify the number of vector elements for this parameter.
houdini_utils::ParmFactory::setParmGroup
ParmFactory & setParmGroup(int)
houdini_utils::ParmFactory::setChoiceListItems
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.
houdini_utils::ParmFactory::setDefault
ParmFactory & setDefault(const PRM_Default *)
Specify a default value or values for this parameter.
houdini_utils::ParmFactory::AttrFilterFunc
std::function< bool(const GA_Attribute &, const PRM_Parm &, const SOP_Node &)> AttrFilterFunc
Functor to filter a list of attributes from a SOP's input.
Definition: ParmFactory.h:199
houdini_utils::ParmFactory::ParmFactory
ParmFactory(PRM_Type, const std::string &token, const std::string &label)
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::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.
houdini_utils::ParmFactory::setTooltip
ParmFactory & setTooltip(const char *)
Specify a plain text tooltip for this parameter.
houdini_utils::ParmFactory::setDocumentation
ParmFactory & setDocumentation(const char *)
Add documentation for this parameter.
houdini_utils::ParmFactory::setTypeExtended
ParmFactory & setTypeExtended(PRM_TypeExtended)
Specify an extended type for this parameter.
houdini_utils::ParmFactory::setChoiceList
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,...
houdini_utils::ParmFactory::setDefault
ParmFactory & setDefault(const std::vector< PRM_Default > &)
Specify default values for the vector elements of this parameter (assuming its vector size is > 1).
houdini_utils::ParmFactory::setChoiceList
ParmFactory & setChoiceList(const PRM_ChoiceList *)
Specify a menu of values for this parameter.
houdini_utils::ParmFactory::setDefault
ParmFactory & setDefault(const std::vector< fpreal > &)
Specify default numeric values for the vector elements of this parameter (assuming its vector size is...
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.
houdini_utils::ParmFactory::setHelpText
ParmFactory & setHelpText(const char *)
Specify a plain text tooltip for this parameter.
houdini_utils::ParmFactory::setChoiceListItems
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.
houdini_utils::ParmFactory::setRange
ParmFactory & setRange(const std::vector< PRM_Range > &)
Specify range for the values of this parameter's vector elements (assuming its vector size is > 1).
houdini_utils::ParmFactory::setChoiceList
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,...
houdini_utils::ParmFactory::setCallbackFunc
ParmFactory & setCallbackFunc(const PRM_Callback &)
houdini_utils::ParmFactory::setSpareData
ParmFactory & setSpareData(const SpareDataMap &)
Specify (key, value) pairs of spare data for this parameter.
houdini_utils::ParmFactory::ParmFactory
ParmFactory(PRM_MultiType, const std::string &token, const std::string &label)
houdini_utils::ParmFactory::setRange
ParmFactory & setRange(const PRM_Range *)
Specify a range or ranges for this parameter's values.
houdini_utils::ParmFactory::setMultiparms
ParmFactory & setMultiparms(const ParmList &)
Specify the list of parameters for each instance of a multiparm.
houdini_utils::ParmList
Parameter template list that is always terminated.
Definition: ParmFactory.h:74
houdini_utils::ParmList::size
size_t size() const
Return the number of parameters in this list.
Definition: ParmFactory.h:85
houdini_utils::ParmList::addFolder
ParmList & addFolder(const std::string &label)
Add a tab with the given label to the current tab collection.
houdini_utils::ParmList::ParmList
ParmList()
Definition: ParmFactory.h:78
houdini_utils::ParmList::empty
bool empty() const
Return true if this list contains no parameters.
Definition: ParmFactory.h:81
houdini_utils::ParmList::beginExclusiveSwitcher
ParmList & beginExclusiveSwitcher(const std::string &token, const std::string &label="")
Begin an exclusive collection of tabs. Only one tab is "active" at a time.
houdini_utils::ParmList::endSwitcher
ParmList & endSwitcher()
End a collection of tabs.
houdini_utils::ParmList::add
ParmList & add(const PRM_Template &)
Add a parameter to this list.
houdini_utils::ParmList::get
PRM_Template * get() const
Return a heap-allocated copy of this list's array of parameters.
houdini_utils::ParmList::clear
void clear()
Remove all parameters from this list.
Definition: ParmFactory.h:88
houdini_utils::ParmList::PrmTemplateVec
std::vector< PRM_Template > PrmTemplateVec
Definition: ParmFactory.h:76
houdini_utils::ParmList::add
ParmList & add(const ParmFactory &)
Add a parameter to this list.
houdini_utils::ParmList::beginSwitcher
ParmList & beginSwitcher(const std::string &token, const std::string &label="")
Begin a collection of tabs.
houdini_utils::ScopedInputLock
Helper class to manage input locking.
Definition: ParmFactory.h:566
houdini_utils::ScopedInputLock::ScopedInputLock
ScopedInputLock(SOP_Node &node, OP_Context &context)
Definition: ParmFactory.h:568
houdini_utils::ScopedInputLock::~ScopedInputLock
~ScopedInputLock()
Definition: ParmFactory.h:575
houdini_utils::ScopedInputLock::markInputUnlocked
void markInputUnlocked(exint input)
Definition: ParmFactory.h:577
houdini_utils
Definition: ParmFactory.h:51
houdini_utils::PrimGroupMenuInput3
OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenuInput3
houdini_utils::OpPolicyPtr
std::shared_ptr< OpPolicy > OpPolicyPtr
Definition: ParmFactory.h:350
houdini_utils::getOperatorSpareData
const SpareDataMap & getOperatorSpareData(const OP_Operator &)
Return the spare data associated with the given operator.
houdini_utils::addOperatorSpareData
void addOperatorSpareData(OP_Operator &, const SpareDataMap &)
Specify (key, value) pairs of spare data for the given operator.
houdini_utils::PrimGroupMenuInput4
OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenuInput4
houdini_utils::SpareDataMap
std::map< std::string, std::string > SpareDataMap
Definition: ParmFactory.h:55
houdini_utils::PrimGroupMenuInput1
OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenuInput1
houdini_utils::PrimGroupMenuInput2
OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenuInput2
houdini_utils::PrimGroupMenu
OPENVDB_HOUDINI_API const PRM_ChoiceList PrimGroupMenu