GB/GB_AttributeHandle.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:
 *      George ElKoura
 *      Side Effects Software, Inc.
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        GB_AttributeHandle.h (C++)
 *
 * COMMENTS:    Used to abstract the interface of dealing with attributes
 *              from their implementation.
 *
 */
#ifndef __GB_AttributeHandle_h__
#define __GB_AttributeHandle_h__

#include "GB_API.h"
#include <SYS/SYS_Types.h>
#include <UT/UT_Vector2.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_Vector4.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_Quaternion.h>

#include "GB_AttributeDefines.h"
#include "GB_GenericData.h"
#include "GB_AttributeHandleBase.h"

class UT_StringArray;
class GB_Detail;
class GB_AttributeElem;
class GB_AttributeTable;

class GB_API GB_AttributeHandle : public GB_AttributeHandleBase
{
public:
     /// Creates an empty attribute handle.
     GB_AttributeHandle();

     /// The copy constructor does not copy references to the element, only
     /// to the detail and the attribute offset.
     GB_AttributeHandle(const GB_AttributeHandle &gah);

     /// Creates a valid attribute handle.
     GB_AttributeHandle(const GB_Detail *gdp,
                        const GB_AttributeDict *dict,
                        GB_Attribute *attrib,
                        int size_in_bytes, 
                        GB_AttribType type);

    virtual ~GB_AttributeHandle();

    virtual GB_AttributeHandle  *clone() const = 0;
    virtual const char          *getName() const;

    /// Sets the element on which this attribute handle will operate
    /// The const version will set a flag and prevent you from writing data
    /// to this element.
    virtual void        setRawElement(GB_AttributeElem *element) = 0;
    virtual void        setRawElement(const GB_AttributeElem *element) = 0;

    /// Returns the number of entries in this attribute
    int                 entries() const { return myData.entries(); }

    /// The operator= does not copy references to the element, only to the
    /// detail and the attribute offset.
    virtual GB_AttributeHandle      &operator=(const GB_AttributeHandle &gah);

    /// Generic Data Accessors
    void                     setF(fpreal val, int index=0) 
                             { myData.setF(val,index); }
    fpreal                   getF(int index=0) const
                             { return myData.getF(index); }

    void                     setI(int val, int index=0)
                             { myData.setI(val, index); }
    int                      getI(int index=0) const
                             { return myData.getI(index); }

    void                     setV2(const UT_Vector2 &val, int index=0)
                             { myData.setV2(val, index); }
    UT_Vector2               getV2(int index=0) const
                             { return myData.getV2(index); }

    void                     setV3(const UT_Vector3 &val, int index=0)
                             { myData.setV3(val, index); }
    UT_Vector3               getV3(int index=0) const
                             { return myData.getV3(index); }

    void                     setV4(const UT_Vector4 &val, int index=0)
                             { myData.setV4(val, index); }
    UT_Vector4               getV4(int index=0) const
                             { return myData.getV4(index); }

    void                     setM3(const UT_Matrix3 &val, int index=0)
                             { myData.setM3(val, index); }
    UT_Matrix3               getM3(int index=0) const
                             { return myData.getM3(index); }

    void                     setM4(const UT_Matrix4 &val, int index=0)
                             { myData.setM4(val, index); }
    UT_Matrix4               getM4(int index=0) const
                             { return myData.getM4(index); }

    template<typename T> bool   import(T &result) const
                             { return myData.import(result); }

    /// p4 will return a 4th component of 1 if it does not exist
    void                     setP4(const UT_Vector4 &val, int index=0)
                             { myData.setP4(val, index); }
    UT_Vector4               getP4(int index=0) const
                             { return myData.getP4(index); }

    /// Fetch & set quaternion values.
    void                     setQ(const UT_Quaternion &val, int index=0)
                             { myData.setQ(val, index); }
    UT_Quaternion            getQ(int index=0) const
                             { return myData.getQ(index); }

    template<typename T>
    T                       *getPointer(int index=0) 
                             { return myData.getPointer<T>(index); }
    template<typename T>
    const T                 *getPointer(int index=0) const
                             { return myData.getPointer<T>(index); }

    // The {get,set}String methods return true if the attribute is a valid
    // string attribute and false otherwise.
    bool                     setString(const UT_String &str, int index=0)
                             { return myData.setString(str, index); }
    bool                     getString(UT_String &str, int index=0,
                                            bool harden=true) const   
                             { return myData.getString(str, index); }

    /// Unary arithmetic operations
    void                multiply(fpreal val) { myData.multiply(val); }
    void                setValue(fpreal val) { myData.setValue(val); }
    void                transform(const UT_Matrix4 &xform,
                                  const UT_Matrix4 &inverse,
                                  bool keeplengths=false)
                        {
                            myData.transform(xform, inverse, keeplengths);
                        }

    /// Performs:  this = this + gah * w
    void                addScale(const GB_AttributeHandle &gah, fpreal w)
                        { myData.addScale(gah.myData, w); }

    /// Performs:  this = this * gah
    void                multiply(const GB_AttributeHandle &gah)
                        { myData.multiply(gah.myData); }
    /// Performs:  this = this / gah
    void                divide(const GB_AttributeHandle &gah)
                        { myData.divide(gah.myData); }

    /// Performs the operation this = this*(1-w) + gah*w
    void                lerp(const GB_AttributeHandle &gah, fpreal w)
                        { myData.lerp(gah.myData, w); }

    /// Copies the data from the src attribute to this attribute
    void                copyDataFrom(const GB_AttributeHandle &src)
                        { myData.copyDataFrom(src.myData); }

    /// Returns true if the data in src matches the data in this, and returns
    /// false otherwise.
    bool                equalData(const GB_AttributeHandle &src, 
                                fpreal64 tol)
                        { return myData.equalData(src.myData, tol); }

    /// Resets the value of the data to 'uninitialized'.  For most types of
    /// attributes, this is zero, for others it is -1.
    void                resetData() { myData.resetData(); }


    /// Returns true if our attribute handle is bound to a valid attribute and
    /// false otherwise.
    virtual bool        isAttributeValid() const = 0;
    virtual bool        isSourceAttributeValid() const = 0;

    /// Returns true if our attribute handle is bound to a valid attribute of
    /// type GB_ATTRIB_FLOAT or GB_ATTRIB_VECTOR.
    bool                isFloatOrVectorAttribute() const;

    /// Returns true if the attribute handle has strings defined.
    /// It's possible that the array contains 0 strings.
    bool                getDefinedStrings(UT_StringArray &list,
                                                bool harden=true) const;

    /// Returns the number of defined strings.  Will return 0 if not
    /// a string table or no defined strings.
    int                 getNumDefinedStrings() const;

    /// Returns the idxth defined string.  Returns "" if invalid.
    const char          *getDefinedString(int idx) const;

    /// Adds a string to our string table returning the index of
    /// the resulting string.  If string already is in our table, returns
    /// the existing string.
    /// Empty ("") and null strings cannot be added to the table as they
    /// are implicitly -1.
    int                  addDefinedString(const char *name);

    /// Invalidates the handle (gets rid of references to elements and details)
    virtual void        invalidate();

    /// This accessor to the GB_Attribute is not to be used.  It's only purpose
    /// is backwards compatibility with functions that have not yet been 
    /// converted to use GB_AttributeHandle instead of GB_Attribute.
    const GB_Attribute  *getAttribute() const { return myData.getAttribute(); }
    GB_Attribute        *getAttribute() { return myData.getAttribute(); }

protected:
    /// Returns true if our attribute handle is valid and false otherwise
    /// (i.e. bound to both attribute and an element)
    bool                isValid() const;
    bool                isSourceValid() const;

    friend class GB_AttributeListHandle;
    friend class GEO_AttributeHandleList;

protected:
    GB_GenericData               myData;
};

#endif

---