xformOp.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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 <vector>
#include <typeinfo>

#include <boost/variant.hpp>

#include "pxr/base/tf/staticTokens.h"

PXR_NAMESPACE_OPEN_SCOPE


#define USDGEOM_XFORM_OP_TYPES \
    (translate) \
    (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,   
        TypeTranslate, 
        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 boost::apply_visitor(_GetMightBeTimeVarying(), _attr);
    }

    // ---------------------------------------------------------------
    // ---------------------------------------------------------------
    
    operator UsdAttribute const& () const { return GetAttr(); }

    UsdAttribute const &GetAttr() const { 
        return boost::apply_visitor(_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 boost::apply_visitor(_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 boost::apply_visitor(_GetTimeSamples(times), _attr);
    }

    bool GetTimeSamplesInInterval(const GfInterval &interval, 
                                  std::vector<double> *times) const {
        return boost::apply_visitor(
                _GetTimeSamplesInInterval(interval, times), _attr);
    }

    size_t GetNumTimeSamples() const {
        return boost::apply_visitor(_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 interally 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 boost::variant<UsdAttribute, UsdAttributeQuery> _attr;

    Type _opType;
    bool _isInverseOp;

    // Visitor for getting xformOp value.
    template <class T>
    struct _Get : public boost::static_visitor<bool> 
    {
        _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 : public boost::static_visitor<const UsdAttribute &> {

        _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 : public boost::static_visitor<bool> {

        _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 : public boost::static_visitor<bool> {

        _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 : public boost::static_visitor<size_t> {

        _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 : public boost::static_visitor<bool> {

        _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