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 
443  USD_API
445  GetResolveInfo(UsdTimeCode time) const;
446 
454  USD_API
456  GetResolveInfo() const;
457 
471  template <typename T>
472  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
473  static_assert(!std::is_pointer<T>::value, "");
474  static_assert(SdfValueTypeTraits<T>::IsValueType ||
475  std::is_same<T, SdfValueBlock>::value, "");
476  return _Set(value, time);
477  }
478 
482  USD_API
483  bool Set(const char* value, UsdTimeCode time = UsdTimeCode::Default()) const;
484 
486  USD_API
487  bool Set(const VtValue& value, UsdTimeCode time = UsdTimeCode::Default()) const;
488 
496  USD_API
497  bool Clear() const;
498 
505  USD_API
506  bool ClearAtTime(UsdTimeCode time) const;
507 
509  USD_API
510  bool ClearDefault() const;
511 
518  USD_API
519  void Block() const;
520 
522 
525 
536  USD_API
537  bool AddConnection(const SdfPath& source,
539 
545  USD_API
546  bool RemoveConnection(const SdfPath& source) const;
547 
556  USD_API
557  bool SetConnections(const SdfPathVector& sources) const;
558 
561  USD_API
562  bool ClearConnections() const;
563 
577  USD_API
578  bool GetConnections(SdfPathVector* sources) const;
579 
584  USD_API
585  bool HasAuthoredConnections() const;
586 
588 
589  // ---------------------------------------------------------------------- //
600  // ---------------------------------------------------------------------- //
601 
605  USD_API
606  TfToken GetColorSpace() const;
607 
611  USD_API
612  void SetColorSpace(const TfToken &colorSpace) const;
613 
616  USD_API
617  bool HasColorSpace() const;
618 
621  USD_API
622  bool ClearColorSpace() const;
623 
625 
626  // ---------------------------------------------------------------------- //
627  // Private Methods and Members
628  // ---------------------------------------------------------------------- //
629 private:
630  friend class UsdAttributeQuery;
631  friend class UsdObject;
632  friend class UsdPrim;
633  friend class UsdSchemaBase;
634  friend class Usd_PrimData;
635  friend struct UsdPrim_AttrConnectionFinder;
636 
637  UsdAttribute(const Usd_PrimDataHandle &prim,
638  const SdfPath &proxyPrimPath,
639  const TfToken &attrName)
640  : UsdProperty(UsdTypeAttribute, prim, proxyPrimPath, attrName) {}
641 
642  UsdAttribute(UsdObjType objType,
643  const Usd_PrimDataHandle &prim,
644  const SdfPath &proxyPrimPath,
645  const TfToken &propName)
646  : UsdProperty(objType, prim, proxyPrimPath, propName) {}
647 
648  SdfAttributeSpecHandle
649  _CreateSpec(const SdfValueTypeName &typeName, bool custom,
650  const SdfVariability &variability) const;
651 
652  // Like _CreateSpec(), but fail if this attribute is not built-in and there
653  // isn't already existing scene description to go on rather than stamping
654  // new information.
655  SdfAttributeSpecHandle _CreateSpec() const;
656 
657  bool _Create(const SdfValueTypeName &typeName, bool custom,
658  const SdfVariability &variability) const;
659 
660  template <typename T>
661  bool _Get(T* value, UsdTimeCode time) const;
662 
663  template <typename T>
664  bool _Set(const T& value, UsdTimeCode time) const;
665 
666  SdfPath
667  _GetPathForAuthoring(const SdfPath &path, std::string* whyNot) const;
668 };
669 
670 PXR_NAMESPACE_CLOSE_SCOPE
671 
672 #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 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:135
A basic mathematical interval class.
Definition: interval.h:49
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
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:472
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.
USD_API UsdResolveInfo GetResolveInfo() const
Perform value resolution to determine the source of the resolved value of this attribute at any non-d...
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:166
USD_API bool Clear() const
Clears the authored default value and all time samples for this attribute at the current EditTarget a...