PRM/PRM_ParmList.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      ramin
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        PRM_ParmList.h (Parameter Library)
 *
 * COMMENTS:
 *              This class is in charge of organizing PRM_Parms.
 *              It also handles variables associated with a group
 *              of parameters.
 */

#ifndef __PRM_ParmList__
#define __PRM_ParmList__

#include "PRM_API.h"
#include <iostream.h>
#include <UT/UT_Defines.h>
#include <UT/UT_IntArray.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_SymbolTable.h>
#include <CH/CH_EventManager.h>
#include <CH/CH_Types.h>
#include <CH/CH_ExprLanguage.h>
#include "PRM_Template.h"
#include "PRM_ChanState.h"
#include "PRM_ParmOwner.h"

#define PRM_PARM_LIST_HASH_TABLE_SIZE   17

class UT_HashTable;
class UT_TokenString;
class UT_StringArray;
class CH_Collection;
class PRM_Parm;
class PRM_Multi;
class PRM_Name;
class PRM_PresetInfo;
class PRM_ParmNameMap;
class PRM_OpSharedInfo;

typedef enum {
    PRM_RALL    = 0004,         // Read, write, execute all
    PRM_WALL    = 0002,
    PRM_XALL    = 0001,
    PRM_RGRP    = 0040,         // Read, write, execute group
    PRM_WGRP    = 0020,
    PRM_XGRP    = 0010,
    PRM_RUSR    = 0400,         // Read, write, execute user
    PRM_WUSR    = 0200,
    PRM_XUSR    = 0100,

    PRM_RWXALL  = 0007,
    PRM_RWXGRP  = 0070,
    PRM_RWXUSR  = 0700,
    PRM_RWX     = 0777,

    PRM_READ_OK         = (PRM_RALL|PRM_RGRP|PRM_RUSR),
    PRM_WRITE_OK        = (PRM_WALL|PRM_WGRP|PRM_WUSR),
    PRM_EXECUTE_OK      = (PRM_XALL|PRM_XGRP|PRM_XUSR)
} PRM_Permission;

typedef float (*PRM_ORCallback)(int data_idx, float time,
                                int *tdepend, int *enable,
                                const float *new_value);

class PRM_API PRM_ParmList
{
public:
                         PRM_ParmList(PRM_Template *thetemplates,
                                      CH_Collection *thechgroupptr,
                                      PRM_ParmOwner *node,
                                      PRM_PresetInfo *presetinfo,
                                      char *optype,
                                      bool clear_channels);
                         // Constructor used to make a new parm list when
                         // loading a new PRM_Template.  This assumes that the
                         // channel collection and variables remains the same.
                         PRM_ParmList(PRM_ParmList *thesrcptr,
                                      PRM_Template *thenewtemplate,
                                      PRM_ParmOwner *node,
                                      PRM_PresetInfo *presetinfo,
                                      char *optype,
                                      bool leavedefaultsunchanged);
                        ~PRM_ParmList();


    int                  getEntries() const { return myParms.entries(); }

    // These two must be redundant now that the constructor has
    // the channel collection in it.
    void                 setChannelGroupPtr(CH_Collection *thechgroupptr);
    CH_Collection       *getChannelGroupPtr() const;

    float                findNextKey(float theoldtime);
    float                findPrevKey(float theoldtime);

    // returns 1 if all the parms in the list are at their default values
    // returns 0 otherwise
    int                  allDefaults() const;

    // This will call revertToDefaults on parms which haven't had their
    // defaults set, thereby delaying the creation of multiparm entries until
    // after we have built all our templates.
    void                 buildDelayedDefaults( bool clear_channels = true );

    PRM_Parm            *getParmPtr(const char *theparmname, int &theparmidx);
    PRM_Parm            *getParmPtr(const char *theparmname);
    const PRM_Parm      *getParmPtr(const char *theparmname) const;
    PRM_Parm            *getParmPtr(const PRM_Name &name);

    PRM_Parm            *getParmPtr(const int theindex)
                         {
                             return theindex < myParms.entries()
                                             ? myParms(theindex)
                                             : 0;
                         }
    const PRM_Parm      *getParmPtr(const int theindex) const
                         {
                             return theindex < myParms.entries()
                                             ? myParms(theindex)
                                             : 0;
                         }

    int                  getParmIndex(const PRM_Parm *parm) const;
    int                  getParmIndex(const char *parmname) const;
    PRM_Parm            *getParmPtrFromChannel(const char *channel,
                                                int *vecidx = 0);
    int                  getParmIndex(const char *channel_name, int &subidx,
                                      bool allow_alias = true) const;
    int                  getParmIndexFromChannel(const char *channel,
                                                 bool allow_alias) const;

    // Clear the dirty flags for all parameters, or query if all dirty flags
    // are clear.
    void                 clearAllDirtyFlags();
    int                  areAllFlagsClean() const;
    void                 clearAllUndoSavedFlags();

    void                 revertToDefaults(float time);

    void                 revertValuesToFactoryDefaults();

    // When the PRM_Template changes (i.e. reloading a new operator
    // definition), the new PRM_ParmList is created and then this method is
    // called to copy over any pertinent information from the old PRM_ParmList.
    void                 updateFromOldTemplate(PRM_ParmList *oldlist);
    // When the spare parameter definitions for a node changes, this function
    // is called to update the parameters to be in line with the new set of
    // templates. The old templates must still exist at this point.
    void                 updateSpareParmTemplates(PRM_Template *newtemplates,
                                                  bool leavedefaultsunchanged);

    void                 saveSingle(PRM_Parm *, ostream &os, int binary) const;
    void                 save(ostream &os, int binary, bool compiled) const;
    bool                 load(UT_IStream &is, const char *path,
                              PRM_ParmList *obsoleteparms);

    // Methods to load and save channel aliases
    void                 saveChannelAliases(ostream &os, int binary);
    bool                 loadChannelAliases(UT_IStream &is, const char *path);
    // Returns true if any of our parms have an alias and false otherwise
    bool                 hasChannelAliases() const;

    void                 clearAndDestroyChannels();
    int                  hasAnyChannels();
    int                  addChannel(const char *name);
    void                 reloadChannelPtrs();
    int                  channelPtrModified(const char *name);

    unsigned             getUserMask() const    { return myUserMask; }
    void                 setUserMask(unsigned m)
                            { myUserMask = m & PRM_RWX; }
    unsigned             getPermissions() const { return myPermissions; }
    void                 setPermissions(unsigned mask)
                            { mask &= PRM_RWX;
                              if (mask != myPermissions)
                              {
                                  myPermissions = mask;
                                  sendChangeEvent(CH_PERMISSION_CHANGED);
                              }
                            }
    unsigned             getAssetPermissionMask() const
                            { return myAssetPermissionMask; }
    void                 setAssetPermissionMask(unsigned mask)
                            { mask &= PRM_RWX;
                              if (mask != myAssetPermissionMask)
                              {
                                  myAssetPermissionMask = mask;
                                  sendChangeEvent(CH_PERMISSION_CHANGED);
                              }
                            }

    // By default, the canAccess method just tests to see if the OP is
    // writeable.
    int                  canAccess(unsigned mask=PRM_WRITE_OK,
                                    const PRM_Type &type=PRM_TYPE_ZERO) const;
    int                  canAccessIgnoringAssetMask(
                                    unsigned mask=PRM_WRITE_OK,
                                    const PRM_Type &type=PRM_TYPE_ZERO) const;
    int                  canAccessCheckingOnlyAssetMask(
                                    unsigned mask=PRM_WRITE_OK,
                                    const PRM_Type &type=PRM_TYPE_ZERO) const;

    static void          beginLoading();
    static void          endLoading();
    static bool          isLoading();

    void                 hardenChanges(float time, char forceflag = 0,
                                       const char *patt=0,
                                       CH_ChannelRefList *list=0);

    PRM_ChanState        getChanState(float time);
    void                 sendChangeEvent(CH_CHANGE_TYPE what, PRM_Parm *who=0);
    void                 setEventHandler(void *data,
                                void (*handler)(void *, CH_CHANGE_TYPE, int))
                         {
                             myEventObject = data;
                             myEventHandler = handler;
                         }
    //
    //                   If the parm list is not already flagged as time
    //                   dependent then checkTimeDependence will scan
    //                   the parms for time dependencies and return the
    //                   new time dependence flag.
    //
    //                   Note that expressions will not be flagged as time
    //                   dependent until they're evaluated.  So, if it's
    //                   possible that the channels have not been evaluated,
    //                   set evaluate_channels to true.
    //
    int                  checkTimeDependence(bool evaluate_channels = false);

    void                 setTimeDependent(int onOff)
                         { myTimeDependent=onOff;}
    void                 setCookTimeDependent(int onOff)
                         { myCookTimeDependent=onOff;}
    void                 setDataDependent(int onOff=1)
                         { myDataDependent=onOff;}

    int                  getTimeDependent() const { return myTimeDependent; }
    int                  getCookTimeDependent() const { return myCookTimeDependent; }
    int                  getDataDependent() const { return myDataDependent; }

    // the override callback is static
    static PRM_ORCallback        getORCallback(void) { return theORCallback; }
    static void                  setORCallback(PRM_ORCallback func) 
                                 { theORCallback = func; }

    void                 pushVariables();       // These should only be used
    void                 popVariables();        // by PSI for syntax reasons

    int                  findString(const char *str, bool fullword,
                                    bool usewildcards) const;
    int                  changeString(const char *from, const char *to,
                                      bool fullword);

    int                  getSendExtraEvent()    { return mySendExtraEvent; }
    void                 setSendExtraEvent()    { mySendExtraEvent = 1; }
    void                 clearSendExtraEvent()  { mySendExtraEvent = 0; }

    void                 getMagicString(UT_TokenString &string,
                                        float t, int parm_group = 1);

    void                 setUndoSavedFlag()     { myUndoSavedFlag = 1; }
    void                 setAutoTakeUndoSavedFlag()
                                        { myAutoTakeUndoSavedFlag = 1; }

    // Appends a block of multiparm instance parameters.
    void                 appendMultiParms(const PRM_Multi *multiparmowner,
                                     PRM_Template *templ, int num, bool spare,
                                     const UT_IntArray &instance,
                                     UT_PtrArray<PRM_Parm *> &newparms);

    void                 removeAndDestroyParm(int index);

    void                 insertMultiParmItem(int index, int i);
    void                 removeMultiParmItem(int index, int i);

    PRM_ParmOwner       *getParmOwner() const   { return myParmOwner; }
    PRM_PresetInfo      *getPresetInfo() const  { return myPresetInfo; }
    void                 clearParmOwner();

    // checkMultiParmInstance() will return true if the given parm name matches
    // a multi-parm instance name. If the multi-parm instance isn't created
    // yet, then it will be created before this function returns.
    bool                 checkMultiParmInstance(const char *parmname);

    // This method is used to alias a channel name to a another name
    // Returns true if successful and false otherwise.
    // NOTE: you should not need to use this directly, you should instead
    // call the OP_Node version.
    bool                 setChannelAlias(PRM_Parm &parm, int subindex,
                                         const char *chan_alias);

    int64                getMemUsage(UT_Bool onlythis) const;

    unsigned long        getAddRemoveCount() const
                            { return myAddRemoveCount; }
    void                 setAddRemoveCount(unsigned long count)
                            { myAddRemoveCount = count; }

    // Convenience functions for evaluating and setting parameters
    void                 evalStringRaw(UT_String &value,
                                       const char *pn, int vi, float t);
    void                 evalString(UT_String &value,
                                    const char *pn, int vi, float t);
    void                 setString(const UT_String &value,
                                   CH_StringMeaning meaning,
                                   const char *pn, int vi, float t,
                                   bool propagate);
    int                  evalInt(const char *pn, int vi, float t);
    void                 setInt(int value, const char *pn, int vi, float t,
                                bool propagate);
    float                evalFloat(const char *pn, int vi, float t);
    void                 setFloat(float value, const char *pn, int vi, float t,
                                  bool propagate);

    // This function removes the shared parmhash info for the specified
    // operator from the shared info table. The data will get deleted
    // as soon as the last PRM_ParmList with a pointer to the shared
    // info gets deleted.
    static void          removeOpSharedInfo(const char *optoken);
    // This functions changes the name under which some shred parm
    // hash info is stored in our table. This is done when the name
    // of an operator type changes.
    static void          renameOpSharedInfo(const char *oldoptoken,
                                            const char *newoptoken);

private:
    void                 moveMultiParmAlias(int index, int i, bool up);
    void                 loadUnknownParmNames(UT_IStream &is,
                                        UT_StringArray &names,
                                        PRM_ParmList *obsoleteparms);
    PRM_Parm            *findLoadParm(const char *name,
                                        PRM_ParmList *obsoleteparms,
                                        PRM_ParmNameMap *nmap,
                                        bool try_again=true);

    // Adopt the common parms (including animating parms) from the source.
    // Note that the source parm list will be changed.
    void                 adopt(PRM_ParmList &thesource,
                               bool leavedefaultsunchanged);
    // Adopt the valuesand other important information from one parm into
    // another. The parms don't have to be from the same PRM_ParmList, but
    // they can be. This allows this function to be used from the adopt()
    // function above, or from updateSpareParms(). Note that the source
    // parm will be changed.
    void                 adopt(PRM_Parm &dstparm, PRM_Parm &srcparm,
                               bool leavedefaultsunchanged);

    void                 adoptChannelAlias(PRM_Parm &dst_parm, 
                                           const PRM_Parm &src_parm);

    // For a set of multiparm instance templates, this function adds the
    // parm names for each instance to the parmnames table.
    void                 addInstanceParmNames(PRM_Template *templates,
                                int multistartoffset,
                                UT_IntArray &indexlist,
                                int numinstances, float t,
                                UT_SymbolTable &parmnames);

    PRM_Parm            *appendParm(PRM_Parm *parm,
                                bool spare, const PRM_Multi *multiparmowner);
    PRM_Parm            *appendParm(PRM_Template *temp, CH_Collection *ch,
                                bool spare, const PRM_Multi *multiparmowner);
    PRM_Parm            *appendParm(PRM_Parm *temp, CH_Collection *ch,
                                bool spare, const PRM_Multi *multiparmowner);
    void                 initHashTable();

    // Decrements the reference count for the specified shared parm hash
    // info,and deletes the data if it is the last reference.
    static void          removeOpSharedInfoReference(PRM_OpSharedInfo *info);


private: // data

    UT_PtrArray<PRM_Parm *>      myParms;
    UT_String                    myOpToken;
    unsigned long                myAddRemoveCount;

    // The following member data holds a pointer to shared hash tables.
    // This is a hash table of all the parameters for this op type. This
    // table is shared by all operators of this type. This implies two
    // things. First, it doesn't contain spare parms or multiparm instances.
    // Second, all operators must keep their "standard" parms always at
    // the start of myParms (before any spare or multi parms). Otherwise
    // The indexes for these parms would be different for each node.
    // NOTE: The channel table is not a list of active animated channels,
    // but a list of all possible channel names.
    PRM_OpSharedInfo            *myOpSharedInfo;
    // This is the hash table for holding the parm indices of spare parms
    // and multiparm instances for this node. It is not shared, obviously.
    // NOTE: The channel table is not a list of active animated channels,
    // but a list of all possible channel names.
    UT_HashTable                 mySpareAndMultiParmHashTable;
    UT_SymbolTable               mySpareAndMultiChannelTable;
    // This is the symbol table of channel aliases. It is also not shared,
    // as channel aliases are per-node not per-type. Because channel aliases
    // are always per-node, we don't need separate tables for regular parms
    // and spare/multi parms.
    UT_SymbolTable               myChannelAliasesTable;

    unsigned                     myPermissions;
    unsigned                     myUserMask;
    unsigned                     myAssetPermissionMask;

    CH_Collection               *myChannelGroupPtr;
    PRM_ParmOwner               *myParmOwner;
    PRM_PresetInfo              *myPresetInfo;

    // mySendExtraEvent is set whenever a parameter that has its
    // myExtraInterestFlag flag set is changed. It should be set
    // from the PRM_Parm::setValue methods and it should be cleared
    // after a OP_PRM_CHANGED or equivalent event has been sent out.
    unsigned                     myDataDependent:1,
                                 myTimeDependent:1,
                                 myCookTimeDependent:1,
                                 mySendExtraEvent:1,
                                 myUndoSavedFlag:1,
                                 myAutoTakeUndoSavedFlag:1;

    void                        (*myEventHandler)(void *, CH_CHANGE_TYPE, int);
    void                        *myEventObject;

    static PRM_ORCallback                        theORCallback;
    static float                                 theFileVersion;
    static UT_SymbolTable                        theOpHashTable;
    static int                                   thePRMLoadCount;
};

#endif

---