types.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_SDF_TYPES_H
#define PXR_USD_SDF_TYPES_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/usd/sdf/assetPath.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/listOp.h"
#include "pxr/usd/sdf/opaqueValue.h"
#include "pxr/usd/sdf/pathExpression.h"
#include "pxr/usd/sdf/timeCode.h"
#include "pxr/usd/sdf/valueTypeName.h"
 
#include "pxr/base/arch/demangle.h"
#include "pxr/base/arch/inttypes.h"
#include "pxr/base/arch/pragmas.h"
#include "pxr/base/gf/duration.h"
#include "pxr/base/gf/half.h"
#include "pxr/base/gf/matrix2d.h"
#include "pxr/base/gf/matrix3d.h"
#include "pxr/base/gf/matrix4d.h"
#include "pxr/base/gf/quatd.h"
#include "pxr/base/gf/quatf.h"
#include "pxr/base/gf/quath.h"
#include "pxr/base/gf/timeCode.h"
#include "pxr/base/gf/vec2d.h"
#include "pxr/base/gf/vec2f.h"
#include "pxr/base/gf/vec2h.h"
#include "pxr/base/gf/vec2i.h"
#include "pxr/base/gf/vec3d.h"
#include "pxr/base/gf/vec3f.h"
#include "pxr/base/gf/vec3h.h"
#include "pxr/base/gf/vec3i.h"
#include "pxr/base/gf/vec4d.h"
#include "pxr/base/gf/vec4f.h"
#include "pxr/base/gf/vec4h.h"
#include "pxr/base/gf/vec4i.h"
#include "pxr/base/tf/enum.h"
#include "pxr/base/tf/preprocessorUtilsLite.h"
#include "pxr/base/tf/staticTokens.h"
#include "pxr/base/tf/token.h"
#include "pxr/base/tf/type.h"
#include "pxr/base/vt/array.h"
#include "pxr/base/vt/arrayEdit.h"
#include "pxr/base/vt/dictionary.h"
#include "pxr/base/vt/traits.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/vt/valueTransform.h"
 
#include <iosfwd>
#include <list>
#include <map>
#include <stdint.h>
#include <string>
#include <typeinfo>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class SdfPath;
 
enum SdfSpecType {
    // The unknown type has a value of 0 so that SdfSpecType() is unknown.
    SdfSpecTypeUnknown = 0,
 
    // Real concrete types
    SdfSpecTypeAttribute,
    SdfSpecTypeConnection,
    SdfSpecTypeExpression,
    SdfSpecTypeMapper,
    SdfSpecTypeMapperArg,
    SdfSpecTypePrim,
    SdfSpecTypePseudoRoot,
    SdfSpecTypeRelationship,
    SdfSpecTypeRelationshipTarget,
    SdfSpecTypeVariant,
    SdfSpecTypeVariantSet,
 
    SdfNumSpecTypes
};
 
enum SdfSpecifier {
    SdfSpecifierDef,
    SdfSpecifierOver,
    SdfSpecifierClass,
    SdfNumSpecifiers
};
 
inline
bool
SdfIsDefiningSpecifier(SdfSpecifier spec)
{
    return (spec != SdfSpecifierOver);
}
 
enum SdfPermission {
    SdfPermissionPublic,         
    SdfPermissionPrivate,        
 
    SdfNumPermissions            
};
 
enum SdfVariability {
    SdfVariabilityVarying,
    SdfVariabilityUniform,
 
    SdfNumVariabilities 
};
 
 
enum SdfAuthoringError
{
    SdfAuthoringErrorUnrecognizedFields,
    SdfAuthoringErrorUnrecognizedSpecType
};
 
// Each category of compatible units of measurement is defined by a
// preprocessor sequence of tuples.  Each such sequence gives rise to an enum
// representing the corresponding unit category.  All the unit categories are
// listed in _SDF_UNITS where each entry is a two-tuple with the unit category
// name as the first element, and the second element is the units in that
// category.  Each tuple in a unit category sequence corresponds to a unit of
// measurement represented by an enumerant whose name is given by concatenating
// 'Sdf', the unit category name, the word 'Unit' and the first entry in the
// tuple.  (E.g. units of category 'Length' are represented by an enum named
// SdfLengthUnit with enumerants SdfLengthUnitInch, SdfLengthUnitMeter and so
// forth.)  The second element in the tuple is the display name for the unit,
// and the third element is the relative size of the unit compared to the menv
// default unit for the unit category (which has a relative size of 1.0).
// Dimensionless quantities use a special 'Dimensionless' unit category
// represented by the enum SdfDimensionlessUnit.
#define _SDF_LENGTH_UNITS       \
((Millimeter, "mm",  0.001))    \
((Centimeter, "cm",  0.01))     \
((Decimeter,  "dm",  0.1))      \
((Meter,      "m",   1.0))      \
((Kilometer,  "km",  1000.0))   \
((Inch,       "in",  0.0254))   \
((Foot,       "ft",  0.3048))   \
((Yard,       "yd",  0.9144))   \
((Mile,       "mi",  1609.344))
 
#define _SDF_ANGULAR_UNITS      \
((Degrees, "deg", 1.0))         \
((Radians, "rad", 57.2957795130823208768))
 
#define _SDF_DIMENSIONLESS_UNITS \
((Percent, "%", 0.01))           \
((Default, "default", 1.0))
 
#define _SDF_UNITS                          \
((Length, _SDF_LENGTH_UNITS),               \
(Angular, _SDF_ANGULAR_UNITS),              \
(Dimensionless, _SDF_DIMENSIONLESS_UNITS))
 
#define _SDF_UNIT_TAG(tup) TF_PP_TUPLE_ELEM(0, tup)
#define _SDF_UNIT_NAME(tup) TF_PP_TUPLE_ELEM(1, tup)
#define _SDF_UNIT_SCALE(tup) TF_PP_TUPLE_ELEM(2, tup)
 
#define _SDF_UNITSLIST_CATEGORY(tup) TF_PP_TUPLE_ELEM(0, tup)
#define _SDF_UNITSLIST_TUPLES(tup) TF_PP_TUPLE_ELEM(1, tup)
#define _SDF_UNITSLIST_ENUM(elem) TF_PP_CAT(TF_PP_CAT(Sdf, \
                                    _SDF_UNITSLIST_CATEGORY(elem)), Unit)
 
#define _SDF_DECLARE_UNIT_ENUMERANT(tag, elem) \
    TF_PP_CAT(Sdf ## tag ## Unit, _SDF_UNIT_TAG(elem)),
 
#define _SDF_DECLARE_UNIT_ENUM(elem)                     \
enum _SDF_UNITSLIST_ENUM(elem) {                         \
    TF_PP_SEQ_FOR_EACH(_SDF_DECLARE_UNIT_ENUMERANT,      \
                       _SDF_UNITSLIST_CATEGORY(elem),    \
                       _SDF_UNITSLIST_TUPLES(elem))      \
};
 
#define _SDF_FOR_EACH_UNITS_IMPL(macro, ...)             \
    TF_PP_FOR_EACH(macro, __VA_ARGS__)
#define _SDF_FOR_EACH_UNITS(macro, args)                 \
    _SDF_FOR_EACH_UNITS_IMPL(macro, TF_PP_EAT_PARENS(args))
 
// On Windows this call to _SDF_FOR_EACH_UNITS generates a C4003 warning.
// This is harmless, but we disable the warning here so that external
// projects that include this header don't run into it as well.
ARCH_PRAGMA_PUSH
ARCH_PRAGMA_MACRO_TOO_FEW_ARGUMENTS
_SDF_FOR_EACH_UNITS(_SDF_DECLARE_UNIT_ENUM, _SDF_UNITS)
ARCH_PRAGMA_POP
 
typedef std::map<std::string, VtValue> SdfMapperParametersMap;
 
typedef std::map<std::string, std::string> SdfVariantSelectionMap;
 
typedef std::map<std::string, std::vector<std::string> > SdfVariantsMap;
 
//  Note: This map needs to be lexicographically sorted for some downstream
//        clients, so SdfPath::FastLessThan is explicitly omitted as
//        the Compare template parameter.
typedef std::map<SdfPath, SdfPath> SdfRelocatesMap;
 
typedef std::pair<SdfPath, SdfPath> SdfRelocate;
 
typedef std::vector<SdfRelocate> SdfRelocates;
 
typedef std::map<double, VtValue> SdfTimeSampleMap;
VT_VALUE_TYPE_CAN_TRANSFORM(SdfTimeSampleMap);
VT_VALUE_TYPE_CAN_COMPOSE(SdfTimeSampleMap);
 
SDF_API
SdfTimeSampleMap
SdfComposeTimeSampleMaps(SdfTimeSampleMap const &strong,
                         SdfTimeSampleMap const &weak);
 
SDF_API TfEnum SdfDefaultUnit( TfToken const &typeName );
 
SDF_API const TfEnum &SdfDefaultUnit( const TfEnum &unit );
 
SDF_API const std::string &SdfUnitCategory( const TfEnum &unit );
 
SDF_API double SdfConvertUnit( const TfEnum &fromUnit, const TfEnum &toUnit );
 
SDF_API const std::string &SdfGetNameForUnit( const TfEnum &unit );
 
SDF_API const TfEnum &SdfGetUnitFromName( const std::string &name );
 
SDF_API bool SdfValueHasValidType(VtValue const& value);
 
SDF_API TfType SdfGetTypeForValueTypeName(TfToken const &name);
 
SDF_API SdfValueTypeName SdfGetValueTypeNameForValue(VtValue const &value);
 
SDF_API TfToken SdfGetRoleNameForValueTypeName(TfToken const &typeName);
 
// Sdf allows a specific set of types for attribute and metadata values.
// These types and some additional metadata are listed in the preprocessor
// sequence of tuples below. First element is a tag name that is appended to
// 'SdfValueType' to produce the C++ traits type for the value type.
// Second element is the value type name, third element is the corresponding
// C++ type, and the fourth element is the tuple of tuple dimensions.
//
// Libraries may extend this list and define additional value types.
// When doing so, the type must be declared using the SDF_DECLARE_VALUE_TYPE
// macro below. The type must also be registered in the associated schema using
// SdfSchema::_RegisterValueType(s).
#define _SDF_SCALAR_VALUE_TYPES                                \
    ((Bool,           bool,           bool,              () )) \
    ((UChar,          uchar,          unsigned char,     () )) \
    ((Int,            int,            int,               () )) \
    ((UInt,           uint,           unsigned int,      () )) \
    ((Int64,          int64,          int64_t,           () )) \
    ((UInt64,         uint64,         uint64_t,          () )) \
    ((Half,           half,           GfHalf,            () )) \
    ((Float,          float,          float,             () )) \
    ((Double,         double,         double,            () )) \
    ((TimeCode,       timecode,       GfTimeCode,        () )) \
    ((Duration,       duration,       GfDuration,        () )) \
    ((String,         string,         std::string,       () )) \
    ((Token,          token,          TfToken,           () )) \
    ((Asset,          asset,          SdfAssetPath,      () )) \
    ((Opaque,         opaque,         SdfOpaqueValue,    () )) \
    ((PathExpression, pathExpression, SdfPathExpression, () ))
 
#define _SDF_DIMENSIONED_VALUE_TYPES                   \
    ((Matrix2d,   matrix2d,   GfMatrix2d,     (2,2) )) \
    ((Matrix3d,   matrix3d,   GfMatrix3d,     (3,3) )) \
    ((Matrix4d,   matrix4d,   GfMatrix4d,     (4,4) )) \
    ((Quath,      quath,      GfQuath,        (4)   )) \
    ((Quatf,      quatf,      GfQuatf,        (4)   )) \
    ((Quatd,      quatd,      GfQuatd,        (4)   )) \
    ((Int2,       int2,       GfVec2i,        (2)   )) \
    ((Half2,      half2,      GfVec2h,        (2)   )) \
    ((Float2,     float2,     GfVec2f,        (2)   )) \
    ((Double2,    double2,    GfVec2d,        (2)   )) \
    ((Int3,       int3,       GfVec3i,        (3)   )) \
    ((Half3,      half3,      GfVec3h,        (3)   )) \
    ((Float3,     float3,     GfVec3f,        (3)   )) \
    ((Double3,    double3,    GfVec3d,        (3)   )) \
    ((Int4,       int4,       GfVec4i,        (4)   )) \
    ((Half4,      half4,      GfVec4h,        (4)   )) \
    ((Float4,     float4,     GfVec4f,        (4)   )) \
    ((Double4,    double4,    GfVec4d,        (4)   ))
 
#define SDF_VALUE_TYPES _SDF_SCALAR_VALUE_TYPES _SDF_DIMENSIONED_VALUE_TYPES
 
// Accessors for individual elements in the value types tuples.
#define SDF_VALUE_CPP_TYPE(tup) TF_PP_TUPLE_ELEM(2, tup)
#define SDF_VALUE_CPP_ARRAY_TYPE(tup) VtArray<TF_PP_TUPLE_ELEM(2, tup)>
#define SDF_VALUE_CPP_ARRAY_EDIT_TYPE(tup) VtArrayEdit<TF_PP_TUPLE_ELEM(2, tup)>
 
template <class T>
struct SdfValueTypeTraits {
    static const bool IsValueType = false;
};
 
// Allow character arrays to be treated as Sdf value types.
// Sdf converts character arrays to strings for scene description.
template <int N>
struct SdfValueTypeTraits<char[N]> {
    static const bool IsValueType = true;
};
 
#define SDF_DECLARE_VALUE_TYPE_TRAITS(unused, elem)                         \
template <>                                                                 \
struct SdfValueTypeTraits<SDF_VALUE_CPP_TYPE(elem)> {                       \
    static const bool IsValueType = true;                                   \
};                                                                          \
template <>                                                                 \
struct SdfValueTypeTraits<SDF_VALUE_CPP_ARRAY_TYPE(elem)> {                 \
    static const bool IsValueType = true;                                   \
};                                                                          \
template <>                                                                 \
struct SdfValueTypeTraits<SDF_VALUE_CPP_ARRAY_EDIT_TYPE(elem)> {            \
    static const bool IsValueType = true;                                   \
};
 
TF_PP_SEQ_FOR_EACH(SDF_DECLARE_VALUE_TYPE_TRAITS, ~, SDF_VALUE_TYPES);
 
SDF_API
bool
SdfConvertToValidMetadataDictionary(VtDictionary *dict, std::string *errMsg);
 
#define SDF_VALUE_ROLE_NAME_TOKENS              \
    (Point)                                     \
    (Normal)                                    \
    (Vector)                                    \
    (Color)                                     \
    (Frame)                                     \
    (Transform)                                 \
    (PointIndex)                                \
    (EdgeIndex)                                 \
    (FaceIndex)                                 \
    (Group)                                     \
    (TextureCoordinate)
 
TF_DECLARE_PUBLIC_TOKENS(SdfValueRoleNames, SDF_API, SDF_VALUE_ROLE_NAME_TOKENS);
 
SDF_DECLARE_HANDLES(SdfLayer);
 
SDF_DECLARE_HANDLES(SdfAttributeSpec);
SDF_DECLARE_HANDLES(SdfPrimSpec);
SDF_DECLARE_HANDLES(SdfPropertySpec);
SDF_DECLARE_HANDLES(SdfSpec);
SDF_DECLARE_HANDLES(SdfRelationshipSpec);
SDF_DECLARE_HANDLES(SdfVariantSetSpec);
SDF_DECLARE_HANDLES(SdfVariantSpec);
 
typedef std::map<std::string, SdfVariantSetSpecHandle> 
    SdfVariantSetSpecHandleMap;
 
SDF_API 
std::ostream & operator<<( std::ostream &out, const SdfSpecifier &spec );
 
SDF_API 
std::ostream & operator<<( std::ostream &out,
                           const SdfRelocatesMap &reloMap );
 
SDF_API 
std::ostream & operator<<( std::ostream &out,
                           const SdfRelocates &relocates );
 
SDF_API 
std::ostream & operator<<( std::ostream &out,
                           const SdfTimeSampleMap &sampleMap );
 
SDF_API 
std::ostream &VtStreamOut(const SdfVariantSelectionMap &, std::ostream &);
 
class SdfUnregisteredValue
{
public:
    SDF_API SdfUnregisteredValue();
 
    SDF_API explicit SdfUnregisteredValue(const std::string &value);
 
    SDF_API explicit SdfUnregisteredValue(const VtDictionary &value);
 
    SDF_API explicit SdfUnregisteredValue(const SdfUnregisteredValueListOp &value);
 
    const VtValue& GetValue() const {
        return _value;
    }
 
    friend size_t hash_value(const SdfUnregisteredValue &uv) {
        return uv._value.GetHash();
    }
 
    SDF_API bool operator==(const SdfUnregisteredValue &other) const;
 
    SDF_API bool operator!=(const SdfUnregisteredValue &other) const;
 
private:
    VtValue _value;
};
 
SDF_API std::ostream &operator << (std::ostream &out, const SdfUnregisteredValue &value);
 
class Sdf_ValueTypeNamesType {
    Sdf_ValueTypeNamesType(const Sdf_ValueTypeNamesType&) = delete;
    Sdf_ValueTypeNamesType& operator=(const Sdf_ValueTypeNamesType&) = delete;
public:
    SdfValueTypeName Bool;
    SdfValueTypeName UChar, Int, UInt, Int64, UInt64;
    SdfValueTypeName Half, Float, Double;
    SdfValueTypeName TimeCode, Duration;
    SdfValueTypeName String, Token, Asset;
    SdfValueTypeName Int2,     Int3,     Int4;
    SdfValueTypeName Half2,    Half3,    Half4;
    SdfValueTypeName Float2,   Float3,   Float4;
    SdfValueTypeName Double2,  Double3,  Double4;
    SdfValueTypeName Point3h,  Point3f,  Point3d;
    SdfValueTypeName Vector3h, Vector3f, Vector3d;
    SdfValueTypeName Normal3h, Normal3f, Normal3d;
    SdfValueTypeName Color3h,  Color3f,  Color3d;
    SdfValueTypeName Color4h,  Color4f,  Color4d;
    SdfValueTypeName Quath,    Quatf,    Quatd;
    SdfValueTypeName Matrix2d, Matrix3d, Matrix4d;
    SdfValueTypeName Frame4d;
    SdfValueTypeName TexCoord2h, TexCoord2f, TexCoord2d;
    SdfValueTypeName TexCoord3h, TexCoord3f, TexCoord3d;
    SdfValueTypeName Opaque;
    SdfValueTypeName Group;
    SdfValueTypeName PathExpression;
 
    SdfValueTypeName BoolArray;
    SdfValueTypeName UCharArray, IntArray, UIntArray, Int64Array, UInt64Array;
    SdfValueTypeName HalfArray, FloatArray, DoubleArray;
    SdfValueTypeName TimeCodeArray, DurationArray;
    SdfValueTypeName StringArray, TokenArray, AssetArray;
    SdfValueTypeName Int2Array,     Int3Array,     Int4Array;
    SdfValueTypeName Half2Array,    Half3Array,    Half4Array;
    SdfValueTypeName Float2Array,   Float3Array,   Float4Array;
    SdfValueTypeName Double2Array,  Double3Array,  Double4Array;
    SdfValueTypeName Point3hArray,  Point3fArray,  Point3dArray;
    SdfValueTypeName Vector3hArray, Vector3fArray, Vector3dArray;
    SdfValueTypeName Normal3hArray, Normal3fArray, Normal3dArray;
    SdfValueTypeName Color3hArray,  Color3fArray,  Color3dArray;
    SdfValueTypeName Color4hArray,  Color4fArray,  Color4dArray;
    SdfValueTypeName QuathArray,    QuatfArray,    QuatdArray;
    SdfValueTypeName Matrix2dArray, Matrix3dArray, Matrix4dArray;
    SdfValueTypeName Frame4dArray;
    SdfValueTypeName TexCoord2hArray, TexCoord2fArray, TexCoord2dArray;
    SdfValueTypeName TexCoord3hArray, TexCoord3fArray, TexCoord3dArray;
    SdfValueTypeName PathExpressionArray;
 
    SDF_API ~Sdf_ValueTypeNamesType();
    struct _Init {
        SDF_API static const Sdf_ValueTypeNamesType* New();
    };
 
    // For Pixar internal backwards compatibility.
    TfToken GetSerializationName(const SdfValueTypeName&) const;
    TfToken GetSerializationName(const VtValue&) const;
    TfToken GetSerializationName(const TfToken&) const;
 
private:
    friend const Sdf_ValueTypeNamesType* Sdf_InitializeValueTypeNames();
    Sdf_ValueTypeNamesType();
};
 
extern SDF_API TfStaticData<const Sdf_ValueTypeNamesType,
    Sdf_ValueTypeNamesType::_Init> SdfValueTypeNames;
 
struct SdfValueBlock { 
    bool operator==(const SdfValueBlock& block) const { return true; }
    bool operator!=(const SdfValueBlock& block) const { return false; }
 
private:
    friend inline size_t hash_value(const SdfValueBlock &block) { return 0; }
};
 
// Write out the string representation of a block.
SDF_API std::ostream& operator<<(std::ostream&, SdfValueBlock const&); 
 
struct SdfAnimationBlock {
    bool operator==(const SdfAnimationBlock& block) const { return true; }
    bool operator!=(const SdfAnimationBlock& block) const { return false; }
 
private:
    friend inline size_t hash_value(const SdfAnimationBlock &block) { return 0; }
};
 
// Write out the string representation of an animation block.
SDF_API std::ostream& operator<<(std::ostream&, SdfAnimationBlock const&);
 
// A class that represents a human-readable value.  This is used for the special
// purpose of producing layers that serialize field values in alternate ways; to
// produce more human-readable output, for example.
struct SdfHumanReadableValue {
    SdfHumanReadableValue() = default;
    explicit SdfHumanReadableValue(std::string const &text) : _text(text) {}
 
    bool operator==(SdfHumanReadableValue const &other) const {
        return GetText() == other.GetText();
    }
    bool operator!=(SdfHumanReadableValue const &other) const {
        return !(*this == other);
    }
 
    std::string const &GetText() const { return _text; }
private:
    std::string _text;
};
 
SDF_API
std::ostream &operator<<(std::ostream &out, const SdfHumanReadableValue &hrval);
 
SDF_API
size_t hash_value(const SdfHumanReadableValue &hrval);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_SDF_TYPES_H