primvar.h

//
// 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_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 <string>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE


class UsdGeomPrimvar
{
public:

    // Default constructor returns an invalid Primvar.  Exists for 
    // container classes
    UsdGeomPrimvar()
    {
        /* NOTHING */
    }
    
    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
    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();
    }

    // hash_value overload for std/boost hash.
    USDGEOM_API
    friend size_t hash_value(const UsdGeomPrimvar &obj) {
        return hash_value(obj.GetAttr());
    }


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;

    // upon construction, we'll take note of the attrType.  If we're a type
    // that could possibly have an Id associated with it, we'll store that name
    // so we don't have to pay the cost of constructing that token per-Get().
    void _SetIdTargetRelName();

    // 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,
                                        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,
                                       VtValue *value, 
                                       std::string *errString);

    // Should only be called if _idTargetRelName is set
    UsdRelationship _GetIdTargetRel(bool create) const;
    TfToken _idTargetRelName;
};

// 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, 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,
                                        VtArray<ScalarType> *value,
                                        std::string *errString)
{
    value->resize(indices.size());
    bool success = true;

    std::vector<size_t> invalidIndexPositions;
    for (size_t i=0; i < indices.size(); i++) {
        int index = indices[i];
        if (index >= 0 && (size_t)index < authored.size()) {
            (*value)[i] = authored[index];
        } else {
            invalidIndexPositions.push_back(i);
            success = false;
        }
    }

    if (!invalidIndexPositions.empty()) {
        std::vector<std::string> invalidPositionsStrVec;
        // Print a maximum of 5 invalid index positions.
        size_t numElementsToPrint = std::min(invalidIndexPositions.size(), 
                                             size_t(5));
        invalidPositionsStrVec.reserve(numElementsToPrint);
        for (size_t i = 0; i < numElementsToPrint ; ++i) {
            invalidPositionsStrVec.push_back(
                    TfStringify(invalidIndexPositions[i]));
        }

        if (errString) {
            *errString = TfStringPrintf(
                "Found %ld invalid indices at positions [%s%s] that are out of "
                "range [0,%ld).", invalidIndexPositions.size(), 
                TfStringJoin(invalidPositionsStrVec, ", ").c_str(), 
                invalidIndexPositions.size() > 5 ? ", ..." : "",
                authored.size());
        }
    }

    return success;
}


PXR_NAMESPACE_CLOSE_SCOPE

#endif // USD_PRIMVAR_H