xformOp.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_USD_GEOM_XFORM_OP_H
#define PXR_USD_USD_GEOM_XFORM_OP_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/usdGeom/api.h"
#include "pxr/usd/usd/attribute.h"
#include "pxr/usd/usd/attributeQuery.h"
#include "pxr/usd/usdGeom/tokens.h"
 
#include <string>
#include <variant>
#include <vector>
#include <typeinfo>
 
#include "pxr/base/tf/staticTokens.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
 
#define USDGEOM_XFORM_OP_TYPES \
    (translateX) \
    (translateY) \
    (translateZ) \
    (translate) \
    (scaleX) \
    (scaleY) \
    (scaleZ) \
    (scale) \
    (rotateX) \
    (rotateY) \
    (rotateZ) \
    (rotateXYZ) \
    (rotateXZY) \
    (rotateYXZ) \
    (rotateYZX) \
    (rotateZXY) \
    (rotateZYX) \
    (orient) \
    (transform) \
    ((resetXformStack, "!resetXformStack!"))
 
TF_DECLARE_PUBLIC_TOKENS(UsdGeomXformOpTypes, USDGEOM_API, USDGEOM_XFORM_OP_TYPES);
 
class UsdGeomXformOp
{
public:
  
    enum Type {
        TypeInvalid,   
        TypeTranslateX,
        TypeTranslateY,
        TypeTranslateZ,
        TypeTranslate, 
        TypeScaleX,    
        TypeScaleY,    
        TypeScaleZ,    
        TypeScale,     
        TypeRotateX,   
        TypeRotateY,   
        TypeRotateZ,   
        TypeRotateXYZ, 
        TypeRotateXZY, 
        TypeRotateYXZ, 
        TypeRotateYZX, 
        TypeRotateZXY, 
        TypeRotateZYX, 
        TypeOrient,    
        TypeTransform  
    };
 
    enum Precision {
        PrecisionDouble, 
        PrecisionFloat,  
        PrecisionHalf    
    };
 
    // Default constructor returns an invalid XformOp.  Exists for 
    // container classes
    UsdGeomXformOp()
    {
        /* NOTHING */
    }
    
    USDGEOM_API
    explicit UsdGeomXformOp(const UsdAttribute &attr, bool isInverseOp=false);
 
    // -------------------------------------------------------
    // -------------------------------------------------------
 
    USDGEOM_API
    static bool IsXformOp(const UsdAttribute &attr);
 
    USDGEOM_API
    static bool IsXformOp(const TfToken &attrName);
 
    USDGEOM_API
    static TfToken const &GetOpTypeToken(Type const opType);
 
    USDGEOM_API
    static Type GetOpTypeEnum(TfToken const &opTypeToken);
 
    USDGEOM_API
    static Precision GetPrecisionFromValueTypeName(
        const SdfValueTypeName& typeName);
 
    USDGEOM_API
    static const SdfValueTypeName &GetValueTypeName(const Type opType,
                                                    const Precision precision);
 
    USDGEOM_API
    static TfToken GetOpName(const Type opType, 
                             const TfToken &opSuffix=TfToken(),
                             bool inverse=false);
 
    // -------------------------------------------------------
    // -------------------------------------------------------
 
    Type GetOpType() const {
        return _opType;
    }
 
    USDGEOM_API
    Precision GetPrecision() const;
 
    bool IsInverseOp() const { 
        return _isInverseOp;
    }
 
    USDGEOM_API
    TfToken GetOpName() const;
 
    USDGEOM_API
    bool HasSuffix(TfToken const &suffix) const;
    
    // ---------------------------------------------------------------
    // ---------------------------------------------------------------
    
    template <typename T>
    bool GetAs(T* value, UsdTimeCode time) const {
        VtValue v;
        if (!Get(&v, time)) {
            return false;
        }
        v.Cast<T>();
        if (v.IsEmpty()){
            TfType thisType = GetTypeName().GetType();
            TF_CODING_ERROR("Unable to convert xformOp %s's value from %s to "
                            "requested type %s.", GetAttr().GetPath().GetText(),
                            thisType.GetTypeName().c_str(),
                            TfType::GetCanonicalTypeName(typeid(*value)).c_str());
            return false;
        }
        *value = v.UncheckedGet<T>();
        return true;
    }
 
    USDGEOM_API
    static GfMatrix4d GetOpTransform(Type const opType, 
                                     VtValue const &opVal,
                                     bool isInverseOp=false);
 
    
    USDGEOM_API
    GfMatrix4d GetOpTransform(UsdTimeCode time) const;
 
    bool MightBeTimeVarying() const {
        return std::visit(_GetMightBeTimeVarying(), _attr);
    }
 
    // ---------------------------------------------------------------
    // ---------------------------------------------------------------
    
    operator UsdAttribute const& () const { return GetAttr(); }
 
    UsdAttribute const &GetAttr() const { 
        return std::visit(_GetAttr(), _attr);
    }
    
    bool IsDefined() const { return IsXformOp(GetAttr()); }
 
public:
    explicit operator bool() const {
        return IsDefined();
    }
 
    friend bool operator==(const UsdGeomXformOp &lhs,
                           const UsdGeomXformOp &rhs) {
        return lhs.GetAttr() == rhs.GetAttr();
    }
 
    friend bool operator!=(const UsdGeomXformOp &lhs,
                           const UsdGeomXformOp &rhs) {
        return !(lhs == rhs);
    }
 
    TfToken const &GetName() const {  return GetAttr().GetName(); }
 
    TfToken GetBaseName() const { return GetAttr().GetBaseName(); }
 
    TfToken GetNamespace() const { return GetAttr().GetNamespace(); }
 
    std::vector<std::string> SplitName() const { return GetAttr().SplitName(); };
 
    SdfValueTypeName GetTypeName() const { return GetAttr().GetTypeName(); }
 
    template <typename T>
    bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
        return std::visit(_Get<T>(value, time), _attr);
    }
 
    template <typename T>
    bool Set(T const & value, UsdTimeCode time = UsdTimeCode::Default()) const {
        // Issue a coding error and return without setting value, 
        // if this is an inverse op.
        if (_isInverseOp) {
            TF_CODING_ERROR("Cannot set a value on the inverse xformOp '%s'. "
                "Please set value on the paired non-inverse xformOp instead.",
                GetOpName().GetText());
            return false;
        }
 
        return GetAttr().Set(value, time);
    }
 
    bool GetTimeSamples(std::vector<double> *times) const {
        return std::visit(_GetTimeSamples(times), _attr);
    }
 
    bool GetTimeSamplesInInterval(const GfInterval &interval, 
                                  std::vector<double> *times) const {
        return std::visit(
                _GetTimeSamplesInInterval(interval, times), _attr);
    }
 
    size_t GetNumTimeSamples() const {
        return std::visit(_GetNumTimeSamples(), _attr);
    }
 
private:
    struct _ValidAttributeTagType {};
 
public:
    // Allow clients that guarantee \p attr is valid avoid having
    // UsdGeomXformOp's ctor check again.
    USDGEOM_API
    UsdGeomXformOp(const UsdAttribute &attr, bool isInverseOp,
                   _ValidAttributeTagType);
    USDGEOM_API
    UsdGeomXformOp(UsdAttributeQuery &&query, bool isInverseOp,
                   _ValidAttributeTagType);
private:
    friend class UsdGeomXformable;
 
    // Shared initialization function.
    void _Init();
 
    // Return the op-type for the string value \p str.
    static Type _GetOpTypeEnumFromCString(char const *str, size_t len);
 
    // Returns the attribute belonging to \p prim that corresponds to the  
    // given \p opName. It also populates the output parameter \p isInverseOp 
    // appropriately. 
    // 
    // The attribute that's returned will be invalid if the 
    // corresponding xformOp attribute doesn't exist on the prim.
    // 
    static UsdAttribute _GetXformOpAttr(UsdPrim const& prim, 
        const TfToken &opName, bool *isInverseOp);
 
    // Private method for creating and using an attribute query internally for 
    // this xformOp.
    void _CreateAttributeQuery() const {
        _attr = UsdAttributeQuery(GetAttr());
    }
 
    // Factory for UsdGeomXformable's use, so that we can encapsulate the
    // logic of what discriminates XformOp in this class, while
    // preserving the pattern that attributes can only be created
    // via their container objects.
    //
    // \p opType must be one of UsdGeomXformOp::Type
    // 
    // \p precision must be one of UsdGeomXformOp::Precision.
    // 
    // \return an invalid UsdGeomXformOp if we failed to create a valid
    // attribute, a valid UsdGeomXformOp otherwise.  It is not an
    // error to create over an existing, compatible attribute.
    //
    // It is a failed verification for \p prim to be invalid/expired
    //
    // \sa UsdPrim::CreateAttribute()
    UsdGeomXformOp(UsdPrim const& prim, Type const opType,
                   Precision const precision, TfToken const &opSuffix=TfToken(),
                   bool inverse=false);
 
    // UsdAttributeQuery already contains a copy of the associated UsdAttribute.
    // To minimize the memory usage, we only store one or the other. 
    // 
    // The lifetime of a UsdAttributeQuery needs to be managed very carefully as
    // it gets invalidated whenever the associated attribute is authored.
    // Hence, access to the creation of an attribute query is restricted inside 
    // a private member function named _CreateAttributeQuery().
    // 
    mutable std::variant<UsdAttribute, UsdAttributeQuery> _attr;
 
    Type _opType;
    bool _isInverseOp;
 
    // Visitor for getting xformOp value.
    template <class T>
    struct _Get
    {
        _Get(T *value_, 
             UsdTimeCode time_ = UsdTimeCode::Default()) : value (value_), time(time_)
        {}
 
        bool operator()(const UsdAttribute &attr) const
        {
            return attr.Get(value, time);
        }
 
        bool operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.Get(value, time);
        }
 
        T *value;
        UsdTimeCode time;
    };
 
    // Visitor for getting a const-reference to the UsdAttribute.
    struct _GetAttr {
 
        _GetAttr() {}
 
        const UsdAttribute &operator()(const UsdAttribute &attr) const
        {
            return attr;
        }
 
        const UsdAttribute &operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.GetAttribute();
        }
    };
 
    // Visitor for getting all the time samples.
    struct _GetTimeSamples {
 
        _GetTimeSamples(std::vector<double> *times_) : times(times_) {}
 
        bool operator()(const UsdAttribute &attr) const
        {
            return attr.GetTimeSamples(times);
        }
 
        bool operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.GetTimeSamples(times);
        }
 
        std::vector<double> *times;
    };
 
    // Visitor for getting all the time samples within a given interval.
    struct _GetTimeSamplesInInterval {
 
        _GetTimeSamplesInInterval(const GfInterval &interval_,
                                  std::vector<double> *times_) 
            : interval(interval_), times(times_) 
        {}
 
        bool operator()(const UsdAttribute &attr) const
        {
            return attr.GetTimeSamplesInInterval(interval, times);
        }
 
        bool operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.GetTimeSamplesInInterval(interval, times);
        }
 
        const GfInterval &interval;
        std::vector<double> *times;
    };
 
    // Visitor for getting the number of time samples.
    struct _GetNumTimeSamples {
 
        _GetNumTimeSamples() {}
 
        size_t operator()(const UsdAttribute &attr) const
        {
            return attr.GetNumTimeSamples();
        }
 
        size_t operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.GetNumTimeSamples();
        }
    };
 
    // Visitor for determining whether the op might vary over time.
    struct _GetMightBeTimeVarying {
 
        _GetMightBeTimeVarying() {}
 
        bool operator()(const UsdAttribute &attr) const
        {
            return attr.ValueMightBeTimeVarying();
        }
 
        bool operator()(const UsdAttributeQuery &attrQuery) const
        {
            return attrQuery.ValueMightBeTimeVarying();
        }
    };
 
};
 
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // USD_XFORMOP_H