HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
attribute.h
Go to the documentation of this file.
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 
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 
44 
45 
47 
48 /// A std::vector of UsdAttributes.
49 typedef std::vector<UsdAttribute> UsdAttributeVector;
50 
51 /// \class UsdAttribute
52 ///
53 /// Scenegraph object for authoring and retrieving numeric, string, and array
54 /// valued data, sampled over time.
55 ///
56 /// The allowed value types for UsdAttribute are dictated by the Sdf
57 /// ("Scene Description Foundations") core's data model, which we summarize in
58 /// \ref Usd_Page_Datatypes .
59 ///
60 /// \section Usd_AttributeQualities Attribute Defining Qualities
61 ///
62 /// In addition to its value type, an Attribute has two other defining
63 /// qualities:
64 /// \li <b>Variability</b> Expresses whether an attribute is intended to
65 /// have time samples (GetVariability() == \c SdfVariabilityVarying), or only
66 /// a default (GetVariability() == \c SdfVariabilityUniform). For more on
67 /// reasoning about time samples,
68 /// see \ref Usd_AttributeValueMethods "Value & Time-Sample Accessors".
69 ///
70 /// \li <b>Custom</b> Determines whether an attribute belongs to a
71 /// schema (IsCustom() == \c false), or is a user-defined, custom attribute.
72 /// schema attributes will always be defined on a prim of the schema type,
73 /// ans may possess fallback values from the schema, whereas custom
74 /// attributes must always first be authored in order to be defined. Note
75 /// that \em custom is actually an aspect of UsdProperty, as UsdRelationship
76 /// can also be custom or provided by a schema.
77 ///
78 /// \section Usd_AttributeExistence Attribute Creation and Existence
79 ///
80 /// One can always create an attribute generically via
81 /// UsdPrim::CreateAttribute(), which ensures that an attribute "is defined"
82 /// in the current \ref UsdEditTarget . In order to author any metadata or
83 /// a default or timesample for an attribute, <em>it must first be defined</em>.
84 /// It is sufficient that the attribute be defined in any one of the layers
85 /// participating in the stage's current composition; for \em builtin
86 /// attributes (those belonging to the owning prim's defining schema, i.e.
87 /// the most specific subclass of UsdTypedSchema for which prim.IsA<schema>()
88 /// will evaluate to true) there need be no authored scene description, because
89 /// a definition is provided by the prim's schema definition.
90 ///
91 /// <b>Creating</b> an attribute does not imply that the attribute has a value.
92 /// More broadly, in the following code:
93 /// \code
94 /// if (UsdAttribute attr = prim.GetAttribute(TfToken("myAttr"))){
95 /// ...
96 /// }
97 /// \endcode
98 ///
99 /// The UsdAttribute passes the bool test, because it is defined; however,
100 /// inside the clause, we have no guarantee that attr has a value.
101 ///
102 /// \section Usd_AttributeInterpolation Attribute Value Interpolation
103 ///
104 /// UsdAttribute supports two interpolation behaviors when retrieving
105 /// attribute values at times where no value is explicitly authored.
106 /// The desired behavior may be specified via UsdStage::SetInterpolationType.
107 /// That behavior will be used for all calls to UsdAttribute::Get.
108 ///
109 /// The supported interpolation types are:
110 ///
111 /// \li <b>Held</b> Attribute values are held constant between authored
112 /// values. An attribute's value will be equal to the nearest preceding
113 /// authored value. If there is no preceding authored value, the value
114 /// will be equal to the nearest subsequent value.
115 ///
116 /// \li <b>Linear</b> Attribute values are linearly interpolated between
117 /// authored values.
118 ///
119 /// Linear interpolation is only supported for certain data types. See
120 /// \ref USD_LINEAR_INTERPOLATION_TYPES for the list of these types. Types
121 /// that do not support linear interpolation will use held interpolation
122 /// instead.
123 ///
124 /// Linear interpolation is done element-by-element for array, vector,
125 /// and matrix data types. If linear interpolation is requested for
126 /// two array values with different sizes, held interpolation will
127 /// be used instead.
128 ///
129 /// \section Usd_AttributeBlocking Attribute Value Blocking
130 ///
131 /// While prims can effectively be removed from a scene by
132 /// \ref Usd_ActiveInactive "deactivating them," properties cannot. However,
133 /// it is possible to **block an attribute's value**, thus making the attribute
134 /// behave as if it has a definition (and possibly metadata), but no authored
135 /// value.
136 ///
137 ///
138 /// One blocks an attribute using UsdAttribute::Block(), which will block the
139 /// attribute in the stage's current UsdEditTarget, by authoring an
140 /// SdfValueBlock in the attribute's *default*, and only values authored in
141 /// weaker layers than the editTarget will be blocked. If the value block is
142 /// the strongest authored opinion for the attribute, the HasAuthoredValue()
143 /// method will return *false*, and the HasValue() and Get() methods will
144 /// only return *true* if the attribute possesses a fallback value from the
145 /// prim's schema. "Unblocking" a blocked attribute is as simple as setting
146 /// a *default* or timeSample value for the attribute in the same or stronger
147 /// layer.
148 ///
149 /// \subsection Usd_TimeVaryingAttributeBlocks Time-varying Blocks
150 ///
151 /// The semantics of \ref Usd_ValueClips_Overview "Value Clips" necessitate
152 /// the ability to selectively block an attribute's value for only some intervals
153 /// in its authored range of samples. One can block an attribute's value at
154 /// time *t* by calling `attr.Set(SdfValueBlock, t)` When an attribute is thusly
155 /// "partially blocked", UsdAttribute::Get() will succeed only for those time
156 /// intervals whose left/earlier bracketing timeSample is **not** SdfValueBlock.
157 ///
158 /// Due to this time-varying potential of value blocking, it may be the case
159 /// that an attribute's HasAuthoredValue() and HasValue() methods both return
160 /// *true* (because they do not and cannot consider time-varying blocks), but
161 /// Get() may yet return *false* over some intervals.
162 ///
163 /// \section Usd_AssetPathValuedAttributes Attributes of type SdfAssetPath and UsdAttribute::Get()
164 ///
165 /// If an attribute's value type is SdfAssetPath or SdfAssetPathArray, Get()
166 /// performs extra work to compute the resolved asset paths, using the layer
167 /// that has the strongest value opinion as the anchor for "relative" asset
168 /// paths. Both the unresolved and resolved results are available through
169 /// SdfAssetPath::GetAssetPath() and SdfAssetPath::GetResolvedPath(),
170 /// respectively.
171 ///
172 /// Clients that call Get() on many asset-path-valued attributes may wish to
173 /// employ an ArResolverScopedCache to improve asset path resolution
174 /// performance.
175 ///
176 class UsdAttribute : public UsdProperty {
177 public:
178  /// Construct an invalid attribute.
180 
181  // --------------------------------------------------------------------- //
182  /// \name Core Metadata
183  // --------------------------------------------------------------------- //
184 
185  /// @{
186 
187  /// An attribute's variability expresses whether it is intended to have
188  /// time-samples (\c SdfVariabilityVarying), or only a single default
189  /// value (\c SdfVariabilityUniform).
190  ///
191  /// Variability is required meta-data of all attributes, and its fallback
192  /// value is SdfVariabilityVarying.
193  USD_API
195 
196  /// Set the value for variability at the current EditTarget, return true
197  /// on success, false if the value can not be written.
198  ///
199  /// \b Note that this value should not be changed as it is typically either
200  /// automatically authored or provided by a property definition. This method
201  /// is provided primarily for fixing invalid scene description.
202  USD_API
203  bool SetVariability(SdfVariability variability) const;
204 
205  /// Return the "scene description" value type name for this attribute.
206  USD_API
208 
209  /// Set the value for typeName at the current EditTarget, return true on
210  /// success, false if the value can not be written.
211  ///
212  /// \b Note that this value should not be changed as it is typically either
213  /// automatically authored or provided by a property definition. This method
214  /// is provided primarily for fixing invalid scene description.
215  USD_API
216  bool SetTypeName(const SdfValueTypeName& typeName) const;
217 
218  /// Return the roleName for this attribute's typeName.
219  USD_API
220  TfToken GetRoleName() const;
221 
222  /// @}
223 
224  // --------------------------------------------------------------------- //
225  /// \anchor Usd_AttributeValueMethods
226  /// \name Value & Time-Sample Accessors
227  // --------------------------------------------------------------------- //
228 
229  /// @{
230 
231  /// Populates a vector with authored sample times.
232  /// Returns false only on error.
233  ///
234  /// This method uses the standard resolution semantics, so if a stronger
235  /// default value is authored over weaker time samples, the default value
236  /// will hide the underlying timesamples.
237  ///
238  /// \note This function will query all value clips that may contribute
239  /// time samples for this attribute, opening them if needed. This may be
240  /// expensive, especially if many clips are involved.
241  ///
242  /// \param times - on return, will contain the \em sorted, ascending
243  /// timeSample ordinates. Any data in \p times will be lost, as this
244  /// method clears \p times.
245  ///
246  /// \sa UsdAttribute::GetTimeSamplesInInterval
247  USD_API
248  bool GetTimeSamples(std::vector<double>* times) const;
249 
250  /// Populates a vector with authored sample times in \p interval.
251  /// Returns false only on an error.
252  ///
253  /// \note This function will only query the value clips that may
254  /// contribute time samples for this attribute in the given interval,
255  /// opening them if necessary.
256  ///
257  /// \param interval - the \ref GfInterval on which to gather time samples.
258  ///
259  /// \param times - on return, will contain the \em sorted, ascending
260  /// timeSample ordinates. Any data in \p times will be lost, as this
261  /// method clears \p times.
262  ///
263  /// \sa UsdAttribute::GetTimeSamples
264  USD_API
265  bool GetTimeSamplesInInterval(const GfInterval& interval,
266  std::vector<double>* times) const;
267 
268  /// Populates the given vector, \p times with the union of all the
269  /// authored sample times on all of the given attributes, \p attrs.
270  ///
271  /// \note This function will query all value clips that may contribute
272  /// time samples for the attributes in \p attrs, opening them if needed.
273  /// This may be expensive, especially if many clips are involved.
274  ///
275  /// The accumulated sample times will be in sorted (increasing) order and
276  /// will not contain any duplicates.
277  ///
278  /// This clears any existing values in the \p times vector before
279  /// accumulating sample times of the given attributes.
280  ///
281  /// \return false if any of the attributes in \p attr are invalid or if
282  /// there's an error when fetching time-samples for any of the attributes.
283  ///
284  /// \sa UsdAttribute::GetTimeSamples
285  /// \sa UsdAttribute::GetUnionedTimeSamplesInInterval
286  USD_API
287  static bool GetUnionedTimeSamples(const std::vector<UsdAttribute> &attrs,
288  std::vector<double> *times);
289 
290  /// Populates the given vector, \p times with the union of all the
291  /// authored sample times in the GfInterval, \p interval on all of the
292  /// given attributes, \p attrs.
293  ///
294  /// \note This function will only query the value clips that may
295  /// contribute time samples for the attributes in \p attrs, in the
296  /// given \p interval, opening them if necessary.
297  ///
298  /// The accumulated sample times will be in sorted (increasing) order and
299  /// will not contain any duplicates.
300  ///
301  /// This clears any existing values in the \p times vector before
302  /// accumulating sample times of the given attributes.
303  ///
304  /// \return false if any of the attributes in \p attr are invalid or if
305  /// there's an error fetching time-samples for any of the attributes.
306  ///
307  /// \sa UsdAttribute::GetTimeSamplesInInterval
308  /// \sa UsdAttribute::GetUnionedTimeSamples
309  USD_API
311  const std::vector<UsdAttribute> &attrs,
312  const GfInterval &interval,
313  std::vector<double> *times);
314 
315  /// Returns the number of time samples that have been authored.
316  ///
317  /// This method uses the standard resolution semantics, so if a stronger
318  /// default value is authored over weaker time samples, the default value
319  /// will hide the underlying timesamples.
320  ///
321  /// \note This function will query all value clips that may contribute
322  /// time samples for this attribute, opening them if needed. This may be
323  /// expensive, especially if many clips are involved.
324  USD_API
325  size_t GetNumTimeSamples() const;
326 
327  /// Populate \a lower and \a upper with the next greater and lesser
328  /// value relative to the \a desiredTime. Return false if no value exists
329  /// or an error occurs, true if either a default value or timeSamples exist.
330  ///
331  /// Use standard resolution semantics: if a stronger default value is
332  /// authored over weaker time samples, the default value hides the
333  /// underlying timeSamples.
334  ///
335  /// 1) If a sample exists at the \a desiredTime, set both upper and lower
336  /// to \a desiredTime.
337  ///
338  /// 2) If samples exist surrounding, but not equal to the \a desiredTime,
339  /// set lower and upper to the bracketing samples nearest to the
340  /// \a desiredTime.
341  ///
342  /// 3) If the \a desiredTime is outside of the range of authored samples,
343  /// clamp upper and lower to the nearest time sample.
344  ///
345  /// 4) If no samples exist, do not modify upper and lower and set
346  /// \a hasTimeSamples to false.
347  ///
348  /// In cases (1), (2) and (3), set \a hasTimeSamples to true.
349  ///
350  /// All four cases above are considered to be successful, thus the return
351  /// value will be true and no error message will be emitted.
352  USD_API
353  bool GetBracketingTimeSamples(double desiredTime,
354  double* lower,
355  double* upper,
356  bool* hasTimeSamples) const;
357 
358  /// Return true if this attribute has an authored default value, authored
359  /// time samples or a fallback value provided by a registered schema. If
360  /// the attribute has been \ref Usd_AttributeBlocking "blocked", then
361  /// return `true` if and only if it has a fallback value.
362  USD_API
363  bool HasValue() const;
364 
365  /// \deprecated This method is deprecated because it returns `true` even when
366  /// an attribute is blocked. Please use HasAuthoredValue() instead. If
367  /// you truly need to know whether the attribute has **any** authored
368  /// value opinions, *including blocks*, you can make the following query:
369  /// `attr.GetResolveInfo().HasAuthoredValueOpinion()`
370  ///
371  /// Return true if this attribute has either an authored default value or
372  /// authored time samples.
373  USD_API
374  bool HasAuthoredValueOpinion() const;
375 
376  /// Return true if this attribute has either an authored default value or
377  /// authored time samples. If the attribute has been
378  /// \ref Usd_AttributeBlocking "blocked", then return `false`
379  USD_API
380  bool HasAuthoredValue() const;
381 
382  /// Return true if this attribute has a fallback value provided by
383  /// a registered schema.
384  USD_API
385  bool HasFallbackValue() const;
386 
387  /// Return true if it is possible, but not certain, that this attribute's
388  /// value changes over time, false otherwise.
389  ///
390  /// If this function returns false, it is certain that this attribute's
391  /// value remains constant over time.
392  ///
393  /// This function is equivalent to checking if GetNumTimeSamples() > 1,
394  /// but may be more efficient since it does not actually need to get a
395  /// full count of all time samples.
396  USD_API
397  bool ValueMightBeTimeVarying() const;
398 
399  /// Perform value resolution to fetch the value of this attribute at the
400  /// requested UsdTimeCode \p time, which defaults to \em default.
401  ///
402  /// If no value is authored at \p time but values are authored at other
403  /// times, this function will return an interpolated value based on the
404  /// stage's interpolation type.
405  /// See \ref Usd_AttributeInterpolation.
406  ///
407  /// If no value is authored and no fallback value is provided by the
408  /// schema for this attribute, this function will return false. If the
409  /// consumer's use-case requires a default value, the consumer will need
410  /// to provide one, possibly using GetTypeName().GetDefaultValue().
411  ///
412  /// This templated accessor is designed for high performance data-streaming
413  /// applications, allowing one to fetch data into the same container
414  /// repeatedly, avoiding memory allocations when possible (VtArray
415  /// containers will be resized as necessary to conform to the size of
416  /// data being read).
417  ///
418  /// This template is only instantiated for the valid scene description
419  /// value types and their corresponding VtArray containers. See
420  /// \ref Usd_Page_Datatypes for the complete list of types.
421  ///
422  /// Values are retrieved without regard to this attribute's variability.
423  /// For example, a uniform attribute may retrieve time sample values
424  /// if any are authored. However, the USD_VALIDATE_VARIABILITY TF_DEBUG
425  /// code will cause debug information to be output if values that are
426  /// inconsistent with this attribute's variability are retrieved.
427  /// See UsdAttribute::GetVariability for more details.
428  ///
429  /// \return true if there was a value to be read, it was of the type T
430  /// requested, and we read it successfully - false otherwise.
431  ///
432  /// For more details, see \ref Usd_ValueResolution , and also
433  /// \ref Usd_AssetPathValuedAttributes for information on how to
434  /// retrieve resolved asset paths from SdfAssetPath-valued attributes.
435  template <typename T>
437  static_assert(!std::is_const<T>::value, "");
438  static_assert(SdfValueTypeTraits<T>::IsValueType, "");
439  return _Get(value, time);
440  }
441  /// \overload
442  /// Type-erased access, often not as efficient as typed access.
443  USD_API
444  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
445 
446  /// Perform value resolution to determine the source of the resolved
447  /// value of this attribute at the requested UsdTimeCode \p time.
448  USD_API
451 
452  /// Perform value resolution to determine the source of the resolved
453  /// value of this attribute at any non-default time.
454  ///
455  /// Often (i.e. unless the attribute is affected by
456  /// \ref Usd_Page_ValueClips "Value Clips") the source of the resolved value
457  /// does not vary over time. See UsdAttributeQuery as an example that takes
458  /// advantage of this quality of value resolution.
459  USD_API
461  GetResolveInfo() const;
462 
463  /// Set the value of this attribute in the current UsdEditTarget to
464  /// \p value at UsdTimeCode \p time, which defaults to \em default.
465  ///
466  /// Values are authored without regard to this attribute's variability.
467  /// For example, time sample values may be authored on a uniform
468  /// attribute. However, the USD_VALIDATE_VARIABILITY TF_DEBUG code
469  /// will cause debug information to be output if values that are
470  /// inconsistent with this attribute's variability are authored.
471  /// See UsdAttribute::GetVariability for more details.
472  ///
473  /// \return false and generate an error if type \c T does not match
474  /// this attribute's defined scene description type <b>exactly</b>,
475  /// or if there is no existing definition for the attribute.
476  template <typename T>
477  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
478  static_assert(!std::is_pointer<T>::value, "");
479  static_assert(SdfValueTypeTraits<T>::IsValueType ||
481  return _Set(value, time);
482  }
483 
484  /// \overload
485  /// As a convenience, we allow the setting of string value typed attributes
486  /// via a C string value.
487  USD_API
488  bool Set(const char* value, UsdTimeCode time = UsdTimeCode::Default()) const;
489 
490  /// \overload
491  USD_API
492  bool Set(const VtValue& value, UsdTimeCode time = UsdTimeCode::Default()) const;
493 
494  /// Clears the authored default value and all time samples for this
495  /// attribute at the current EditTarget and returns true on success.
496  ///
497  /// Calling clear when either no value is authored or no spec is present,
498  /// is a silent no-op returning true.
499  ///
500  /// This method does not affect any other data authored on this attribute.
501  USD_API
502  bool Clear() const;
503 
504  /// Clear the authored value for this attribute at the given
505  /// \a time, at the current EditTarget and return true on success.
506  /// UsdTimeCode::Default() can be used to clear the default value.
507  ///
508  /// Calling clear when either no value is authored or no spec is present,
509  /// is a silent no-op returning true.
510  USD_API
511  bool ClearAtTime(UsdTimeCode time) const;
512 
513  /// Shorthand for ClearAtTime(UsdTimeCode::Default()).
514  USD_API
515  bool ClearDefault() const;
516 
517  /// Remove all time samples on an attribute and author a *block*
518  /// \c default value. This causes the attribute to resolve as
519  /// if there were no authored value opinions in weaker layers.
520  ///
521  /// See \ref Usd_AttributeBlocking for more information, including
522  /// information on time-varying blocking.
523  USD_API
524  void Block() const;
525 
526  /// @}
527 
528  /// \name Querying and Editing Connections
529  /// @{
530 
531  /// Adds \p source to the list of connections, in the position
532  /// specified by \p position.
533  ///
534  /// Issue an error if \p source identifies a prototype prim or an object
535  /// descendant to a prototype prim. It is not valid to author connections
536  /// to these objects.
537  ///
538  /// What data this actually authors depends on what data is currently
539  /// authored in the authoring layer, with respect to list-editing
540  /// semantics, which we will document soon
541  USD_API
542  bool AddConnection(const SdfPath& source,
544 
545  /// Removes \p target from the list of targets.
546  ///
547  /// Issue an error if \p source identifies a prototype prim or an object
548  /// descendant to a prototype prim. It is not valid to author connections
549  /// to these objects.
550  USD_API
551  bool RemoveConnection(const SdfPath& source) const;
552 
553  /// Make the authoring layer's opinion of the connection list explicit,
554  /// and set exactly to \p sources.
555  ///
556  /// Issue an error if \p source identifies a prototype prim or an object
557  /// descendant to a prototype prim. It is not valid to author connections
558  /// to these objects.
559  ///
560  /// If any path in \p sources is invalid, issue an error and return false.
561  USD_API
562  bool SetConnections(const SdfPathVector& sources) const;
563 
564  /// Remove all opinions about the connections list from the current edit
565  /// target.
566  USD_API
567  bool ClearConnections() const;
568 
569  /// Compose this attribute's connections and fill \p sources with the
570  /// result. All preexisting elements in \p sources are lost.
571  ///
572  /// Returns true if any connection path opinions have been authored and no
573  /// composition errors were encountered, returns false otherwise.
574  /// Note that authored opinions may include opinions that clear the
575  /// connections and a return value of true does not necessarily indicate
576  /// that \p sources will contain any connection paths.
577  ///
578  /// See \ref Usd_ScenegraphInstancing_TargetsAndConnections for details on
579  /// behavior when targets point to objects beneath instance prims.
580  ///
581  /// The result is not cached, and thus recomputed on each query.
582  USD_API
583  bool GetConnections(SdfPathVector* sources) const;
584 
585  /// Return true if this attribute has any authored opinions regarding
586  /// connections. Note that this includes opinions that remove connections,
587  /// so a true return does not necessarily indicate that this attribute has
588  /// connections.
589  USD_API
590  bool HasAuthoredConnections() const;
591 
592  /// @}
593 
594  // ---------------------------------------------------------------------- //
595  /// \anchor Usd_AttributeColorSpaceAPI
596  /// \name ColorSpace API
597  ///
598  /// The color space in which a given color or texture valued attribute is
599  /// authored is set as token-valued metadata 'colorSpace' on the attribute.
600  /// For color or texture attributes that don't have an authored 'colorSpace'
601  /// value, the fallback color-space is gleaned from whatever color
602  /// management system is specified by UsdStage::GetColorManagementSystem().
603  ///
604  /// @{
605  // ---------------------------------------------------------------------- //
606 
607  /// Gets the color space in which the attribute is authored.
608  /// \sa SetColorSpace()
609  /// \ref Usd_ColorConfigurationAPI "UsdStage Color Configuration API"
610  USD_API
611  TfToken GetColorSpace() const;
612 
613  /// Sets the color space of the attribute to \p colorSpace.
614  /// \sa GetColorSpace()
615  /// \ref Usd_ColorConfigurationAPI "UsdStage Color Configuration API"
616  USD_API
617  void SetColorSpace(const TfToken &colorSpace) const;
618 
619  /// Returns whether color-space is authored on the attribute.
620  /// \sa GetColorSpace()
621  USD_API
622  bool HasColorSpace() const;
623 
624  /// Clears authored color-space value on the attribute.
625  /// \sa SetColorSpace()
626  USD_API
627  bool ClearColorSpace() const;
628 
629  /// @}
630 
631  // ---------------------------------------------------------------------- //
632  // Private Methods and Members
633  // ---------------------------------------------------------------------- //
634 private:
635  friend class UsdAttributeQuery;
636  friend class UsdObject;
637  friend class UsdPrim;
638  friend class UsdSchemaBase;
639  friend class Usd_PrimData;
641 
642  UsdAttribute(const Usd_PrimDataHandle &prim,
643  const SdfPath &proxyPrimPath,
644  const TfToken &attrName)
645  : UsdProperty(UsdTypeAttribute, prim, proxyPrimPath, attrName) {}
646 
647  UsdAttribute(UsdObjType objType,
648  const Usd_PrimDataHandle &prim,
649  const SdfPath &proxyPrimPath,
650  const TfToken &propName)
651  : UsdProperty(objType, prim, proxyPrimPath, propName) {}
652 
653  SdfAttributeSpecHandle
654  _CreateSpec(const SdfValueTypeName &typeName, bool custom,
655  const SdfVariability &variability) const;
656 
657  // Like _CreateSpec(), but fail if this attribute is not built-in and there
658  // isn't already existing scene description to go on rather than stamping
659  // new information.
660  SdfAttributeSpecHandle _CreateSpec() const;
661 
662  bool _Create(const SdfValueTypeName &typeName, bool custom,
663  const SdfVariability &variability) const;
664 
665  template <typename T>
666  bool _Get(T* value, UsdTimeCode time) const;
667 
668  template <typename T>
669  bool _Set(const T& value, UsdTimeCode time) const;
670 
671  SdfPath
672  _GetPathForAuthoring(const SdfPath &path, std::string* whyNot) const;
673 };
674 
676 
677 #endif // PXR_USD_USD_ATTRIBUTE_H
USD_API TfToken GetRoleName() const
Return the roleName for this attribute's typeName.
USD_API bool ClearColorSpace() const
std::string upper(string_view a)
Return an all-upper case version of a (locale-independent).
Definition: strutil.h:402
USD_API bool ClearConnections() const
USD_API bool GetConnections(SdfPathVector *sources) const
UsdObjType
Definition: object.h:51
USD_API bool GetBracketingTimeSamples(double desiredTime, double *lower, double *upper, bool *hasTimeSamples) const
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
#define USD_API
Definition: api.h:40
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:436
USD_API bool SetConnections(const SdfPathVector &sources) const
USD_API bool HasAuthoredValueOpinion() const
GT_API const UT_StringHolder time
USD_API void Block() const
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLfloat * value
Definition: glcorearb.h:824
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USD_API bool SetVariability(SdfVariability variability) const
USD_API SdfValueTypeName GetTypeName() const
Return the "scene description" value type name for this attribute.
USD_API bool HasFallbackValue() const
USD_API bool ClearAtTime(UsdTimeCode time) const
USD_API bool HasAuthoredValue() const
USD_API UsdResolveInfo GetResolveInfo() const
static USD_API bool GetUnionedTimeSamples(const std::vector< UsdAttribute > &attrs, std::vector< double > *times)
UsdAttribute()
Construct an invalid attribute.
Definition: attribute.h:179
GLsizei GLenum * sources
Definition: glcorearb.h:2542
Definition: token.h:87
friend struct UsdPrim_AttrConnectionFinder
Definition: attribute.h:640
USD_API bool AddConnection(const SdfPath &source, UsdListPosition position=UsdListPositionBackOfPrependList) const
USD_API bool HasValue() const
USD_API bool GetTimeSamples(std::vector< double > *times) const
GLsizei GLsizei GLchar * source
Definition: glcorearb.h:803
USD_API size_t GetNumTimeSamples() const
std::vector< UsdAttribute > UsdAttributeVector
A std::vector of UsdAttributes.
Definition: attribute.h:46
USD_API void SetColorSpace(const TfToken &colorSpace) const
Definition: prim.h:133
USD_API bool HasAuthoredConnections() const
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:477
Definition: path.h:290
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
USD_API bool ClearDefault() const
Shorthand for ClearAtTime(UsdTimeCode::Default()).
SdfVariability
Definition: types.h:173
USD_API bool Clear() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
std::string lower(string_view a)
Return an all-upper case version of a (locale-independent).
Definition: strutil.h:395
SIM_API const UT_StringHolder position
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
USD_API TfToken GetColorSpace() const
Definition: core.h:1131
static USD_API bool GetUnionedTimeSamplesInInterval(const std::vector< UsdAttribute > &attrs, const GfInterval &interval, std::vector< double > *times)
USD_API bool SetTypeName(const SdfValueTypeName &typeName) const
UsdListPosition
Definition: common.h:88
USD_API bool RemoveConnection(const SdfPath &source) const
USD_API bool ValueMightBeTimeVarying() const
Definition: value.h:164
USD_API SdfVariability GetVariability() const
USD_API bool HasColorSpace() const