This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
primvar.h
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_USD_USD_GEOM_PRIMVAR_H
8#define PXR_USD_USD_GEOM_PRIMVAR_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/usdGeom/api.h"
12#include "pxr/usd/usd/attribute.h"
14
15#include <atomic>
16#include <string>
17#include <vector>
18
19PXR_NAMESPACE_OPEN_SCOPE
20
21
245{
246public:
247
248 // Default constructor returns an invalid Primvar. Exists for
249 // container classes
251 {
252 /* NOTHING */
253 }
254
256 USDGEOM_API
258
260 USDGEOM_API
262
272 USDGEOM_API
273 explicit UsdGeomPrimvar(const UsdAttribute &attr);
274
280 USDGEOM_API
282
291 USDGEOM_API
292 bool SetInterpolation(const TfToken &interpolation);
293
297 USDGEOM_API
299
319 USDGEOM_API
320 int GetElementSize() const;
321
327 USDGEOM_API
328 bool SetElementSize(int eltSize);
329
333 USDGEOM_API
335
336
341 USDGEOM_API
342 static bool IsPrimvar(const UsdAttribute &attr);
343
344
349 USDGEOM_API
350 static bool IsValidPrimvarName(const TfToken& name);
351
354 USDGEOM_API
355 static TfToken StripPrimvarsName(const TfToken& name);
356
359 USDGEOM_API
360 static bool IsValidInterpolation(const TfToken &interpolation);
361
368 USDGEOM_API
370 TfToken *interpolation, int *elementSize) const;
371
372 // ---------------------------------------------------------------
374 // ---------------------------------------------------------------
376
380 operator UsdAttribute const& () const { return _attr; }
381
383 UsdAttribute const &GetAttr() const { return _attr; }
384
388 bool IsDefined() const { return IsPrimvar(_attr); }
389
392 bool HasValue() const { return _attr.HasValue(); }
393
396 bool HasAuthoredValue() const { return _attr.HasAuthoredValue(); }
397
401 explicit operator bool() const {
402 return IsDefined() ? &UsdGeomPrimvar::_attr : 0;
403 }
404
406 TfToken const &GetName() const { return _attr.GetName(); }
407
414 USDGEOM_API
416
423 USDGEOM_API
425
427 TfToken GetBaseName() const { return _attr.GetBaseName(); }
428
430 TfToken GetNamespace() const { return _attr.GetNamespace(); }
431
433 std::vector<std::string> SplitName() const { return _attr.SplitName(); };
434
436 SdfValueTypeName GetTypeName() const { return _attr.GetTypeName(); }
437
442 template <typename T>
443 bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
444 return _attr.Get(value, time);
445 }
446
448 template <typename T>
449 bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
450 return _attr.Set(value, time);
451 }
452
460 USDGEOM_API
461 bool GetTimeSamples(std::vector<double>* times) const;
462
469 USDGEOM_API
471 std::vector<double>* times) const;
472
480 USDGEOM_API
482
484
485 // ---------------------------------------------------------------
511
518 USDGEOM_API
519 bool SetIndices(const VtIntArray &indices,
520 UsdTimeCode time = UsdTimeCode::Default()) const;
521
526 USDGEOM_API
527 bool GetIndices(VtIntArray *indices,
528 UsdTimeCode time = UsdTimeCode::Default()) const;
529
533 USDGEOM_API
534 void BlockIndices() const;
535
541 USDGEOM_API
542 bool IsIndexed() const;
543
546 USDGEOM_API
548
551 USDGEOM_API
553
566 USDGEOM_API
567 bool SetUnauthoredValuesIndex(int unauthoredValuesIndex) const;
568
572 USDGEOM_API
574
581 template <typename ScalarType>
583 UsdTimeCode time = UsdTimeCode::Default()) const;
584
592 USDGEOM_API
594 UsdTimeCode time=UsdTimeCode::Default()) const;
595
607 USDGEOM_API
608 static bool ComputeFlattened(VtValue *value, const VtValue &attrVal,
609 const VtIntArray &indices,
610 std::string *errString);
611
623 USDGEOM_API
624 static bool ComputeFlattened(VtValue *value, const VtValue &attrVal,
625 const VtIntArray &indices,
626 int elementSize,
627 std::string *errString);
628
629
631
632 // ---------------------------------------------------------------
662 // ---------------------------------------------------------------
663
667 USDGEOM_API
668 bool IsIdTarget() const;
669
674 USDGEOM_API
675 bool SetIdTarget(const SdfPath& path) const;
676
678
681 friend bool operator==(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
682 return lhs.GetAttr() == rhs.GetAttr();
683 }
684
687 friend bool operator!=(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
688 return !(lhs == rhs);
689 }
690
694 friend bool operator<(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs) {
695 return lhs.GetAttr().GetPath() < rhs.GetAttr().GetPath();
696 }
697
698 // Specialize TfHashAppend for TfHash
699 template <typename HashState>
700 friend void TfHashAppend(HashState& h, const UsdGeomPrimvar& obj) {
701 h.Append(obj.GetAttr());
702 }
703
704 // hash_value overload for std/boost hash.
705 friend size_t hash_value(const UsdGeomPrimvar &obj) {
706 return TfHash{}(obj);
707 }
708
709
710private:
711 friend class UsdGeomImageable;
712 friend class UsdGeomPrimvarsAPI;
713
716 static bool _IsNamespaced(const TfToken& name);
717
725 static TfToken _MakeNamespaced(const TfToken& name, bool quiet=false);
726
727 static TfToken const &_GetNamespacePrefix();
728
748 UsdGeomPrimvar(const UsdPrim& prim, const TfToken& attrName,
749 const SdfValueTypeName &typeName);
750
751 UsdAttribute _attr;
752
753 // Gets or creates the indices attribute corresponding to the primvar.
754 UsdAttribute _GetIndicesAttr(bool create) const;
755
756 // Helper method for computing the flattened value of an indexed primvar.
757 template<typename ScalarType>
758 static bool _ComputeFlattenedHelper(const VtArray<ScalarType> &authored,
759 const VtIntArray &indices,
760 int elementSize,
761 VtArray<ScalarType> *value,
762 std::string *errString);
763
764 // Helper function to evaluate the flattened array value of a primvar given
765 // the attribute value and the indices array.
766 template <typename ArrayType>
767 static bool _ComputeFlattenedArray(const VtValue &attrVal,
768 const VtIntArray &indices,
769 int elementSize,
770 VtValue *value,
771 std::string *errString);
772
773 // Should only be called if _idTargetRelName is set
774 UsdRelationship _GetIdTargetRel(bool create) const;
775
776 // Compute & cache whether or not this primvar can be an idtarget. After a
777 // call to this function, _idTargetStatus will be either IdTargetImpossible
778 // or IdTargetPossible. If the result is "possible" then _idTargetRelName
779 // will contain the relationship name. This function returns true if
780 // _idTargetStatus was set to IdTargetPossible, else false.
781 bool _ComputeIdTargetPossibility() const;
782
783 enum _IdTargetStatus {
784 IdTargetUninitialized,
785 IdTargetInitializing,
786 IdTargetImpossible,
787 IdTargetPossible };
788
789 mutable TfToken _idTargetRelName;
790 mutable std::atomic<_IdTargetStatus> _idTargetStatus;
791};
792
793// We instantiate the following so we can check and provide the correct value
794// for Id attributes.
795template <>
796USDGEOM_API bool UsdGeomPrimvar::Get(std::string* value, UsdTimeCode time) const;
797
798template <>
799USDGEOM_API bool UsdGeomPrimvar::Get(VtStringArray* value, UsdTimeCode time) const;
800
801template <>
802USDGEOM_API bool UsdGeomPrimvar::Get(VtValue* value, UsdTimeCode time) const;
803
804template <typename ScalarType>
805bool
807{
808 VtArray<ScalarType> authored;
809 if (!Get(&authored, time))
810 return false;
811
812 if (!IsIndexed()) {
813 *value = authored;
814 return true;
815 }
816
817 VtIntArray indices;
818 if (!GetIndices(&indices, time)) {
819 TF_WARN("No indices authored for indexed primvar <%s>.",
820 _attr.GetPath().GetText());
821 return false;
822 }
823
824 // If the authored array is empty, there's nothing to do.
825 if (authored.empty())
826 return false;
827
828 std::string errString;
829 bool res = _ComputeFlattenedHelper(authored, indices, GetElementSize(), value, &errString);
830 if (!errString.empty()) {
831 TF_WARN("For primvar %s: %s",
832 UsdDescribe(_attr).c_str(), errString.c_str());
833 }
834 return res;
835}
836
837template<typename ScalarType>
838bool
839UsdGeomPrimvar::_ComputeFlattenedHelper(const VtArray<ScalarType> &authored,
840 const VtIntArray &indices,
841 int elementSize,
842 VtArray<ScalarType> *value,
843 std::string *errString)
844{
845 TF_VERIFY(elementSize >= 1);
846 value->resize(indices.size() * elementSize);
847 bool success = true;
848
849 std::vector<size_t> invalidIndexPositions;
850 for (size_t i=0; i < indices.size(); i++) {
851 if (indices[i] < 0 || static_cast<size_t>((indices[i] + 1) * elementSize) > authored.size()) {
852 invalidIndexPositions.push_back(i);
853 success = false;
854 continue;
855 }
856
857 const size_t indicesIdx = indices[i] * elementSize;
858 const size_t valuesIdx = i * elementSize;
859 for (size_t j=0; j < static_cast<size_t>(elementSize); j++) {
860 size_t index = indicesIdx + j;
861 (*value)[valuesIdx + j] = authored[index];
862 }
863 }
864
865 if (!invalidIndexPositions.empty() && errString) {
866 *errString = TfStringPrintf(
867 "Found %ld invalid indices into authored array of size %ld with"
868 " element size of %i:",
869 invalidIndexPositions.size(),
870 authored.size(), elementSize);
871
872 // Print a maximum of 5 invalid index positions.
873 size_t numElementsToPrint = std::min(invalidIndexPositions.size(),
874 size_t(5));
875 for (size_t i = 0; i < numElementsToPrint ; ++i) {
876 int invalidIndex = indices[invalidIndexPositions[i]];
877 int authoredStartIndex = invalidIndex * elementSize;
878
879 *errString += TfStringPrintf(
880 "\n\t Invalid index %i at position %ld refers to %s of the"
881 " authored array, which is out of bounds",
882 invalidIndex,
883 invalidIndexPositions[i],
884 elementSize == 1 ? TfStringPrintf("index %i", authoredStartIndex).c_str()
885 : TfStringPrintf("indices [%i,...,%i]", authoredStartIndex, authoredStartIndex + elementSize - 1).c_str());
886 }
887 }
888 return success;
889}
890
891
892PXR_NAMESPACE_CLOSE_SCOPE
893
894#endif // USD_PRIMVAR_H
A basic mathematical interval class.
Definition: interval.h:33
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
SDF_API const char * GetText() const
Returns the string representation of this path as a c string.
Represents a value type name, i.e.
Definition: valueTypeName.h:71
A user-extensible hashing mechanism for use with runtime hash tables.
Definition: hash.h:460
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160
USD_API bool HasValue() const
Return true if this attribute has an authored default value, authored time samples or a fallback valu...
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time,...
Definition: attribute.h:461
USD_API SdfValueTypeName GetTypeName() const
Return the "scene description" value type name for this attribute.
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time,...
Definition: attribute.h:420
USD_API bool HasAuthoredValue() const
Return true if this attribute has either an authored default value or authored time samples.
Base class for all prims that may require rendering or visualization of some sort.
Definition: imageable.h:58
Schema wrapper for UsdAttribute for authoring and introspecting attributes that are primvars.
Definition: primvar.h:245
USDGEOM_API bool HasAuthoredElementSize() const
Has elementSize been explicitly authored on this Primvar?
USDGEOM_API bool GetTimeSamples(std::vector< double > *times) const
Populates a vector with authored sample times for this primvar.
TfToken GetBaseName() const
Definition: primvar.h:427
USDGEOM_API UsdGeomPrimvar(const UsdAttribute &attr)
Speculative constructor that will produce a valid UsdGeomPrimvar when attr already represents an attr...
static USDGEOM_API bool IsValidInterpolation(const TfToken &interpolation)
Validate that the provided interpolation is a valid setting for interpolation as defined by Interpola...
USDGEOM_API bool ComputeFlattened(VtValue *value, UsdTimeCode time=UsdTimeCode::Default()) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
bool ComputeFlattened(VtArray< ScalarType > *value, UsdTimeCode time=UsdTimeCode::Default()) const
Computes the flattened value of the primvar at time.
Definition: primvar.h:806
static USDGEOM_API bool IsPrimvar(const UsdAttribute &attr)
Test whether a given UsdAttribute represents valid Primvar, which implies that creating a UsdGeomPrim...
USDGEOM_API bool SetIndices(const VtIntArray &indices, UsdTimeCode time=UsdTimeCode::Default()) const
Sets the indices value of the indexed primvar at time.
USDGEOM_API bool NameContainsNamespaces() const
Does this primvar contain any namespaces other than the "primvars:" namespace?
static USDGEOM_API bool ComputeFlattened(VtValue *value, const VtValue &attrVal, const VtIntArray &indices, int elementSize, std::string *errString)
Computes the flattened value of attrValue given indices and elementSize.
friend bool operator!=(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs)
Inequality comparison.
Definition: primvar.h:687
USDGEOM_API int GetUnauthoredValuesIndex() const
Returns the index that represents unauthored values in the indices array.
USDGEOM_API bool IsIdTarget() const
Returns true if the primvar is an Id primvar.
USDGEOM_API UsdGeomPrimvar & operator=(const UsdGeomPrimvar &other)
Copy assign.
USDGEOM_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
Populates a vector with authored sample times in interval.
static USDGEOM_API TfToken StripPrimvarsName(const TfToken &name)
Returns the name, devoid of the "primvars:" token if present, otherwise returns the name unchanged.
TfToken GetNamespace() const
Definition: primvar.h:430
static USDGEOM_API bool ComputeFlattened(VtValue *value, const VtValue &attrVal, const VtIntArray &indices, std::string *errString)
Computes the flattened value of attrValue given indices, assuming an elementSize of 1.
friend bool operator==(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs)
Equality comparison.
Definition: primvar.h:681
USDGEOM_API bool SetElementSize(int eltSize)
Set the elementSize for this Primvar.
USDGEOM_API bool SetInterpolation(const TfToken &interpolation)
Set the Primvar's interpolation.
USDGEOM_API bool SetUnauthoredValuesIndex(int unauthoredValuesIndex) const
Set the index that represents unauthored values in the indices array.
USDGEOM_API int GetElementSize() const
Return the "element size" for this Primvar, which is 1 if unauthored.
USDGEOM_API TfToken GetPrimvarName() const
Returns the primvar's name, devoid of the "primvars:" namespace.
USDGEOM_API void GetDeclarationInfo(TfToken *name, SdfValueTypeName *typeName, TfToken *interpolation, int *elementSize) const
Convenience function for fetching all information required to properly declare this Primvar.
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the attribute value of the Primvar at time.
Definition: primvar.h:449
USDGEOM_API UsdAttribute CreateIndicesAttr() const
Returns the existing indices attribute if the primvar is indexed or creates a new one.
USDGEOM_API UsdGeomPrimvar(const UsdGeomPrimvar &other)
Copy construct.
bool IsDefined() const
Return true if the underlying UsdAttribute::IsDefined(), and in addition the attribute is identified ...
Definition: primvar.h:388
std::vector< std::string > SplitName() const
Definition: primvar.h:433
bool HasAuthoredValue() const
Return true if the underlying attribute has an unblocked, authored value.
Definition: primvar.h:396
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Get the attribute value of the Primvar at time .
Definition: primvar.h:443
static USDGEOM_API bool IsValidPrimvarName(const TfToken &name)
Test whether a given name represents a valid name of a primvar, which implies that creating a UsdGeom...
SdfValueTypeName GetTypeName() const
Definition: primvar.h:436
TfToken const & GetName() const
Definition: primvar.h:406
UsdAttribute const & GetAttr() const
Explicit UsdAttribute extractor.
Definition: primvar.h:383
USDGEOM_API TfToken GetInterpolation() const
Return the Primvar's interpolation, which is UsdGeomTokens->constant if unauthored.
USDGEOM_API bool SetIdTarget(const SdfPath &path) const
This primvar must be of String or StringArray type for this method to succeed.
USDGEOM_API bool IsIndexed() const
Returns true if the primvar is indexed, i.e., if it has an associated "indices" attribute.
USDGEOM_API UsdAttribute GetIndicesAttr() const
Returns a valid indices attribute if the primvar is indexed.
bool HasValue() const
Return true if the underlying attribute has a value, either from authored scene description or a fall...
Definition: primvar.h:392
USDGEOM_API bool HasAuthoredInterpolation() const
Has interpolation been explicitly authored on this Primvar?
USDGEOM_API void BlockIndices() const
Block the indices that were previously set.
friend bool operator<(const UsdGeomPrimvar &lhs, const UsdGeomPrimvar &rhs)
Less-than operator.
Definition: primvar.h:694
USDGEOM_API bool GetIndices(VtIntArray *indices, UsdTimeCode time=UsdTimeCode::Default()) const
Returns the value of the indices array associated with the indexed primvar at time.
USDGEOM_API bool ValueMightBeTimeVarying() const
Return true if it is possible, but not certain, that this primvar's value changes over time,...
UsdGeomPrimvarsAPI encodes geometric "primitive variables", as UsdGeomPrimvar, which interpolate acro...
Definition: primvarsAPI.h:66
SdfPath GetPath() const
Return the complete scene path to this object on its UsdStage, which may (UsdPrim) or may not (all ot...
Definition: object.h:186
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:221
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
USD_API TfToken GetBaseName() const
Return this property's name with all namespace prefixes removed, i.e.
USD_API TfToken GetNamespace() const
Return this property's complete namespace prefix.
USD_API std::vector< std::string > SplitName() const
Return this property's name elements including namespaces and its base name as the final element.
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:111
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:67
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:95
Represents an arbitrary dimensional rectangular container class.
Definition: array.h:211
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:147
USD_API std::string UsdDescribe(const UsdObject &)
Return a human-readable description.
size_t size() const
Return the total number of elements in this array.
Definition: array.h:472
bool empty() const
Return true if this array contains no elements, false otherwise.
Definition: array.h:500
void resize(size_t newSize)
Resize this array.
Definition: array.h:543
#define TF_WARN(...)
Issue a warning, but continue execution.
Definition: diagnostic.h:132
#define TF_VERIFY(cond, format,...)
Checks a condition and reports an error if it evaluates false.
Definition: diagnostic.h:266
TF_API std::string TfStringPrintf(const char *fmt,...)
Returns a string formed by a printf()-like specification.