POP/POP_ContextData.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:
 *      Side Effects
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 */

#ifndef __POP_ContextData_h__
#define __POP_ContextData_h__

#include "POP_API.h"
#include <SYS/SYS_Math.h>
#include <UT/UT_IntArray.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_RefArray.h>
#include <GU/GU_DetailHandle.h>
#include <OP/OP_Context.h>
#include "POP_Guide.h"
#include "POP_ParticleList.h"

// ID where user variables start
#define POP_USER_VARIABLE               600
#define POP_TIMEDELTA                   0.01
#define MAX_INPUT_GEOS                  4

class GEO_PrimParticle;
class UT_SymbolTable;
class UT_HashTable;
class GU_Detail;
class POP_Node;
class OP_Network;
class CH_LocalVariable;
class PHYS_Constraint;
class POP_BlindData;
class POP_ContextDataHandle;
class pop_ContextDataHandleRef;

// The POP_GuideHandleList provides indirect references to POP_Guide objects.
typedef UT_RefArray<GU_DetailHandle> POP_GuideHandleList;

// The POP_ContextData is a class used to pass information from
// the object cooking the POP and also to pass info from POP to POP
// as cooking occurs. It contains the gdp to cook as well as lots
// of attribute info.

class POP_API POP_ContextData
{
public:
             POP_ContextData (const char *owner);
    virtual ~POP_ContextData (void);

    const char *        getName() const { return myName; }

    // These methods are mainly used by classes that cook POPs (e.g.
    // JOLT_View, SOP_Pop).
    //________________________________________________________________________

    // copyFrom() copies to this POP_ContextData, the state of another
    // POP_ContextData. It will make a new copy of the geometry.
    void                copyFrom (const POP_ContextData &data,
                                  GU_Detail* gdp = NULL);

    // cook() is used to perform cooking on the POP specified by
    // myCookPOP.
    void                cook            (OP_Context& context);

    // cookGuide() is like cook() except that it is used to recook the 
    // guide geometry only.
    void                cookGuide       (OP_Context& context);

    // reset() is used to completely reset the POP_ContextData. It should
    // be called whenever a restart of the particle system is required.
    void                reset           (POP_Node *pop,
                                         GU_Detail *gdp,
                                         const char *init,
                                         bool keepgeo,
                                         unsigned seed,
                                         bool solveimmediately);

    // frameReset() is used to reset some information on a per frame 
    // basis. It should be called before an attempt to cook a POP.
    // However, once this is set, any number of calls to cook a POP can
    // be performed assuming the underlying network does not change.
    void                frameReset      (void);

    // offsetReset() resets the attribute offsets.
    void                offsetReset     (void);

    // recacheOffset() will search for the offsets in the gdp.
    void                recacheOffset   (void);

    // getDisplayDetail() returns the GU_Detail that corresponds to the
    // passed in myDisplayPOP.
    GU_Detail*          getDisplayDetail (void) { return(myDisplayGdp); }

    //
    // Interface to manage blind data.
    //  getBlindData()  Will return the blind data associated with the POP.  If
    //                  there is no data stored for the pop, a null ptr will be
    //                  returned.
    //  addBlindData    Returns 1 if the data was added successfully to the
    //                  context data.  At this point, the context assumes
    //                  ownership of the data and may delete it from time to
    //                  time.
    //  stealBlindData  Will return the blind data for the pop and then give up
    //                  any responsiblity or ownership of the data.
    //
    POP_BlindData       *getBlindData(const POP_Node *pop) const;
    int                  addBlindData(POP_BlindData *data);
    POP_BlindData       *stealBlindData(const POP_Node *pop);

    // These methods are mainly used by POPs themselves.
    //________________________________________________________________________

    // random() returns a random number between 0-1. This should be used
    // instead of UTfastRandom() so that random numbers used within 
    // POPs are completely deterministic.
    float               random          (void);
    // This uses the same seed as random but sends the result through
    // a hash...  This is slower than random, but has the advantage
    // that succeeding calls produce values that are "more" independent
    // of each other.  Specifically, if you sample a cube, you'll get a 
    // nice distribution
    float               randomSample    (void);

    unsigned            getRandomSeed() const { return myFastRandomSeed; }

    // getPrimPart() returns the particle primitive generated by a 
    // particular POP. If this particle doesn't exist already, it
    // creates a new one.
    GEO_PrimParticle*   getPrimPart     (POP_Node* node);

    // hasPrimPart() returns whether the node already has a particle
    // primitive assigned to it.
    GEO_PrimParticle*   hasPrimPart     (POP_Node* node);

    // getGenerator() returns the POP_Node that created a particular
    // particle primitive.
    POP_Node*           getGenerator    (GEO_PrimParticle* part) const;

    // getDetail() returns the GU_Detail being processed by this
    // POP_ContextData.
    GU_Detail*          getDetail       (void) const { return(myGdp); }

    // getEventAttr() returns the event attribute.
    GB_Attribute*       getEventAttr    (void);

    // addEvent() signals that an event has occurred.
    void                addEvent        (UT_String& events, float t);

    // removeEvent() signals that an event is over.
    void                removeEvent     (UT_String& events);

    // clearAllEvents() clears any currently active events.
    void                clearAllEvents  (void);

    // cacheDetail() will cache the current gdp.
    void                cacheDetail    (POP_Node* node);

    // addToParticleList() adds a new primitive to the stored particle
    // list. This particle list is used to keep track of all particle
    // primitives to be processed for timestepping.
    void                addToParticleList (GEO_PrimParticle* part, 
                                           POP_Node* pop, int idx);

    // Reference counting, used for caching in POP_Cache (through POPNET_Node)
    // Note that when the count reaches 0, myGdp is deleted along with this, 
    // because in the POP_Cache a new gdp is created for each context data.
    void                incRef()
                        {
                            myRefCount++;
                        }
    void                decRef()
                        {
                            myRefCount--; 
                            if (!myRefCount)
                            {
                                delete myGdp;
                                delete this;
                            }
                        }

    // This method is here for the use of POPNET_Node to ensure that its
    // local contextdata has a pointer to the detail if no other method
    // has yet been called to set it.
    void                setRefDetail(GU_Detail *gdp) { myGdp = gdp; }

    /// These flags control how the pop network will cook.  They globally
    /// turn off various update rules so it is possible to, for example,
    /// only perform the velocity update, or only perform the cooking.
    bool                shouldDoReap() const { return myDoReap; }
    void                setDoReap(bool v) { myDoReap = v; }
    bool                shouldDoPrep() const { return myDoPrep; }
    void                setDoPrep(bool v) { myDoPrep = v; }
    bool                shouldDoApplyRules() const { return myDoApplyRules; }
    void                setDoApplyRules(bool v) { myDoApplyRules = v; }
    bool                shouldDoCook() const { return myDoCook; }
    void                setDoCook(bool v) { myDoCook = v; }
    bool                shouldDoCookFirst() const { return myDoCookFirst; }
    void                setDoCookFirst(bool v) { myDoCookFirst = v; }

    /// Globally affects the standard PART_STATE_SUP* flags.
    /// This should be an or of the relevant PART_STATE_SUP* flags you
    /// want suppressed in this applyRules method.
    int                 getRuleSuppression() { return myRuleSuppression; }
    void                setRuleSuppression(int suppress) { myRuleSuppression = suppress; }

    // getParticleList() returns the stored particle list.
    POP_ParticleList*   getParticleList (void) { return(&myParticleList); };

    int     getStateOffset       (void) const { return(myStateOffset); }
    int     getLifeOffset        (void) const { return(myLifeOffset); }
    int     getVelocityOffset    (void) const { return(myVelocityOffset); }
    int     getAccelOffset       (void) const { return(myAccelOffset); }
    int     getBacktrackOffset   (void) const { return(myBacktrackOffset); }

    int     getBornOffset        (void) const { return(myBornOffset); }
    int     getSourceOffset      (void) const { return(mySourceOffset); }

    int     getAlphaOffset       (void) const { return(myAlphaOffset); }
    int     getAngVelOffset      (void) const { return(myAngVelOffset); }
    int     getAttractOffset     (void) const { return(myAttractOffset); }
    int     getBounceOffset      (void) const { return(myBounceOffset); }
    int     getChargeOffset      (void) const { return(myChargeOffset); }
    int     getClingOffset       (void) const { return(myClingOffset); }
    int     getComOffset         (void) const { return(myComOffset); }
    int     getDiffuseOffset     (void) const { return(myDiffuseOffset); }
    int     getDistanceOffset    (void) const { return(myDistanceOffset); }
    int     getDragOffset        (void) const { return(myDragOffset); }
    int     getFollowOffset      (void) const { return(myFollowOffset); }
    int     getFDynamicOffset    (void) const { return(myFDynamicOffset); }
    int     getFStaticOffset     (void) const { return(myFStaticOffset); }
    int     getGenOffset         (void) const { return(myGenOffset); }
    int     getHitDiffuseOffset  (void) const { return(myHitDiffuseOffset); }
    int     getHitIDOffset       (void) const { return(myHitIDOffset); }
    int     getHitForceOffset    (void) const { return(myHitForceOffset); }
    int     getHitNormalOffset   (void) const { return(myHitNormalOffset); }
    int     getHitPosOffset      (void) const { return(myHitPosOffset); }
    int     getHitPosUVOffset    (void) const { return(myHitPosUVOffset); }
    int     getHitTimeOffset     (void) const { return(myHitTimeOffset); }
    int     getHitUVOffset       (void) const { return(myHitUVOffset); }
    int     getIDOffset          (void) const { return(myIDOffset); }
    int     getInstanceOffset    (void) const { return(myInstanceOffset); }
    int     getMassOffset        (void) const { return(myMassOffset); }
    int     getNearestOffset     (void) const { return(myNearestOffset); }
    int     getNearestDistOffset (void) const { return(myNearestDistOffset); }
    int     getNormalOffset      (void) const { return(myNormalOffset); }
    int     getNumHitOffset      (void) const { return(myNumHitOffset); }
    int     getNumProximityOffset(void) const { return(myNumProximityOffset);}
    int     getOrbitAxisOffset   (void) const { return(myOrbitAxisOffset); }
    int     getOrbitCenterOffset (void) const { return(myOrbitCenterOffset); }
    int     getOrbitOffset       (void) const { return(myOrbitOffset); }
    int     getOrbitRadiusOffset (void) const { return(myOrbitRadiusOffset); }
    int     getOrbitSpeedOffset  (void) const { return(myOrbitSpeedOffset); }
    int     getOrientOffset      (void) const { return(myOrientOffset); }
    int     getOriginOffset      (void) const { return(myOriginOffset); }
    int     getParentOffset      (void) const { return(myParentOffset); }
    int     getPosPathOffset     (void) const { return(myPosPathOffset); }
   
    int     getPosPrimOffset     (void) const { return(myPosPrimOffset); }
    int     getPosUVOffset       (void) const { return(myPosUVOffset); }
    int     getPrevVelOffset     (void) const { return(myPrevVelOffset); }
    int     getRestOffset        (void) const { return(myRestOffset); }
    int     getRotOffset         (void) const { return(myRotOffset); }
    int     getScaleOffset       (void) const { return(myScaleOffset); }
    int     getScale3Offset      (void) const { return(myScale3Offset); }
    int     getSpeedOffset       (void) const { return(mySpeedOffset); }
    int     getSpeedLimitOffset  (void) const { return(mySpeedLimitOffset); }
    int     getSpringKOffset     (void) const { return(mySpringKOffset); }
    int     getSpriteRotOffset   (void) const { return(mySpriteRotOffset); }
    int     getSpriteScaleOffset (void) const { return(mySpriteScaleOffset); }
    int     getSpriteShopOffset  (void) const { return(mySpriteShopOffset); }
    int     getSpriteUVOffset    (void) const { return(mySpriteUVOffset); }
    int     getTensionOffset     (void) const { return(myTensionOffset); }
    int     getTextureOffset     (void) const { return(myTextureOffset); }
    int     getTransOffset       (void) const { return(myTransOffset); }
    int     getTorqueOffset      (void) const { return(myTorqueOffset); }
    int     getUpOffset          (void) const { return(myUpOffset); }

    void    setAlphaOffset       (int offset) { myAlphaOffset = offset; }
    void    setAngVelOffset      (int offset) { myAngVelOffset = offset; }
    void    setAttractOffset     (int offset) { myAttractOffset = offset; }
    void    setBounceOffset      (int offset) { myBounceOffset = offset; }
    void    setChargeOffset      (int offset) { myChargeOffset = offset; }
    void    setClingOffset       (int offset) { myClingOffset = offset; }
    void    setComOffset         (int offset) { myComOffset = offset; }
    void    setDiffuseOffset     (int offset) { myDiffuseOffset = offset; }
    void    setDistanceOffset    (int offset) { myDistanceOffset = offset; }
    void    setDragOffset        (int offset) { myDragOffset = offset; }
    void    setFollowOffset      (int offset) { myFollowOffset = offset; }
    void    setFDynamicOffset    (int offset) { myFDynamicOffset = offset; }
    void    setFStaticOffset     (int offset) { myFStaticOffset = offset; }
    void    setGenOffset         (int offset) { myGenOffset = offset; }
    void    setHitDiffuseOffset  (int offset) { myHitDiffuseOffset = offset; }
    void    setHitForceOffset    (int offset) { myHitForceOffset = offset; }
    void    setHitIDOffset       (int offset) { myHitIDOffset = offset; }
    void    setHitNormalOffset   (int offset) { myHitNormalOffset = offset; }
    void    setHitPosOffset      (int offset) { myHitPosOffset = offset; }
    void    setHitPosUVOffset    (int offset) { myHitPosUVOffset = offset; }
    void    setHitTimeOffset     (int offset) { myHitTimeOffset = offset; }
    void    setHitUVOffset       (int offset) { myHitUVOffset = offset; }
    void    setIDOffset          (int offset) { myIDOffset = offset; }
    void    setInstanceOffset    (int offset) { myInstanceOffset = offset; }
    void    setMassOffset        (int offset) { myMassOffset = offset; }
    void    setNearestOffset     (int offset) { myNearestOffset = offset; }
    void    setNearestDistOffset (int offset) { myNearestDistOffset = offset; }
    void    setNormalOffset      (int offset) { myNormalOffset = offset; }
    void    setNumHitOffset      (int offset) { myNumHitOffset = offset; }
    void    setNumProximityOffset(int offset){ myNumProximityOffset=offset;}
    void    setOrbitAxisOffset   (int offset) { myOrbitAxisOffset = offset; }
    void    setOrbitCenterOffset (int offset) { myOrbitCenterOffset = offset; }
    void    setOrbitOffset       (int offset) { myOrbitOffset = offset; }
    void    setOrbitRadiusOffset (int offset) { myOrbitRadiusOffset = offset; }
    void    setOrbitSpeedOffset  (int offset) { myOrbitSpeedOffset = offset; }
    void    setOrientOffset      (int offset) { myOrientOffset = offset; }
    void    setOriginOffset      (int offset) { myOriginOffset = offset; }
    void    setParentOffset      (int offset) { myParentOffset = offset; }
    
    void    setPosPathOffset     (int offset) { myPosPathOffset = offset; }
    void    setPosPrimOffset     (int offset) { myPosPrimOffset = offset; }
    void    setPosUVOffset       (int offset) { myPosUVOffset = offset; }
    void    setPrevVelOffset     (int offset) { myPrevVelOffset = offset; }
    void    setRestOffset        (int offset) { myRestOffset = offset; }
    void    setRotOffset         (int offset) { myRotOffset = offset; }
    void    setScaleOffset       (int offset) { myScaleOffset = offset; }
    void    setScale3Offset      (int offset) { myScale3Offset = offset; }
    void    setSpeedOffset       (int offset) { mySpeedOffset = offset; }
    void    setSpeedLimitOffset  (int offset) { mySpeedLimitOffset = offset; }
    void    setSpringKOffset     (int offset) { mySpringKOffset = offset; }
    void    setSpriteRotOffset   (int offset) { mySpriteRotOffset = offset; }
    void    setSpriteScaleOffset (int offset) { mySpriteScaleOffset = offset; }
    void    setSpriteShopOffset  (int offset) { mySpriteShopOffset = offset; }
    void    setSpriteUVOffset    (int offset) { mySpriteUVOffset = offset; }
    void    setTensionOffset     (int offset) { myTensionOffset = offset; }
    void    setTextureOffset     (int offset) { myTextureOffset = offset; }
    void    setTransOffset       (int offset) { myTransOffset = offset; }
    void    setTorqueOffset      (int offset) { myTorqueOffset = offset; }
    void    setUpOffset          (int offset) { myUpOffset = offset; }

    CH_LocalVariable            *getUserVariables (void) { return myUserVars; }
    const CH_LocalVariable      *getUserVariables(void) const
                                                    { return myUserVars; }

    int     addUserVariable      (const char* name, int size, 
                                  GB_AttribType type,
                                  const void* def, const char* local = 0);

    int     isUserVariable       (int index) 
                                        { return (index >= POP_USER_VARIABLE); }

    float   getUserVariableValue (GEO_Point* ppt, int index, int thread);

    uint64  getUserVariableSerial() const { return myUserVarSerial; }

    // isGuideOnly() returns whether to cook the guide geometry only.
    int         isGuideOnly        (void) const { return myGuideOnly; }

    // nextID() returns the next integer ID to assign to birthed particles.
    int         nextID             (void);

    // bumpNumParticles() changes the number of particles in the network.
    void        bumpNumParticles   (int delta) { myNumParticles += delta; }

    // allowBirth() returns whether birthing another particle is allowed.
    int         allowBirth         (void);

    // Gets the object name for the context input
    void                 getInputGeo(UT_String &path, int index) const;
    void                 setInputGeo(const UT_String &path, int index);

    // The following method is used to append guide geometry during a cook.
    // The specified GU_DetailHandle must be pointing to a POP_Guide.
    void                 appendGuide(POP_Node *, const GU_DetailHandle &);

    // The following method is used to specify the instance guide geometry
    // during a cook.  The specified GU_DetailHandle must be pointing to a
    // POP_Guide.
    void                 setInstanceGuide(POP_Node *, const GU_DetailHandle &);

    // Methods to set or query whether the last cook (or cookGuide) call
    // changed the selection.
    bool                 getSelectionChanged() const
                                                { return mySelectionChanged; }
    void                 setSelectionChanged()  { mySelectionChanged = true; }

    // The following method is used mainly by expression functions.
    //________________________________________________________________________

    // Query the context with respect to which expression functions are to be
    // evaluated.
    static POP_ContextData      *getExpressionData(int thread);

    // Inputs
    //________________________________________________________________________

    float       myTime;                 // time 
    float       myTimeInc;              // per frame time increment
    void*       myUserData;             // user data
    int         myRemoveUnused;         // remove unused points flag 
    OP_Network* myXformObj;             // transform object
    POP_Node*   myCookPOP;              // POP to cook
    POP_Node*   myDisplayPOP;           // POP to display 
    int         myDoInfoButton;         // compute info button text
    int         myDoUpdateViewport;     // update viewport like guides.
    int         myMaxParticles;         // Maximum number of particles allowed.

    // Outputs
    //________________________________________________________________________

    // Rebuilt per cook.
    POP_GuideHandleList         myOPGuides;   // guide geometries to display
    UT_IntArray                 myGuidePOPs;  // POPs that create guide geos

    UT_PtrArray<GEO_Point*>     myInstancePoints;  
    GU_DetailHandle             myInstanceOPGuide; // handle to a POP_Guide
    int                         myInstanceGuidePOP;

    int                         myNotifyCache;

private:
    void                recacheUserOffset   (void);

    void                setupAttributes(GU_Detail *gdp);
    void                setupInitialState(GU_Detail *gdp);

    pop_ContextDataHandleRef    *getIndirectHandle();

    UT_String           myName;

    // Inputs
    int                 myGuideOnly;
#ifdef INTEL_COMPILER
        // This is a way of avoiding an internal compiler error 
        // when using Intel's compiler. In what looks like a
        // compiler bug, it does not like an array of UT_Strings
        // in this particular file.
        std::vector<UT_String> myInputPaths;
#else   
    UT_String           myInputPaths[MAX_INPUT_GEOS];
#endif

    // Rebuilt per cook.
    GU_Detail           myCacheGdp;
    GU_Detail*          myDisplayGdp;

    // State
    unsigned            myFastRandomSeed;
    UT_SymbolTable*     myPrimParts;
    UT_SymbolTable*     myGenerators;
    UT_SymbolTable*     myInitPrims;
    GU_Detail*          myGdp;
    POP_ParticleList    myParticleList;
    POP_ParticleList    myInitParticleList;
    float               myPrevTimeInc;
    bool                mySolveImmediately;
    bool                mySelectionChanged;
    int                 myNumParticles;

    // point attributes that are accessed by POPs
    int                 myAlphaOffset;
    int                 myAngVelOffset;
    int                 myAttractOffset;
    int                 myBounceOffset;
    int                 myChargeOffset;
    int                 myClingOffset;
    int                 myComOffset;
    int                 myDiffuseOffset;
    int                 myDistanceOffset;
    int                 myDragOffset;
    int                 myFollowOffset;
    int                 myFDynamicOffset;
    int                 myFStaticOffset;
    int                 myGenOffset;
    int                 myHitDiffuseOffset;
    int                 myHitForceOffset;
    int                 myHitIDOffset;
    int                 myHitNormalOffset;
    int                 myHitPosOffset;
    int                 myHitPosUVOffset;
    int                 myHitTimeOffset;
    int                 myHitUVOffset;
    int                 myIDOffset;
    int                 myInstanceOffset;
    int                 myMassOffset;
    int                 myNearestOffset;
    int                 myNearestDistOffset;
    int                 myNormalOffset;
    int                 myNumHitOffset;
    int                 myNumProximityOffset;
    int                 myOrbitAxisOffset;
    int                 myOrbitCenterOffset;
    int                 myOrbitOffset;
    int                 myOrbitRadiusOffset;
    int                 myOrbitSpeedOffset;
    int                 myOrientOffset;
    int                 myOriginOffset;
    int                 myParentOffset;
    
//  int                 myPosObjOffset;
//  int                 myPosSopOffset;
    int                 myPosPathOffset;
    
    int                 myPosPrimOffset;
    int                 myPosUVOffset;
    int                 myPrevVelOffset;
    int                 myRestOffset;
    int                 myRotOffset;
    int                 myScaleOffset;
    int                 myScale3Offset;
    int                 mySpeedOffset;
    int                 mySpeedLimitOffset;
    int                 mySpringKOffset;
    int                 mySpriteRotOffset;
    int                 mySpriteScaleOffset;
    int                 mySpriteShopOffset;
    int                 mySpriteUVOffset;
    int                 myTensionOffset;
    int                 myTextureOffset;
    int                 myTransOffset;
    int                 myTorqueOffset;
    int                 myUpOffset;

    // point attributes created in initDetail()
    int                 myVelocityOffset;
    int                 myAccelOffset;
    int                 myStateOffset;
    int                 myLifeOffset;
    int                 myBacktrackOffset;

    // primitive attributes created in initDetail()
    int                 myBornOffset;
    int                 mySourceOffset;
    int                 myGeneratorOffset;

    // Flags controlling certain timestep behaviours.  These allow
    // us to globally turn off certain rules in the POP timestepping.
    bool                myDoPrep;
    bool                myDoReap;
    bool                myDoApplyRules;
    bool                myDoCook;
    bool                myDoCookFirst;

    // Global rule overrides.  This uses the PART_STATE_SUP* flags for
    // reference.
    int                 myRuleSuppression;

    // user variables
    //________________________________________________________________________

    CH_LocalVariable*    getLocalVariable (const char* symbol);

    void                 resetUserVariables();
    // The blind data flag is:
    //  0 = bypass
    //  1 = reset handling
    //  2 = forced cleanup
    void                 resetBlindData(int forced);

    int                          myUserVarSize;
    int                          myUserVarEntries;
    CH_LocalVariable*            myUserVars;
    UT_SymbolTable*              myUserVarSymbols;
    UT_SymbolTable*              myUserVarIDs;
    uint64                       myUserVarSerial;
    UT_HashTable                *myBlindData;

    int                          myRefCount;

    pop_ContextDataHandleRef    *myIndirectHandle;

    friend class POP_ContextDataHandle;
};

inline float
POP_ContextData::random (void)
{
    return SYSfastRandom(myFastRandomSeed);
}

inline float
POP_ContextData::randomSample (void)
{
    return SYSrandom(myFastRandomSeed);
}

/// A POP_ContextDataHandle is designed to allow arms length references to a
/// POP_ContextData.  The handle is notified upon deletion of the underlying
/// data buffering any code using the handle from potentially dereferencing
/// a deleted object.  This class does not provide any sort of access control
/// to the underlying POP_ContextData, nor does it bump the reference count
/// on the POP_ContextData.  In other words, an active handle to a particular
/// POP_ContextData instance will not prevent said instance from destruction.
class POP_API POP_ContextDataHandle
{
public:
     POP_ContextDataHandle();
     POP_ContextDataHandle(const POP_ContextDataHandle &handle);
    ~POP_ContextDataHandle();

    void                         clear();
    const POP_ContextDataHandle &operator=(const POP_ContextDataHandle &handle);
    POP_ContextData             *getContextData() const;
    void                         bind(POP_ContextData *data);
private:
    void                         setHandleRef(pop_ContextDataHandleRef *handle);
    pop_ContextDataHandleRef    *myHandle;
};

/// A POP_UserVarResolveInfo caches information that can later be compared to
/// determine if local variable resolutions cached in compiled expressions may
/// no longer be valid.
class POP_API POP_UserVarResolveInfo
{
public:
    POP_UserVarResolveInfo() : mySerial(0) {}

    /// Update and return true if compiled expressions need to resolve local
    /// variables again.
    bool update(POP_ContextData *data);

private:
    POP_ContextDataHandle        myContextData;
    uint64                       mySerial;
};

#endif

---