primvar.h

//
// 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_PRIMVAR_H
#define PXR_USD_USD_GEOM_PRIMVAR_H
 
#include "pxr/pxr.h"
#include "pxr/usd/usdGeom/api.h"
#include "pxr/usd/usd/attribute.h"
#include "pxr/usd/usdGeom/tokens.h"
 
#include <atomic>
#include <string>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
 
class UsdGeomPrimvar
{
public:
 
    // Default constructor returns an invalid Primvar.  Exists for 
    // container classes
    UsdGeomPrimvar()
    {
        /* NOTHING */
    }
 
    USDGEOM_API
    UsdGeomPrimvar(const UsdGeomPrimvar &other);
 
    USDGEOM_API
    UsdGeomPrimvar &operator=(const UsdGeomPrimvar &other);
 
    USDGEOM_API
    explicit UsdGeomPrimvar(const UsdAttribute &attr);
 
    USDGEOM_API
    TfToken GetInterpolation() const;
 
    USDGEOM_API
    bool SetInterpolation(const TfToken &interpolation);
    
    USDGEOM_API
    bool HasAuthoredInterpolation() const;
 
    USDGEOM_API
    int GetElementSize() const;
    
    USDGEOM_API
    bool SetElementSize(int eltSize);
    
    USDGEOM_API
    bool HasAuthoredElementSize() const;
    
 
    USDGEOM_API
    static bool IsPrimvar(const UsdAttribute &attr);
 
 
    USDGEOM_API
    static bool IsValidPrimvarName(const TfToken& name);
 
    USDGEOM_API
    static TfToken StripPrimvarsName(const TfToken& name);
 
    USDGEOM_API
    static bool IsValidInterpolation(const TfToken &interpolation);
 
    USDGEOM_API
    void GetDeclarationInfo(TfToken *name, SdfValueTypeName *typeName,
                            TfToken *interpolation, int *elementSize) const;
 
    // ---------------------------------------------------------------
    // ---------------------------------------------------------------
 
    operator UsdAttribute const& () const { return _attr; }
 
    UsdAttribute const &GetAttr() const { return _attr; }
    
    bool IsDefined() const { return IsPrimvar(_attr); }
 
    bool HasValue() const { return _attr.HasValue(); }
 
    bool HasAuthoredValue() const { return _attr.HasAuthoredValue(); }
 
    explicit operator bool() const {
        return IsDefined() ? &UsdGeomPrimvar::_attr : 0;
    }
 
    TfToken const &GetName() const { return _attr.GetName(); }
 
    USDGEOM_API
    TfToken GetPrimvarName() const;
 
    USDGEOM_API
    bool NameContainsNamespaces() const;
 
    TfToken GetBaseName() const { return _attr.GetBaseName(); }
 
    TfToken GetNamespace() const { return _attr.GetNamespace(); }
 
    std::vector<std::string> SplitName() const { return _attr.SplitName(); };
 
    SdfValueTypeName GetTypeName() const { return _attr.GetTypeName(); }
 
    template <typename T>
    bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
        return _attr.Get(value, time);
    }
 
    template <typename T>
    bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
        return _attr.Set(value, time);
    }
 
    USDGEOM_API
    bool GetTimeSamples(std::vector<double>* times) const;
 
    USDGEOM_API
    bool GetTimeSamplesInInterval(const GfInterval& interval,
                                  std::vector<double>* times) const;
 
    USDGEOM_API
    bool ValueMightBeTimeVarying() const;
 
 
    // ---------------------------------------------------------------
 
    USDGEOM_API
    bool SetIndices(const VtIntArray &indices, 
                    UsdTimeCode time = UsdTimeCode::Default()) const;
 
    USDGEOM_API
    bool GetIndices(VtIntArray *indices,
                    UsdTimeCode time = UsdTimeCode::Default()) const;
 
    USDGEOM_API
    void BlockIndices() const;
 
    USDGEOM_API
    bool IsIndexed() const;
 
    USDGEOM_API
    UsdAttribute GetIndicesAttr() const;
 
    USDGEOM_API
    UsdAttribute CreateIndicesAttr() const;
    
    USDGEOM_API
    bool SetUnauthoredValuesIndex(int unauthoredValuesIndex) const;
 
    USDGEOM_API
    int GetUnauthoredValuesIndex() const;
    
    template <typename ScalarType>
    bool ComputeFlattened(VtArray<ScalarType> * value, 
                          UsdTimeCode time = UsdTimeCode::Default()) const;
 
    USDGEOM_API
    bool ComputeFlattened(VtValue *value, 
                          UsdTimeCode time=UsdTimeCode::Default()) const;
 
    USDGEOM_API
    static bool ComputeFlattened(VtValue *value, const VtValue &attrVal,
                                 const VtIntArray &indices, 
                                 std::string *errString);
    
    USDGEOM_API
    static bool ComputeFlattened(VtValue *value, const VtValue &attrVal,
                                 const VtIntArray &indices,
                                 int elementSize,
                                 std::string *errString);
 
 
 
    // ---------------------------------------------------------------
    // ---------------------------------------------------------------
    
    USDGEOM_API
    bool IsIdTarget() const;
 
    USDGEOM_API
    bool SetIdTarget(const SdfPath& path) const;
    
 
    friend bool operator==(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
        return lhs.GetAttr() == rhs.GetAttr();
    }
 
    friend bool operator!=(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
        return !(lhs == rhs);
    }
 
    friend bool operator<(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
        return lhs.GetAttr().GetPath() < rhs.GetAttr().GetPath();
    }
 
    // Specialize TfHashAppend for TfHash
    template <typename HashState>
    friend void TfHashAppend(HashState& h, const UsdGeomPrimvar& obj) {
        h.Append(obj.GetAttr());
    }
 
    // hash_value overload for std/boost hash.
    friend size_t hash_value(const UsdGeomPrimvar &obj) {
        return TfHash{}(obj);
    }
 
 
private:
    friend class UsdGeomImageable;
    friend class UsdGeomPrimvarsAPI;
    
    static bool _IsNamespaced(const TfToken& name);
 
    static TfToken _MakeNamespaced(const TfToken& name, bool quiet=false);
 
    static TfToken const &_GetNamespacePrefix();
 
    UsdGeomPrimvar(const UsdPrim& prim, const TfToken& attrName,
                   const SdfValueTypeName &typeName);
 
    UsdAttribute _attr;
 
    // Gets or creates the indices attribute corresponding to the primvar.
    UsdAttribute _GetIndicesAttr(bool create) const;
 
    // Helper method for computing the flattened value of an indexed primvar.
    template<typename ScalarType>
    static bool _ComputeFlattenedHelper(const VtArray<ScalarType> &authored,
                                        const VtIntArray &indices,
                                        int elementSize,
                                        VtArray<ScalarType> *value,
                                        std::string *errString);
    
    // Helper function to evaluate the flattened array value of a primvar given
    // the attribute value and the indices array.
    template <typename ArrayType>
    static bool _ComputeFlattenedArray(const VtValue &attrVal,
                                       const VtIntArray &indices,
                                       int elementSize,
                                       VtValue *value, 
                                       std::string *errString);
 
    // Should only be called if _idTargetRelName is set
    UsdRelationship _GetIdTargetRel(bool create) const;
 
    // Compute & cache whether or not this primvar can be an idtarget.  After a
    // call to this function, _idTargetStatus will be either IdTargetImpossible
    // or IdTargetPossible.  If the result is "possible" then _idTargetRelName
    // will contain the relationship name.  This function returns true if
    // _idTargetStatus was set to IdTargetPossible, else false.
    bool _ComputeIdTargetPossibility() const;
 
    enum _IdTargetStatus {
        IdTargetUninitialized,
        IdTargetInitializing,
        IdTargetImpossible,
        IdTargetPossible };
 
    mutable TfToken _idTargetRelName;
    mutable std::atomic<_IdTargetStatus> _idTargetStatus;
};
 
// We instantiate the following so we can check and provide the correct value
// for Id attributes.
template <>
USDGEOM_API bool UsdGeomPrimvar::Get(std::string* value, UsdTimeCode time) const;
 
template <>
USDGEOM_API bool UsdGeomPrimvar::Get(VtStringArray* value, UsdTimeCode time) const;
 
template <>
USDGEOM_API bool UsdGeomPrimvar::Get(VtValue* value, UsdTimeCode time) const;
 
template <typename ScalarType>
bool 
UsdGeomPrimvar::ComputeFlattened(VtArray<ScalarType> *value, UsdTimeCode time) const
{
    VtArray<ScalarType> authored;
    if (!Get(&authored, time))
        return false;
 
    if (!IsIndexed()) {
        *value = authored;
        return true;
    }
 
    VtIntArray indices;
    if (!GetIndices(&indices, time)) {
        TF_WARN("No indices authored for indexed primvar <%s>.", 
                _attr.GetPath().GetText());
        return false;
    }
 
    // If the authored array is empty, there's nothing to do.
    if (authored.empty())
        return false;
 
    std::string errString;
    bool res = _ComputeFlattenedHelper(authored, indices, GetElementSize(), value, &errString);
    if (!errString.empty()) {
        TF_WARN("For primvar %s: %s", 
                UsdDescribe(_attr).c_str(), errString.c_str());
    }
    return res;
}
 
template<typename ScalarType>
bool
UsdGeomPrimvar::_ComputeFlattenedHelper(const VtArray<ScalarType> &authored,
                                        const VtIntArray &indices,
                                        int elementSize,
                                        VtArray<ScalarType> *value,
                                        std::string *errString)
{
    TF_VERIFY(elementSize >= 1);
    value->resize(indices.size() * elementSize);
    bool success = true;
 
    std::vector<size_t> invalidIndexPositions;
    for (size_t i=0; i < indices.size(); i++) {
        if (indices[i] < 0 || static_cast<size_t>((indices[i] + 1) * elementSize) > authored.size()) {
            invalidIndexPositions.push_back(i);
            success = false;
            continue;
        }
 
        const size_t indicesIdx = indices[i] * elementSize;
        const size_t valuesIdx = i * elementSize;
        for (size_t j=0; j < static_cast<size_t>(elementSize); j++) {
            size_t index = indicesIdx + j;
            (*value)[valuesIdx + j] = authored[index];
        }
    }
 
    if (!invalidIndexPositions.empty() && errString) {
        *errString = TfStringPrintf(
            "Found %ld invalid indices into authored array of size %ld with" 
            " element size of %i:", 
            invalidIndexPositions.size(), 
            authored.size(), elementSize);
 
        // Print a maximum of 5 invalid index positions.
        size_t numElementsToPrint = std::min(invalidIndexPositions.size(), 
                                             size_t(5));
        for (size_t i = 0; i < numElementsToPrint ; ++i) {
            int invalidIndex = indices[invalidIndexPositions[i]];
            int authoredStartIndex = invalidIndex * elementSize;
 
            *errString += TfStringPrintf(
            "\n\t Invalid index %i at position %ld refers to %s of the"
            " authored array, which is out of bounds", 
            invalidIndex,
            invalidIndexPositions[i],
            elementSize == 1 ? TfStringPrintf("index %i", authoredStartIndex).c_str() 
            : TfStringPrintf("indices [%i,...,%i]", authoredStartIndex, authoredStartIndex + elementSize - 1).c_str());
        }
    }
    return success;
}
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // USD_PRIMVAR_H