GA/GA_Types.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 Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        GA_Types.h ( GA Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GA_Types__
#define __GA_Types__

#include "GA_API.h"
#include <SYS/SYS_Types.h>
#include <SYS/SYS_TypeTraits.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_IntrusivePtr.h>

// -------------------------------------------------------------
// GA Enums/Defines
// -------------------------------------------------------------
/// The GA_AttributeOwner enum is used to differentiate between the different
/// types of attribute arrays stored in a GA_Detail.  The different classes
/// represent
///   -# unique point attribute data (one per vertex on a primitive)
///   -# shared point attribute data (attributes shared multiple vertices)
///   -# per-primitive attribute data (one per primitive)
///   -# attribute data stored on the detail itself (single value)
enum GA_AttributeOwner
{
    GA_ATTRIB_VERTEX,           // Unique vertex data
    GA_ATTRIB_POINT,            // Shared vertex data
    GA_ATTRIB_PRIMITIVE,        // Primitive attribute data
    GA_ATTRIB_GLOBAL,           // Global data

    GA_ATTRIB_OWNER_N,          // Number of GA_AttributeOwner enums

    GA_ATTRIB_DETAIL = GA_ATTRIB_GLOBAL // Detail data, same as global
};

/// Attributes (and other data) may be stored with different precision and
/// storage types.
enum GA_Storage
{
    GA_STORE_INVALID=-1,        // Invalid storage
    GA_STORE_BOOL,              // Bool storage (bit-array)
    GA_STORE_UINT8,             // 8-bit unsigned integer
    GA_STORE_INT8,              // 8-bit signed integer
    GA_STORE_INT16,             // 16-bit integer
    GA_STORE_INT32,             // 32-bit integer
    GA_STORE_INT64,             // 64-bit integer
    GA_STORE_REAL16,            // 16-bit real
    GA_STORE_REAL32,            // 32-bit real
    GA_STORE_REAL64,            // 64-bit real
    GA_STORE_STRING,            // ASCII string data
    // GA_STORE_UTF8,           // Future?
    // GA_STORE_UTF16,          // Future?
    // GA_STORE_UTF32,          // Future?
};

/// Often one does not care about the precision.  In this case
/// the storage class gives a good idea which AIFs will be supported.
enum GA_StorageClass
{
    GA_STORECLASS_INVALID = -1,         // Invalid storage
    GA_STORECLASS_INT,                  // Any integer type
    GA_STORECLASS_REAL,                 // Any real type
    GA_STORECLASS_FLOAT = GA_STORECLASS_REAL,
    GA_STORECLASS_STRING,
    GA_STORECLASS_OTHER
};

/// Type qualifiers on attributes.  These qualifiers can help to interpret the
/// data associated with an attribute, but are not required.
enum GA_TypeInfo
{
    /// Data has no numeric representation
    GA_TYPE_VOID = -1,
    /// Data represents a position in space.  Token "point"
    GA_TYPE_POINT,
    /// Data represents a position and homogeneous coordinate.  The position is
    /// stored in non-homogeneous space (i.e. the w coordinate is not
    /// multiplied through).  Token "hpoint"
    GA_TYPE_HPOINT,
    /// Data represents a direction vector.  Token "vector"
    GA_TYPE_VECTOR,
    /// Data represents a normal vector.  Token "normal"
    GA_TYPE_NORMAL,
    /// Data represents a color.  Token "color"
    GA_TYPE_COLOR,
    /// Data represents a transform matrix.  Token "matrix"
    GA_TYPE_TRANSFORM,
    /// Data represents a quaternion.  Token "quaternion"
    GA_TYPE_QUATERNION,
    /// Data represents an index-pair.  Token "indexpair"
    GA_TYPE_INDEXPAIR,

    /// When a numeric attribute is created with integer storage, the attribute
    /// will be tagged as a non-arithmetic integer.  This means that
    /// mathematical operations will not typically be performed (i.e. integer
    /// values will not be averaged).  This works well for most cases of
    /// integers under Houdini.
    GA_TYPE_NONARITHMETIC_INTEGER,
    /// Arithmetic integers will be modified under arithmetic operations.
    /// Their values will be averaged etc.
    /// @note This is not the default behaviour for numeric attributes
    GA_TYPE_ARITHMETIC_INTEGER,
};

/// Scope qualifiers on attributes.  Each valid scope has its own namespace,
/// along with other consequences.
enum GA_AttributeScope
{
    /// Data has no numeric representation
    GA_SCOPE_INVALID = -1,
    /// Standard user attribute level
    //    GA_OPTION_EXPORT_ON_SAVE/MERGE defaults to true
    GA_SCOPE_PUBLIC,
    // Internal attribute level
    //    GA_OPTION_EXPORT_ON_SAVE/MERGE defaults to false
    GA_SCOPE_PRIVATE,
    // Group attribute level
    //    GA_OPTION_EXPORT_ON_SAVE/MERGE defaults to false
    GA_SCOPE_GROUP
};

/// An ordinal enum for the different types of groups in GA
enum GA_GroupType
{
    GA_GROUP_INVALID    = -1,
    GA_GROUP_POINT      = 0,
    GA_GROUP_PRIMITIVE  = 1,
    GA_GROUP_EDGE       = 2,
    GA_GROUP_BREAKPOINT = 3,
    GA_GROUP_VERTEX     = 4,
    GA_GROUP_N
};

/// Currently SOP_Node::parseAllGroups takes a mask of different types of
/// groups.  This enum allows group types to be packed into a bit field.
enum GA_GroupMaskType
{
    GA_GMASK_NONE       = 0,
    GA_GMASK_POINT      = 1 << GA_GROUP_POINT,
    GA_GMASK_PRIMITIVE  = 1 << GA_GROUP_PRIMITIVE,
    GA_GMASK_EDGE       = 1 << GA_GROUP_EDGE,
    GA_GMASK_BREAKPOINT = 1 << GA_GROUP_BREAKPOINT,
    GA_GMASK_VERTEX     = 1 << GA_GROUP_VERTEX,
    GA_GMASK_FULL_MASK  = ((1 << GA_GROUP_N)-1)
};

// Maximum order for NURBs/Bezier bases
#define GA_MAX_ORDER    11

// Types of knot spacing for NURBs operations
enum GA_KnotSpaceType
{
    GA_KNOT_SPACE_UNIFORM,
    GA_KNOT_SPACE_AVERAGING
};

// Basis parametrization types
enum GA_ParameterizationType
{
    GA_PARAMETERIZATION_UNIFORM,
    GA_PARAMETERIZATION_CHORD,
    GA_PARAMETERIZATION_CENTRIPETAL,
    GA_PARAMETERIZATION_APPROXARC
};

/// Attributes may paritition their data in pages of GA_PAGE_SIZE offsets.
#define GA_PAGE_BITS             10
#define GA_PAGE_SIZE             (1 << GA_PAGE_BITS)
#define GA_PAGE_MASK             (GA_PAGE_SIZE - 1)
#define GA_DEFRAGMENT_OCCUPANCY  1.00

// -------------------------------------------------------------
// GA Types
// When indexing points, vertices or primitives, use
// GA_Index (ordered) or GA_Offset (data offset)
// -------------------------------------------------------------

/// Defines the bit width for index and offset types in GA
typedef exint   GA_Size;

/// Define the strictness of GA_Offset/GA_Index
#if !defined(GA_STRICT_TYPES) && UT_ASSERT_LEVEL > 2
    #define GA_STRICT_TYPES     0
#endif

#if defined(GA_STRICT_TYPES)

#define GA_DEFINE_ORDINAL_BINARY_OPS(OP) \
    friend ThisType operator OP (const ThisType &v1, const ThisType &v2) \
                        { return ThisType(v1.myVal OP v2.myVal); } \
    friend ThisType operator OP (const ThisType &v1, const exint &v2) \
                        { return ThisType(v1.myVal OP v2); } \
    friend ThisType operator OP (const exint &v1, const ThisType &v2) \
                        { return ThisType(v1 OP v2.myVal); } \
    friend ThisType operator OP (const ThisType &v1, const int &v2) \
                        { return ThisType(v1.myVal OP v2); } \
    friend ThisType operator OP (const int &v1, const ThisType &v2) \
                        { return ThisType(v1 OP v2.myVal); } \
    friend ThisType operator OP (const ThisType &v1, const uint &v2) \
                        { return ThisType(v1.myVal OP v2); } \
    friend ThisType operator OP (const uint &v1, const ThisType &v2) \
                        { return ThisType(v1 OP v2.myVal); } \
    /**/

#define GA_DEFINE_ORDINAL_METHODS \
    ThisType        operator+=(exint v) { myVal += v; return *this; } \
    ThisType        operator+=(int v)   { myVal += v; return *this; } \
    ThisType        operator+=(uint v)  { myVal += v; return *this; } \
    ThisType        operator-=(exint v) { myVal -= v; return *this; } \
    ThisType        operator-=(int v)   { myVal -= v; return *this; } \
    ThisType        operator-=(uint v)  { myVal -= v; return *this; } \
    ThisType &      operator++()        { ++myVal; return *this; } \
    ThisType        operator++(int)     { return ThisType(myVal++); } \
    ThisType &      operator--()        { --myVal; return *this; } \
    ThisType        operator--(int)     { return ThisType(myVal--); } \
    ThisType        operator-()         { return ThisType(-myVal); } \
    \
    GA_DEFINE_ORDINAL_BINARY_OPS(+) \
    GA_DEFINE_ORDINAL_BINARY_OPS(-) \
    /**/

template <typename TAG, typename BASE_TYPE>
class GA_OrdinalType
{
private:
    typedef     GA_OrdinalType<TAG, BASE_TYPE> ThisType;

public:
                GA_OrdinalType()    { }
    explicit    GA_OrdinalType(const BASE_TYPE &val) : myVal(val) { }

    operator    BASE_TYPE() const           { return myVal; }

    GA_DEFINE_ORDINAL_METHODS

private:
    BASE_TYPE   myVal;
};

class GA_Index;

/// GA_Offset defines an offset into the attribute table of a GA_IndexMap.
/// Properties:
///   - Not allowed to be converted from a GA_Index
///   - Not implicitly convertible from a GA_Size
class GA_Offset
{
    typedef     GA_Offset           ThisType;

public:
                GA_Offset()         { }
    explicit    GA_Offset(const GA_Size &val) : myVal(val) { }

    operator    GA_Size() const     { return myVal; }

    GA_DEFINE_ORDINAL_METHODS

private:
                GA_Offset(const GA_Index &v);   // DISALLOW

    GA_Size     myVal;
};
SYS_DECLARE_IS_POD(GA_Offset)

/// GA_Index defines an ordered index of a GA_IndexMap.
/// Properties:
///   - Not allowed to be converted from a GA_Offset
///   - Implicitly convertible from and to a GA_Size
class GA_Index
{
private:
    typedef     GA_Index            ThisType;

public:
                GA_Index()          { }
                GA_Index(const GA_Size &val) : myVal(val) { }

    operator    GA_Size() const     { return myVal; }

    GA_DEFINE_ORDINAL_METHODS

private:
                GA_Index(const GA_Offset &v);   // DISALLOW

    GA_Size     myVal;
};
SYS_DECLARE_IS_POD(GA_Index)

#undef GA_DEFINE_ORDINAL_BINARY_OPS
#undef GA_DEFINE_ORDINAL_METHODS


class GA_PageNumTag {};
typedef GA_OrdinalType<GA_PageNumTag, GA_Size> GA_PageNum;
SYS_DECLARE_IS_POD(GA_PageNum)


class GA_PageOffTag {};
typedef GA_OrdinalType<GA_PageOffTag, GA_Size> GA_PageOff;
SYS_DECLARE_IS_POD(GA_PageOff)

#else

typedef GA_Size GA_Index;
typedef GA_Size GA_Offset;
typedef GA_Size GA_PageNum;
typedef GA_Size GA_PageOff;

#endif

inline bool GAisValid(GA_Size v) { return v >= 0; }

inline GA_PageNum GAgetPageNum(GA_Offset v)
{
    return GA_PageNum(v >> GA_PAGE_BITS);
}
inline GA_PageOff GAgetPageOff(GA_Offset v)
{
    return GA_PageOff(v & GA_PAGE_MASK);
}
inline bool      GAisFullPage(GA_Offset start, GA_Offset end)
{
    return (GAgetPageOff(start) == 0 &&
            GAgetPageOff(end) == 0 &&
            (GAgetPageNum(start) == GAgetPageNum(end)-1));
}

inline GA_Offset GAgetPageBoundary(const GA_Offset &start,
                                   const GA_Offset &end)
{
    return GA_Offset(SYSmin(end, start - GA_Size(GAgetPageOff(start)) + GA_PAGE_SIZE));
}

#define GA_INVALID_INDEX        GA_Index(-1)
#define GA_INVALID_OFFSET       GA_Offset(-1)

typedef UT_ValArray<GA_Index>       GA_IndexArray;
typedef UT_ValArray<GA_Offset>      GA_OffsetArray;

/// @{
/// At the current time, intrinsic handles are an integer.
/// This may change in the future.
typedef int     GA_LocalIntrinsic;
typedef int     GA_GlobalIntrinsic;
#define GA_INVALID_INTRINSIC_HANDLE     -1
static inline bool      GAisValidGlobalIntrinsic(GA_GlobalIntrinsic h)
                                    { return h >= 0; }
static inline bool      GAisValidLocalIntrinsic(GA_LocalIntrinsic h)
                                    { return h >= 0; }
/// @}

// -------------------------------------------------------------
// Functions to map storage enums to tokens.
// -------------------------------------------------------------
/// Lookup the size in bytes of a storage type (inaccurate for bool)
GA_API extern unsigned           GAsizeof(GA_Storage store);

/// Compare precision of GA_Storage types.  The function will return:
///     -2 invalid comparison (i.e. comparing a string to a float)
///     -1 if a is less precise than b
///      0 if a and be have the same precision
///      1 if a is more precise than b
GA_API extern int                GAcomparePrecision(GA_Storage a, GA_Storage b);

/// Lookup the owner name from the owner type
GA_API extern const char        *GAowner(GA_AttributeOwner owner);
/// Lookup the owner type from the owner name
GA_API extern GA_AttributeOwner  GAowner(const char *owner);

/// Lookup the scope name from the scope type
GA_API extern const char        *GAscope(GA_AttributeScope scope);
/// Lookup the scope type from the scope name
GA_API extern GA_AttributeScope  GAscope(const char *scope);

/// Lookup the storage name from the storage type
GA_API extern const char        *GAstorage(GA_Storage store);
/// Lookup the storage type from the storage name
GA_API extern GA_Storage         GAstorage(const char *store);

/// Lookup the storage label (descriptive name) from the storage type
GA_API extern const char        *GAstorageLabel(GA_Storage store);
/// Lookup the storage type from the storage label
GA_API extern GA_Storage         GAstorageLabel(const char *store);



/// Lookup the storage name from the storage type
GA_API extern const char        *GAstorageClass(GA_StorageClass store);
/// Lookup the intrinsic storage type from the storage name
GA_API extern GA_StorageClass    GAstorageClass(const char *store);

/// Lookup the type-info name from the type-info type
GA_API extern const char        *GAtypeinfo(GA_TypeInfo type);
/// Lookup the type-info type from the type-info name
GA_API extern GA_TypeInfo        GAtypeinfo(const char *type);

/// Lookup the type-info label (descriptive name) from the type-info type
GA_API extern const char        *GAtypeinfoLabel(GA_TypeInfo type);
/// Lookup the type-info type from the type-info label (descriptive name)
GA_API extern GA_TypeInfo        GAtypeinfoLabel(const char *type);

/// Lookup the owner name from the owner type
GA_API extern const char        *GAgroupType(GA_GroupType owner);
/// Lookup the owner type from the owner name
GA_API extern GA_GroupType       GAgroupType(const char *owner);


/// Convenience method to determine whether an integer represents a valid
/// storage type.
static inline bool      GAisStorageType(int s)
                        {
                            return s >= GA_STORE_BOOL && s <= GA_STORE_STRING;
                        }

/// Convenience method to determine whether storage is real valued
static inline bool      GAisFloatStorage(GA_Storage s)
                        {
                            return s == GA_STORE_REAL16 ||
                                s == GA_STORE_REAL32 ||
                                s == GA_STORE_REAL64;
                        }

/// Convenience method to determine whether storage is integer valued
static inline bool      GAisIntStorage(GA_Storage s)
                        {
                            return
                                s == GA_STORE_UINT8 ||
                                s == GA_STORE_INT8 ||
                                s == GA_STORE_INT16 ||
                                s == GA_STORE_INT32 ||
                                s == GA_STORE_INT64;
                        }

/// Convenience method to determine whether storage is numeric (real/integer)
static inline bool      GAisNumericStorage(GA_Storage s)
                        {
                            return GAisFloatStorage(s) || GAisIntStorage(s);
                        }

/// Convenience method to determine if type info is a transforming type
static inline bool      GAisTransformingType(GA_TypeInfo t)
                        {
                            return
                                t == GA_TYPE_VECTOR ||
                                t == GA_TYPE_NORMAL ||
                                t == GA_TYPE_POINT ||
                                t == GA_TYPE_HPOINT ||
                                t == GA_TYPE_TRANSFORM ||
                                t == GA_TYPE_QUATERNION;
                        }

static inline GA_StorageClass GAstorageClass(GA_Storage s)
{
    switch (s)
    {
        case GA_STORE_INVALID:
            return GA_STORECLASS_INVALID;
        case GA_STORE_BOOL:
        case GA_STORE_UINT8:
        case GA_STORE_INT8:
        case GA_STORE_INT16:
        case GA_STORE_INT32:
        case GA_STORE_INT64:
            return GA_STORECLASS_INT;
        case GA_STORE_REAL16:
        case GA_STORE_REAL32:
        case GA_STORE_REAL64:
            return GA_STORECLASS_REAL;
        case GA_STORE_STRING:
            return GA_STORECLASS_STRING;
    }

    return GA_STORECLASS_OTHER;
}

static inline GA_Storage GAgetDefaultStorage(GA_StorageClass s)
{
    switch (s)
    {
        case GA_STORECLASS_INT:
            return GA_STORE_INT32;
        case GA_STORECLASS_REAL:
            return GA_STORE_REAL32;
        case GA_STORECLASS_STRING:
            return GA_STORE_STRING;
        default:
            // There's no default storage for this storage class
            return GA_STORE_INVALID;
    }
}

/// @{
/// Define an intrusive type handle type for GA_AttributeProxy
class GA_AttributeProxy;
typedef UT_IntrusivePtr<GA_AttributeProxy>       GA_AttributeProxyHandle;
typedef UT_IntrusivePtr<const GA_AttributeProxy> GA_ConstAttributeProxyHandle;
/// @}

#endif

---