HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
PI_OpHandleLink.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: PI_OpHandleLink.h (PI Library, C++)
7  *
8  * COMMENTS:
9  *
10  * PI base class.
11  */
12 
13 #ifndef __PI_OpHandleLink__
14 #define __PI_OpHandleLink__
15 
16 #include "PI_API.h"
17 #include <UT/UT_Color.h>
18 #include <UT/UT_String.h>
19 #include <UT/UT_StringArray.h>
20 #include <UT/UT_IntArray.h>
21 #include <UT/UT_SymbolTable.h>
22 #include <UT/UT_UndoManager.h>
23 #include <UT/UT_ValArray.h>
24 #include <UT/UT_VectorTypes.h>
25 #include <PRM/PRM_ChanState.h>
26 #include <PRM/PRM_Value.h>
27 #include <OP/OP_Value.h>
28 #include <iosfwd>
29 
30 #include <functional>
31 
32 #include "PI_ResourceTemplate.h"
33 #include "PI_ResourceManager.h"
34 
35 #define PI_SETTING_SHOWOPPATH "showoppath"
36 #define PI_SETTING_COLOR "color"
37 #define PI_SETTING_OWNEROP "ownerop"
38 #define PI_SETTING_OWNEROPGROUP "owneropgroup"
39 
40 class OP_Node;
41 class OP_Operator;
42 class CMD_Args;
43 class PI_SettingList;
44 
46 {
47 public:
48  struct LateBinding
49  {
50  // Interface to define the protocol for implementing handle late bindings
51  LateBinding() = default;
52  virtual ~LateBinding() = default;
53 
54  // read/write parm values
55  virtual bool toStateValues(PI_OpHandleLink*) = 0;
56  virtual bool toHandleValues(PI_OpHandleLink*) = 0;
57 
58  // data accessors
59  virtual int getParmValue(PI_OpHandleLink const* pi, int pindex, int &val, int d=0) const = 0;
60  virtual int getParmValue(PI_OpHandleLink const* pi, int pindex, fpreal &val, fpreal d) const = 0;
61  virtual int getParmValue(PI_OpHandleLink const* pi, int pindex, UT_String &val, UT_String d=0) const = 0;
62  virtual int setParmValue(PI_OpHandleLink const* pi, int pindex, fpreal value, bool setkey) = 0;
63  virtual int setParmValue(PI_OpHandleLink const* pi, int pindex, int value, bool setkey) = 0;
64  virtual int setParmValue(PI_OpHandleLink const* pi, int pindex, UT_StringRef const& value) = 0;
65  };
66 
67  PI_OpHandleLink(const PI_PITemplate &templ);
68  virtual ~PI_OpHandleLink();
69 
70  // Methods to link a handle's parameter with an op's parameter.
71  // Return 1 on success, 0 if parm name is invalid. op_type_name tells the
72  // type of operator. Do not call these methods from the class c-tor.
73  int linkOpParmToHandleParm(const char *op_type,
74  const char *handle_parm_name,
75  const char *op_parm_name);
76 
77  // Activate the underlying handle parm, typically used when dynamic handle
78  // binding is in effect (see PI_OpHandleLink::HandleBinding)
79  int activateHandleParm(int pindex);
80 
81  virtual int attach(OP_Node &node);
82  virtual int detach(OP_Node &node);
83  virtual void detachAll();
84 
85  void attachForKeyframe(OP_Node &node);
86  void detachForKeyframe(OP_Node &node);
87  void detachAllForKeyframe();
88 
89  // Hide all handle parameter parts except for the ones from handle_parms
90  // (starting from index `beg`).
91  void isolateHandleParms(int beg,
92  const UT_StringArray& handle_parms);
93 
94  void setShowOpPath(bool onoff);
95  virtual bool getShowOpPath() const;
96 
97  // The root description is the description for the PI that is set
98  // in the binding. Then the name of the first attached operator may
99  // be appended by the buildDecription function (which calls
100  // the virtual descriptionChanged in case a subclass needs to do
101  // something in responds to a description change).
102  void setRootDescription(const char *description);
103  const char *getRootDescription() const;
104  void buildDescription();
105  const char *getDescription() const;
106  virtual void descriptionChanged();
107 
108  // The time overrides are used by the Motion Path PI to manipulate other PIs
109  // to modify parm values at a given time instead of at the current time
110  // in the animation timeline.
111  void setIsTimeOverride(bool is_time_override);
112  void setTimeOverrideTime(fpreal t);
113 
114  bool getIsTimeOverride() const
115  { return myIsTimeOverride; }
117  { return myTimeOverrideTime; }
118 
119  // Does this PI allow saving/loading from the per-op and/or last settings
120  // tables? By default, it allows using both tables.
122  { return myAllowUsingPerOpSettingsTable; }
124  { return myAllowUsingLastSettingsTable; }
126  { return myAllowUsingOpTypeSettings; }
128  { return myAllowUsingLastVisibilitySetting; }
129 
130  // When saving settings for this PI to the last settings table, we
131  // often only want PI's of this type to use these settings when they're
132  // attached to a specific type of operator. For example, the "xform"
133  // PI can be attached to many different types of sops. However, we
134  // don't want the last "xform" settings for the "copy" sop to be used
135  // the next time we put down an "xform" sop. This method returns that
136  // type of operator, if there are any restrictions, or null if there are
137  // no restrictions. The PI must be attached to at least one op when
138  // this method is called. By default, it returns null if this PI is
139  // attached to more than one op, or the type of the op if it is attached
140  // to exactly one. This method will also always return null if the
141  // myAllowUsingOpTypeSettings flag is false.
142  OP_Operator *lastSettingsOperatorTypeRestriction() const;
143 
144  // Return the op to which we're attached, or nil if we're detached.
145  OP_Node *getOpNode(int opnum = 0) const;
146  int getNumOps() const;
147  OP_Node *getKeyframeOpNode(int opnum = 0) const;
148  int getKeyframeNumOps() const;
149 
150  // Find out if we contain this node:
151  int hasOpNode(const OP_Node &node) const;
152  int hasKeyframeOpNode(const OP_Node &node) const;
153  OP_Node *findOpNode(int op_type, const char *op_name) const;
154 
155  // Update ourselves (and our handles) based on our ops parm values.
156  void doUpdateFromOpParms();
157 
158  // Respond to a parameter change in the op. Called from the above
159  // function.
160  virtual void handleOpNodeChange(OP_Node &node);
161  virtual void handleOpUIChange(OP_Node & /*node*/)
162  { }
163  virtual int wantsOpNodeChange(const OP_Node & /*node*/) const
164  { return 0; }
165  virtual bool flagOpNodeChangeNeeded(OP_Node & /*node*/)
166  { return false; }
167 
168  // The user can dynamically change the bindings from the textport.
169  // We need to refresh the current handle link in the viewports
170  // because it could be affected. Return 0 if this handle has no bindings
171  // left.
172  virtual int refreshBindings(int op_type, const char *op_name);
173 
174  // These id values are used by the linking mechanism to determine if
175  // the pi for a particular linked parm exists already or not.
176  void id(int i);
177  int id() const;
178 
179  // Returns a list of all parms bound to this handle.
180  const UT_StringArray &linkedParmNames(int opnum) const
181  { return *myParmNames(opnum); }
182  // These virtuals are similar to the linked... functions below.
183  // The difference is that these versions are used by the Key
184  // functions above. By ovrriding these, subclasses can make the
185  // above functions work for OP parms that are not linked to
186  // PI parms.
187  virtual const UT_StringArray &allParmNames(int opnum) const
188  { return *myParmNames(opnum); }
189 
190  // This gets the index of the operator that is actually bound
191  // to the specified index. If none is bound, -1 is returned.
192  int getOpnumForHandleParmIndex(int idx) const;
193 
194  // Query or set the active color of the PI:
195  const UT_Color &getActiveColor() const;
196  virtual void setActiveColor(const UT_Color &c);
197 
198  // Set accessibility state of the binding
199  void setBindingState(const bool active);
200 
201  virtual int isEqual(const PI_OpHandleLink &pi) const;
202  virtual int setEqual(const PI_OpHandleLink &pi);
203 
204  // An ethereal handle link is one that is invisible by nature.
205  bool ethereal(void) const;
206  const PI_PITemplate &getTemplate() const;
207 
208  int writeOptions(std::ostream &os, const char *baseCommand);
209  int runBindCommand(CMD_Args &args);
210  int runUnbindCommand(CMD_Args &args);
211 
212  // Functions used to handle menu functionality
213  void editChannels(int append_channels, int opnum=-1);
214  void findKey(int direction, int opnum=-1);
215  void setKeys(int opnum = -1,
216  int pindex_start = -1,
217  int pined_stop = -1,
218  const char *undo_str = 0);
219  void removeKeys(int opnum=-1);
220  void deleteChannels(int opnum=-1);
221  void lockParms(int opnum=-1);
222  void revertToDefaults(int opnum=-1);
223  void revertToFactoryDefaults(int opnum=-1);
224  void overwriteDefaults(int opnum=-1);
225 
226  // Load or save the settings for this PI. If specific_to_op is true
227  // in saveSettings() then the PI's settings will be saved in the per-op
228  // settings table instead of the last settings table.
229  virtual void loadSettings(const PI_SettingList &settings);
230  virtual void saveSettings(PI_SettingList &settings,
231  bool specific_to_op) const;
232 
233  // Save the settings for this PI.
234  virtual void saveSettingsToAppropriateLocation();
235 
236  // Load the settings for this PI from the per-op or last setting table.
237  // The PI _must_ be attached to its nodes when this method is called.
238  void loadSettingsFromTables(bool okay_to_use_last_settings);
239 
240  // Remove any settings this PI may have stored from the per-op and
241  // last setting tables.
242  void removeSettingsFromTables();
243 
245  {
246  public:
247  int myIndex;
249  };
250 
251  // This extracts the projection associated with this binding, if any,
252  // from the parmname. channel is set to the name of the channel
253  // which is bound.
254  static void extractProjection(UT_String &channel,
255  const char *parmname, fpreal &a, fpreal &b,
256  fpreal &c, fpreal &d);
257  static void extractChannelName(UT_String &channel,
258  const char *parmname)
259  {
260  fpreal dummy;
261  extractProjection(channel, parmname,
262  dummy, dummy,
263  dummy, dummy);
264  }
265 
266  void setLateBinding(LateBinding * binding);
267  bool hasLateBinding(LateBinding const * binding) const;
268 
269 protected:
270 
271  // Update ourselves (and our handles) based on our ops parm values.
272  virtual void updateFromOpParms(void);
273 
274  // Override this function to help decide which handles should be
275  // active when this PI is attached to an operator. This will be
276  // called if we successfully link to the given pindex.
277  //
278  // You should call the base class first and only proceed if it
279  // returns 1. I don't know the semantics of that - it's just how
280  // the old linkOpParm worked.
281  virtual int justLinked(int pindex);
282  virtual void justUnlinked(int pindex);
283 
284  virtual PI_Interest *getInputGroupInterests() const;
285 
286  // Map a handle parm name to an index, or retrieve the index by the name.
287  // Indices must be non-negative. If the parm has not been mapped,
288  // findHandleParmIndex returns -1.
289  int findHandleParmIndex(const char *h_parm_name) const;
290 
291  // These methods add/remove interests in all of a PI's input group
292  // parameters. These methods are called when a node is attached or
293  // detached from the PI. They use the array of PI_Interests
294  // returned by getInputGroupInterests().
295  void addAllInputGroupInterests(int opnum);
296  void removeAllInputGroupInterests(int opnum);
297 
298  // Convenience method for descendents to get the current time.
299  virtual fpreal getTime() const;
300 
301  // Methods to get/set the op's parameter values. If the parameter has
302  // not been linked to an op parameter, these methods return 0. Otherwise,
303  // they return 1.
304  int getParmValue(int pindex, int &val, int d=0) const;
305  int getParmValue(int pindex, fpreal &val, fpreal d=0) const;
306  int getParmValue(int pindex, UT_String &val,
307  UT_String d=0) const;
308  // Get the [pindex, pindex+3) parm values into a UT_Vector3R
309  void getParmVector3(int pindex, UT_Vector3R &v,
310  fpreal def = 0.0) const;
311 
312  int getParmInstValue(int pindex, const int *inst,
313  int &val, int d=0,
314  int nestlevel=1) const;
315  int getParmInstValue(int pindex, const int *inst,
316  fpreal &val, fpreal d=0,
317  int nestlevel=1) const;
318  int getParmInstValue(int pindex, const int *inst,
319  UT_String &val, UT_String d=0,
320  int nestlevel=1) const;
321  // Get the [pindex, pindex+3) parm values into a UT_Vector3R
322  void getParmInstVector3(int pindex, const int *inst,
323  UT_Vector3R &v,
324  fpreal def = 0.0) const;
325 
326  int setParmValue(int pindex, int val, bool addkey=false);
327  int setParmValue(int pindex, fpreal val, bool addkey=false);
328  int setParmValue(int pindex, const UT_String &val,
329  CH_StringMeaning meaning);
330  // Get the [pindex, pindex+3) parm values into a UT_Vector3R
331  void setParmVector3(int pindex, const UT_Vector3R &v);
332 
333  int setParmInstValue(int pindex, const int *inst,
334  int val, bool addkey=false,
335  int nestlevel=1);
336  int setParmInstValue(int pindex, const int *inst,
337  fpreal val, bool addkey=false,
338  int nestlevel=1);
339  int setParmInstValue(int pindex, const int *inst,
340  const UT_String &val,
341  CH_StringMeaning meaning,
342  int nestlevel=1);
343  void setParmInstVector3(int pindex, const int *inst,
344  const UT_Vector3R &v);
345 
346  int performParmCallback(int pindex, int theitem);
347 
348  int setOpParmValue(OP_Node *op, PRM_Parm *parm, int vecidx,
349  int val, bool addkey=false);
350  int setOpParmValue(OP_Node *op, PRM_Parm *parm, int vecidx,
351  fpreal val, bool addkey=false);
352  int setOpParmValue(OP_Node *op, PRM_Parm *parm, int vecidx,
353  const UT_String &val,
354  CH_StringMeaning meaning);
355 
356  // Methods to read or modify parm values given a pindex without adding keys
357  // Returns true if Parim is read/modified, otherwise false
358  bool readParm(int pindex, std::function<void(const PRM_Parm &parm,
359  int vecidx)> f);
360 
361  bool modifyParm(int pindex, std::function<void(PRM_Parm &parm,
362  int vecidx)> f);
363 
364 
365  // copies the keyframe structure of pindex_from to pindex_dest, while
366  // leaving the value of pindex_dest constant.
367  void copyKeyStructure(int pindex_dest, int pindex_from);
368 
369  // returns true if the parameter is enabled (a la disableParms())
370  bool isParmEnabled(int pindex, int opnum = 0) const;
371 
372  // returns the parameter animation state.
373  PRM_ChanState getParmState(int pindex, int opnum = 0) const;
374 
375  // Functions to access the parameter index arrays.
376  int getLinkedParmCount() const
377  { return myParmNames.entries(); }
378 
379  // This function determines whether or not we should do an
380  // updateFromOpParms when the time changes.
381  // Returns true unless we have an input group interest, in which
382  // case the input group interest is enough to force the update,
383  // so we return false.
384  virtual int hasTimeInterest() const;
385  virtual void handleTimeChange();
386 
387  // These two functions are provided for all the PI based operations
388  // that need to manage an undo block that begins in one function
389  // but ends in another function (or another instance of the same
390  // function).
391  //
392  // However, they can only handle ONE block at a time. No nesting
393  // of calls to beginDistributedUndo!
394  void beginDistributedUndoBlock(const char *operation,
395  UT_UndoBlockType blocktype);
396  void endDistributedUndoBlock();
397 
398  // Returns true if we have called beginDistributedUndoBlock but have
399  // not yet called endDistributedUndoBlock; returns false otherwise.
400  bool inDistributedUndoBlock();
401 
402  // This virtual callback is called whenever one of our attached
403  // or attached-for-keyframe nodes is changed.
404  virtual void handleOpChange(OP_Node *op,
405  OP_EventType etype,
406  void *data);
407 
408  // Subclasses may call these methods to customize how their settings
409  // are saved.
411  { myAllowUsingPerOpSettingsTable = onoff; }
413  { myAllowUsingLastSettingsTable = onoff; }
415  { myAllowUsingOpTypeSettings = onoff; }
417  { myAllowUsingLastVisibilitySetting = onoff; }
418 
419  // Some functions for getting and setting our owner operator information.
420  // The owner operator is the operator that defines what space our handles
421  // should appear in and what SOP/group field we should be interested in.
422  virtual void setOwnerOp(const char *owner_op);
423  const UT_String &getOwnerOp() const;
424  OP_Node *getOwnerOpRelativeTo(OP_Node *node) const;
425  virtual void setOwnerOpGroup(const char *owner_op_group);
426  const UT_String &getOwnerOpGroup() const;
427 
428  // Return the channel name for our first input group interest.
429  const UT_StringHolder &getFirstInputGroupInterestName() const;
430 
431  // This helper function returns true if the parm channel_name is locked and
432  // false otherwise. This function will follow any channel references that
433  // this parm might have to determine the "true" locked status.
434  static bool isOpParmLocked(
435  const char *channel_name, OP_Node &op, fpreal time,
436  const PRM_Parm **ret_parm = NULL,
437  const OP_Node **ret_node = NULL);
438 
439  // called by derived class to update the state values bind to a handle
440  void updateStateValues();
441 
442 private:
443  int linkOpParm(const char *op_type,
444  int pindex, const char *parmname);
445  void updateParmLockStatus( OP_Node &op );
446  UT_StringArray &opParmNames(const char *op_type);
447  void addParmNames(int opnum);
448  void removeParmNames(int opnum);
449 
450  void setKeysSingleOp(int opnum, int pindex = -1,
451  UT_String *names = NULL,
452  const char *name_prefix = NULL);
453  void removeKeysSingleOp(int opnum);
454  void deleteChannelsSingleOp(int opnum);
455  void lockParmsSingleOp(int opnum);
456  void revertToDefaultsSingleOp(int opnum);
457  void revertToFactoryDefaultsSingleOp(int opnum);
458  void overwriteDefaultsSingleOp(int opnum);
459 
460  // For a given pindex, add/remove interest's in the corresponding
461  // parameter's PRM_Value.
462  int addInputGroupInterest(int pindex,
463  PRM_ValueCallback callback,
464  int opnum);
465  int removeInputGroupInterest(int pindex,
466  PRM_ValueCallback callback,
467  int opnum);
468 
469  // Callback function to make sure we always know when one of our
470  // nodes is being deleted.
471  static void handleOpChangeCallback(OP_Node *op, void *callee,
472  OP_EventType etype, void *data);
473 
474  void clearOpTypeParmNamesMap();
475 
476  // used for updating handle values from a dynamic handle binding
477  void updateHandleValues();
478 
479  const PI_PITemplate &myTemplate;
480  // This symbol table has as it's index the optype name, and as it's
481  // contents the cached UT_StringArrays which would correspond to that
482  // op's ParmNames.
483  UT_SymbolMap<UT_StringArray *> myOpTypeParmNames;
484 
485  // This is a translation from our PI parm index into the opnum.
486  UT_IntArray myOpnumForParmIndex;
487 
488  // This is indexed by the opnum and has the string array of op parms
489  // that correspond to that opnum. The index on the string array is
490  // the index into our PI parms.
491  UT_ValArray<UT_StringArray *> myParmNames;
492  UT_ValArray<OP_Node *> myOpNodes;
493  UT_ValArray<OP_Node *> myKeyframeOpNodes;
494  UT_StringArray myInputGroupInterests;
495  int myId;
496  const PI_Interest *myInterests;
497  UT_String myRootDescription;
498  UT_String myDescription;
499  UT_String myOwnerOp;
500  UT_String myOwnerOpGroup;
501 
502  UT_Color myActiveColor;
503 
504  int myDistributedUndoBlockLevel;
505  bool myAllowUsingPerOpSettingsTable;
506  bool myAllowUsingLastSettingsTable;
507  bool myAllowUsingOpTypeSettings;
508  bool myAllowUsingLastVisibilitySetting;
509  bool myShowOpPath;
510 
511  bool myIsTimeOverride;
512  fpreal myTimeOverrideTime;
513  LateBinding* myLateBinding;
514 };
515 
516 #endif
517 
CH_StringMeaning
GT_API const UT_StringHolder time
const GLdouble * v
Definition: glcorearb.h:836
IMF_EXPORT IMATH_NAMESPACE::V3f direction(const IMATH_NAMESPACE::Box2i &dataWindow, const IMATH_NAMESPACE::V2f &pixelPosition)
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1221
#define PI_API
Definition: PI_API.h:10
png_uint_32 i
Definition: png.h:2877
GLuint id
Definition: glcorearb.h:654
GLfloat f
Definition: glcorearb.h:1925
PRM_ChanState
Definition: PRM_ChanState.h:14
UT_UndoBlockType
GLboolean * data
Definition: glcorearb.h:130
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1221
void(* PRM_ValueCallback)(void *callee, void *value)
Definition: PRM_Value.h:22
GLsizei const GLfloat * value
Definition: glcorearb.h:823
double fpreal
Definition: SYS_Types.h:270
GLuint GLfloat * val
Definition: glcorearb.h:1607
OP_EventType
Definition: OP_Value.h:22