HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
attributeSpec.h
Go to the documentation of this file.
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_SDF_ATTRIBUTE_SPEC_H
8 #define PXR_USD_SDF_ATTRIBUTE_SPEC_H
9 
10 /// \file sdf/attributeSpec.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/sdf/api.h"
15 #include "pxr/usd/sdf/path.h"
17 #include "pxr/usd/sdf/types.h"
18 #include "pxr/base/tf/enum.h"
19 
21 
22 /// \class SdfAttributeSpec
23 ///
24 /// A subclass of SdfPropertySpec that holds typed data.
25 ///
26 /// Attributes are typed data containers that can optionally hold any
27 /// and all of the following:
28 /// \li A single default value.
29 /// \li An array of knot values describing how the value varies over time.
30 /// \li A dictionary of posed values, indexed by name.
31 ///
32 /// The values contained in an attribute must all be of the same type. In the
33 /// Python API the \c typeName property holds the attribute type. In the C++
34 /// API, you can get the attribute type using the GetTypeName() method. In
35 /// addition, all values, including all knot values, must be the same shape.
36 /// For information on shapes, see the VtShape class reference in the C++
37 /// documentation.
38 ///
40 {
41  SDF_DECLARE_SPEC(SdfAttributeSpec, SdfPropertySpec);
42 
43 public:
46 
47  ///
48  /// \name Spec construction
49  /// @{
50 
51  /// Constructs a new prim attribute instance.
52  ///
53  /// Creates and returns a new attribute for the given prim.
54  /// The \p owner will own the newly created attribute.
55  SDF_API
56  static SdfAttributeSpecHandle
57  New(const SdfPrimSpecHandle& owner,
58  const std::string& name, const SdfValueTypeName& typeName,
60  bool custom = false);
61 
62  /// @}
63 
64  /// \name Connections
65  /// @{
66 
67  /// Returns a proxy for editing the attribute's connection paths.
68  ///
69  /// The returned proxy, which is an SdfListEditorProxy, modifies the
70  /// SdfListOp that represents this attribute's connections.
71  SDF_API
73 
74  /// Returns \c true if any connection paths are set on this attribute.
75  SDF_API
76  bool HasConnectionPaths() const;
77 
78  /// Clears the connection paths for this attribute.
79  SDF_API
80  void ClearConnectionPaths();
81 
82  /// @}
83  /// \name Attribute value API
84  /// @{
85 
86  /// Returns the allowed tokens metadata for this attribute.
87  /// Consumers may use this metadata to define a set of predefined
88  /// options for this attribute's value. However, this metadata is
89  /// purely advisory. It is up to the consumer to perform any
90  /// validation against this set of tokens, if desired.
91  SDF_API
92  VtTokenArray GetAllowedTokens() const;
93 
94  /// Sets the allowed tokens metadata for this attribute.
95  SDF_API
96  void SetAllowedTokens(const VtTokenArray& allowedTokens);
97 
98  /// Returns true if allowed tokens metadata is set for this attribute.
99  SDF_API
100  bool HasAllowedTokens() const;
101 
102  /// Clears the allowed tokens metadata for this attribute.
103  SDF_API
104  void ClearAllowedTokens();
105 
106  /// Returns the display unit of the attribute.
107  SDF_API
108  TfEnum GetDisplayUnit() const;
109 
110  /// Sets the display unit of the attribute.
111  SDF_API
112  void SetDisplayUnit(const TfEnum& displayUnit);
113 
114  /// Returns true if a display unit is set for this attribute.
115  SDF_API
116  bool HasDisplayUnit() const;
117 
118  /// Clears the display unit of the attribute.
119  SDF_API
120  void ClearDisplayUnit();
121 
122  /// Returns the color space in which a color or texture valued attribute
123  /// is authored. Refer to GfColorSpaceNames for the list of built in
124  /// color spaces.
125  SDF_API
126  TfToken GetColorSpace() const;
127 
128  /// Sets the color space in which a color or texture valued attribute is
129  /// authored.
130  SDF_API
131  void SetColorSpace(const TfToken &colorSpace);
132 
133  /// Returns true if this attribute has a colorSpace value authored.
134  SDF_API
135  bool HasColorSpace() const;
136 
137  /// Clears the colorSpace metadata value set on this attribute.
138  SDF_API
139  void ClearColorSpace();
140 
141  /// @}
142  /// \name Spec properties
143  /// @{
144 
145  /// Returns the roleName for this attribute's typeName.
146  ///
147  /// If the typeName has no roleName, return empty token.
148  SDF_API
149  TfToken GetRoleName() const;
150 
151  /// @}
152 
153  /// \name Time-sample API
154  /// @{
155  /// Returns the entire set of time samples.
156  SDF_API
158 
159  SDF_API
160  std::set<double> ListTimeSamples() const;
161 
162  SDF_API
163  size_t GetNumTimeSamples() const;
164 
165  SDF_API
166  bool GetBracketingTimeSamples(double time, double* tLower,
167  double* tUpper) const;
168 
169  SDF_API
170  bool QueryTimeSample(double time, VtValue *value=NULL) const;
171  SDF_API
172  bool QueryTimeSample(double time, SdfAbstractDataValue *value) const;
173 
174  template <class T>
175  bool QueryTimeSample(double time, T* data) const
176  {
177  if (!data) {
178  return QueryTimeSample(time);
179  }
180 
181  SdfAbstractDataTypedValue<T> outValue(data);
182  const bool hasValue = QueryTimeSample(
183  time, static_cast<SdfAbstractDataValue *>(&outValue));
184 
186  return hasValue && outValue.isValueBlock;
187  }
188 
189  return hasValue && (!outValue.isValueBlock);
190  }
191 
192  SDF_API
193  void SetTimeSample(double time, const VtValue & value);
194  SDF_API
195  void SetTimeSample(double time, const SdfAbstractDataConstValue& value);
196 
197  template <class T>
198  void SetTimeSample(double time, const T& value)
199  {
200  const SdfAbstractDataConstTypedValue<T> inValue(&value);
201  const SdfAbstractDataConstValue& untypedInValue = inValue;
202  return SetTimeSample(time, untypedInValue);
203  }
204 
205  SDF_API
206  void EraseTimeSample(double time);
207 
208  /// @}
209 };
210 
211 /// Convenience function to create an attributeSpec on a primSpec at the given
212 /// path, and any necessary parent primSpecs, in the given layer.
213 ///
214 /// If an attributeSpec already exists at the given path,
215 /// author typeName, variability, and custom according to passed arguments
216 /// and return an attribute spec handle.
217 ///
218 /// Any newly created prim specs have SdfSpecifierOver and an empty type (as if
219 /// created by SdfJustCreatePrimInLayer()). attrPath must be a valid prim
220 /// property path (see SdfPath::IsPrimPropertyPath()). Return false and issue
221 /// an error if we fail to author the required scene description.
222 SDF_API
223 SdfAttributeSpecHandle
225  const SdfLayerHandle &layer,
226  const SdfPath &attrPath,
227  const SdfValueTypeName &typeName,
229  bool isCustom = false);
230 
231 /// Convenience function to create an attributeSpec on a primSpec at the given
232 /// path, and any necessary parent primSpecs, in the given layer.
233 ///
234 /// If an attributeSpec already exists at the given path, just author typeName,
235 /// variability, and custom according to passed arguments and return true.
236 ///
237 /// Any newly created prim specs have SdfSpecifierOver and an empty type (as if
238 /// created by SdfJustCreatePrimInLayer()). attrPath must be a valid prim
239 /// property path (see SdfPath::IsPrimPropertyPath()). Return false and issue
240 /// an error if we fail to author the required scene description.
241 ///
242 /// Differs only from SdfCreatePrimAttributeInLayer only in that a bool, not
243 /// a handle, is returned.
244 SDF_API
245 bool
247  const SdfLayerHandle &layer,
248  const SdfPath &attrPath,
249  const SdfValueTypeName &typeName,
251  bool isCustom = false);
252 
254 
255 #endif // PXR_USD_SDF_ATTRIBUTE_SPEC_H
SDF_API SdfConnectionsProxy GetConnectionPathList() const
SDF_API bool QueryTimeSample(double time, VtValue *value=NULL) const
GT_API const UT_StringHolder time
GLsizei const GLfloat * value
Definition: glcorearb.h:824
static SDF_API SdfAttributeSpecHandle New(const SdfPrimSpecHandle &owner, const std::string &name, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying, bool custom=false)
SdfAttributeSpec This
Definition: attributeSpec.h:44
SDF_API bool HasConnectionPaths() const
Returns true if any connection paths are set on this attribute.
Definition: enum.h:119
SdfPropertySpec Parent
Definition: attributeSpec.h:45
SDF_API VtTokenArray GetAllowedTokens() const
bool QueryTimeSample(double time, T *data) const
SDF_API void ClearAllowedTokens()
Clears the allowed tokens metadata for this attribute.
SDF_API void ClearColorSpace()
Clears the colorSpace metadata value set on this attribute.
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
SDF_API void EraseTimeSample(double time)
Definition: token.h:70
SDF_API bool SdfJustCreatePrimAttributeInLayer(const SdfLayerHandle &layer, const SdfPath &attrPath, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying, bool isCustom=false)
SDF_API bool HasColorSpace() const
Returns true if this attribute has a colorSpace value authored.
SDF_API SdfTimeSampleMap GetTimeSampleMap() const
SDF_API bool HasAllowedTokens() const
Returns true if allowed tokens metadata is set for this attribute.
SDF_API size_t GetNumTimeSamples() const
void SetTimeSample(double time, const T &value)
SDF_API std::set< double > ListTimeSamples() const
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:273
SDF_API void ClearDisplayUnit()
Clears the display unit of the attribute.
SdfVariability
Definition: types.h:156
#define SDF_API
Definition: api.h:23
SDF_API void SetDisplayUnit(const TfEnum &displayUnit)
Sets the display unit of the attribute.
SDF_API void SetColorSpace(const TfToken &colorSpace)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
SDF_API void ClearConnectionPaths()
Clears the connection paths for this attribute.
SDF_API TfToken GetColorSpace() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
SDF_API SdfAttributeSpecHandle SdfCreatePrimAttributeInLayer(const SdfLayerHandle &layer, const SdfPath &attrPath, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying, bool isCustom=false)
SDF_API bool GetBracketingTimeSamples(double time, double *tLower, double *tUpper) const
SDF_API TfToken GetRoleName() const
SDF_API bool HasDisplayUnit() const
Returns true if a display unit is set for this attribute.
std::map< double, VtValue > SdfTimeSampleMap
A map from sample times to sample values.
Definition: types.h:277
Definition: value.h:146
Definition: format.h:1821
SDF_API TfEnum GetDisplayUnit() const
Returns the display unit of the attribute.
SDF_API void SetTimeSample(double time, const VtValue &value)
SDF_API void SetAllowedTokens(const VtTokenArray &allowedTokens)
Sets the allowed tokens metadata for this attribute.