attribute.h
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_ATTRIBUTE_H
25 #define PXR_USD_USD_ATTRIBUTE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/usd/common.h"
30 #include "pxr/usd/usd/property.h"
32 
33 #include "pxr/usd/sdf/abstractData.h"
34 #include "pxr/usd/sdf/path.h"
35 #include "pxr/usd/sdf/types.h"
36 #include "pxr/base/vt/value.h"
37 #include "pxr/base/gf/interval.h"
38 
39 #include <string>
40 #include <type_traits>
41 #include <vector>
42 
43 PXR_NAMESPACE_OPEN_SCOPE
44 
45 
46 class UsdAttribute;
47 
49 typedef std::vector<UsdAttribute> UsdAttributeVector;
50 
176 class UsdAttribute : public UsdProperty {
177 public:
180 
181  // --------------------------------------------------------------------- //
183  // --------------------------------------------------------------------- //
184 
186 
193  USD_API
195 
202  USD_API
203  bool SetVariability(SdfVariability variability) const;
204 
206  USD_API
208 
215  USD_API
216  bool SetTypeName(const SdfValueTypeName& typeName) const;
217 
219  USD_API
220  TfToken GetRoleName() const;
221 
223 
224  // --------------------------------------------------------------------- //
227  // --------------------------------------------------------------------- //
228 
230 
247  USD_API
248  bool GetTimeSamples(std::vector<double>* times) const;
249 
264  USD_API
265  bool GetTimeSamplesInInterval(const GfInterval& interval,
266  std::vector<double>* times) const;
267 
286  USD_API
287  static bool GetUnionedTimeSamples(const std::vector<UsdAttribute> &attrs,
288  std::vector<double> *times);
289 
309  USD_API
311  const std::vector<UsdAttribute> &attrs,
312  const GfInterval &interval,
313  std::vector<double> *times);
314 
324  USD_API
325  size_t GetNumTimeSamples() const;
326 
352  USD_API
353  bool GetBracketingTimeSamples(double desiredTime,
354  double* lower,
355  double* upper,
356  bool* hasTimeSamples) const;
357 
362  USD_API
363  bool HasValue() const;
364 
373  USD_API
374  bool HasAuthoredValueOpinion() const;
375 
379  USD_API
380  bool HasAuthoredValue() const;
381 
384  USD_API
385  bool HasFallbackValue() const;
386 
396  USD_API
397  bool ValueMightBeTimeVarying() const;
398 
430  template <typename T>
431  bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
432  static_assert(!std::is_const<T>::value, "");
433  static_assert(SdfValueTypeTraits<T>::IsValueType, "");
434  return _Get(value, time);
435  }
438  USD_API
439  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
440 
444  USD_API
447 
461  template <typename T>
462  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
463  static_assert(!std::is_pointer<T>::value, "");
464  static_assert(SdfValueTypeTraits<T>::IsValueType ||
465  std::is_same<T, SdfValueBlock>::value, "");
466  return _Set(value, time);
467  }
468 
472  USD_API
473  bool Set(const char* value, UsdTimeCode time = UsdTimeCode::Default()) const;
474 
476  USD_API
477  bool Set(const VtValue& value, UsdTimeCode time = UsdTimeCode::Default()) const;
478 
486  USD_API
487  bool Clear() const;
488 
495  USD_API
496  bool ClearAtTime(UsdTimeCode time) const;
497 
499  USD_API
500  bool ClearDefault() const;
501 
508  USD_API
509  void Block() const;
510 
512 
515 
526  USD_API
527  bool AddConnection(const SdfPath& source,
529 
535  USD_API
536  bool RemoveConnection(const SdfPath& source) const;
537 
546  USD_API
547  bool SetConnections(const SdfPathVector& sources) const;
548 
551  USD_API
552  bool ClearConnections() const;
553 
567  USD_API
568  bool GetConnections(SdfPathVector* sources) const;
569 
574  USD_API
575  bool HasAuthoredConnections() const;
576 
578 
579  // ---------------------------------------------------------------------- //
590  // ---------------------------------------------------------------------- //
591 
595  USD_API
596  TfToken GetColorSpace() const;
597 
601  USD_API
602  void SetColorSpace(const TfToken &colorSpace) const;
603 
606  USD_API
607  bool HasColorSpace() const;
608 
611  USD_API
612  bool ClearColorSpace() const;
613 
615 
616  // ---------------------------------------------------------------------- //
617  // Private Methods and Members
618  // ---------------------------------------------------------------------- //
619 private:
620  friend class UsdAttributeQuery;
621  friend class UsdObject;
622  friend class UsdPrim;
623  friend class UsdSchemaBase;
624  friend class Usd_PrimData;
625  friend struct UsdPrim_AttrConnectionFinder;
626 
627  UsdAttribute(const Usd_PrimDataHandle &prim,
628  const SdfPath &proxyPrimPath,
629  const TfToken &attrName)
630  : UsdProperty(UsdTypeAttribute, prim, proxyPrimPath, attrName) {}
631 
632  UsdAttribute(UsdObjType objType,
633  const Usd_PrimDataHandle &prim,
634  const SdfPath &proxyPrimPath,
635  const TfToken &propName)
636  : UsdProperty(objType, prim, proxyPrimPath, propName) {}
637 
638  SdfAttributeSpecHandle
639  _CreateSpec(const SdfValueTypeName &typeName, bool custom,
640  const SdfVariability &variability) const;
641 
642  // Like _CreateSpec(), but fail if this attribute is not built-in and there
643  // isn't already existing scene description to go on rather than stamping
644  // new information.
645  SdfAttributeSpecHandle _CreateSpec() const;
646 
647  bool _Create(const SdfValueTypeName &typeName, bool custom,
648  const SdfVariability &variability) const;
649 
650  template <typename T>
651  bool _Get(T* value, UsdTimeCode time) const;
652 
653  template <typename T>
654  bool _Set(const T& value, UsdTimeCode time) const;
655 
656  SdfPath
657  _GetPathForAuthoring(const SdfPath &path, std::string* whyNot) const;
658 };
659 
660 PXR_NAMESPACE_CLOSE_SCOPE
661 
662 #endif // PXR_USD_USD_ATTRIBUTE_H
USD_API bool SetVariability(SdfVariability variability) const
Set the value for variability at the current EditTarget, return true on success, false if the value c...
USD_API UsdResolveInfo GetResolveInfo(UsdTimeCode time=UsdTimeCode::Default()) const
Perform value resolution to determine the source of the resolved value of this attribute at the reque...
USD_API SdfVariability GetVariability() const
An attribute's variability expresses whether it is intended to have time-samples (SdfVariabilityVaryi...
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:431
UsdObjType
Enum values to represent the various Usd object types.
Definition: object.h:49
UsdListPosition
Specifies a position to add items to lists.
Definition: common.h:88
USD_API bool AddConnection(const SdfPath &source, UsdListPosition position=UsdListPositionBackOfPrependList) const
Adds source to the list of connections, in the position specified by position.
USD_API bool SetConnections(const SdfPathVector &sources) const
Make the authoring layer's opinion of the connection list explicit, and set exactly to sources.
Object for efficiently making repeated queries for attribute values.
USD_API bool HasValue() const
Return true if this attribute has an authored default value, authored time samples or a fallback valu...
USD_API bool HasAuthoredConnections() const
Return true if this attribute has any authored opinions regarding connections.
USD_API TfToken GetColorSpace() const
Gets the color space in which the attribute is authored.
Represents a value type name, i.e.
Definition: valueTypeName.h:87
USD_API bool HasColorSpace() const
Returns whether color-space is authored on the attribute.
USD_API bool RemoveConnection(const SdfPath &source) const
Removes target from the list of targets.
Container for information about the source of an attribute's value, i.e.
Definition: resolveInfo.h:68
static USD_API bool GetUnionedTimeSamples(const std::vector< UsdAttribute > &attrs, std::vector< double > *times)
Populates the given vector, times with the union of all the authored sample times on all of the given...
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
UsdAttribute()
Construct an invalid attribute.
Definition: attribute.h:179
Basic Sdf data types.
USD_API TfToken GetRoleName() const
Return the roleName for this attribute's typeName.
USD_API bool ClearDefault() const
Shorthand for ClearAtTime(UsdTimeCode::Default()).
USD_API bool ClearAtTime(UsdTimeCode time) const
Clear the authored value for this attribute at the given time, at the current EditTarget and return t...
USD_API bool ClearColorSpace() const
Clears authored color-space value on the attribute.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
USD_API bool HasAuthoredValueOpinion() const
USD_API bool SetTypeName(const SdfValueTypeName &typeName) const
Set the value for typeName at the current EditTarget, return true on success, false if the value can ...
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
USD_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
Populates a vector with authored sample times in interval.
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:130
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:132
A basic mathematical interval class.
Definition: interval.h:50
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:288
USD_API void SetColorSpace(const TfToken &colorSpace) const
Sets the color space of the attribute to colorSpace.
USD_API bool GetTimeSamples(std::vector< double > *times) const
Populates a vector with authored sample times.
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:462
USD_API bool GetBracketingTimeSamples(double desiredTime, double *lower, double *upper, bool *hasTimeSamples) const
Populate lower and upper with the next greater and lesser value relative to the desiredTime.
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:179
USD_API bool ValueMightBeTimeVarying() const
Return true if it is possible, but not certain, that this attribute's value changes over time,...
USD_API bool GetConnections(SdfPathVector *sources) const
Compose this attribute's connections and fill sources with the result.
USD_API void Block() const
Remove all time samples on an attribute and author a block default value.
USD_API bool HasFallbackValue() const
Return true if this attribute has a fallback value provided by a registered schema.
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:55
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:113
USD_API size_t GetNumTimeSamples() const
Returns the number of time samples that have been authored.
The position at the back of the prepend list.
Definition: common.h:98
USD_API bool ClearConnections() const
Remove all opinions about the connections list from the current edit target.
USD_API SdfValueTypeName GetTypeName() const
Return the "scene description" value type name for this attribute.
The base class for all schema types in Usd.
Definition: schemaBase.h:56
USD_API bool HasAuthoredValue() const
Return true if this attribute has either an authored default value or authored time samples.
static USD_API bool GetUnionedTimeSamplesInInterval(const std::vector< UsdAttribute > &attrs, const GfInterval &interval, std::vector< double > *times)
Populates the given vector, times with the union of all the authored sample times in the GfInterval,...
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:168
USD_API bool Clear() const
Clears the authored default value and all time samples for this attribute at the current EditTarget a...