HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
property.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_PROPERTY_H
25 #define PXR_USD_USD_PROPERTY_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/object.h"
31 #include "pxr/usd/usd/prim.h"
32 
33 #include "pxr/usd/sdf/path.h"
35 #include "pxr/base/vt/value.h"
36 
38 
39 
40 class UsdProperty;
41 
42 /// \class UsdProperty
43 ///
44 /// Base class for UsdAttribute and UsdRelationship scenegraph objects.
45 ///
46 /// UsdProperty has a bool conversion operator that validates that the property
47 /// IsDefined() and thus valid for querying and authoring values and metadata.
48 /// This is a fairly expensive query that we do <b>not</b> cache, so if client
49 /// code retains UsdProperty objects it should manage its object validity
50 /// closely for performance. An ideal pattern is to listen for
51 /// UsdNotice::StageContentsChanged notifications, and revalidate/refetch
52 /// retained UsdObjects only then and otherwise use them without validity
53 /// checking.
54 ///
55 class UsdProperty : public UsdObject {
56 public:
57  /// Construct an invalid property.
59 
60  // --------------------------------------------------------------------- //
61  /// \name Object and Namespace Accessors
62  // --------------------------------------------------------------------- //
63 
64  /// @{
65 
66  /// Returns a strength-ordered list of property specs that provide
67  /// opinions for this property.
68  ///
69  /// If \p time is UsdTimeCode::Default(), *or* this property
70  /// is a UsdRelationship (which are never affected by clips), we will
71  /// not consider value clips for opinions. For any other \p time, for
72  /// a UsdAttribute, clips whose samples may contribute an opinion will
73  /// be included. These specs are ordered from strongest to weakest opinion,
74  /// although if \p time requires interpolation between two adjacent clips,
75  /// both clips will appear, sequentially.
76  ///
77  /// \note The results returned by this method are meant for debugging
78  /// and diagnostic purposes. It is **not** advisable to retain a
79  /// PropertyStack for the purposes of expedited value resolution for
80  /// properties, since the makeup of an attribute's PropertyStack may
81  /// itself be time-varying. To expedite repeated value resolution of
82  /// attributes, you should instead retain a \c UsdAttributeQuery .
83  ///
84  /// \sa UsdClipsAPI
85  USD_API
86  SdfPropertySpecHandleVector GetPropertyStack(
88 
89  /// Returns a strength-ordered list of property specs that provide
90  /// opinions for this property paired with the cumulative layer offset from
91  /// the stage's root layer to the layer containing the property spec.
92  ///
93  /// This behaves exactly the same as UsdProperty::GetPropertyStack with the
94  /// addition of providing the cumulative layer offset of each spec's layer.
95  ///
96  /// \note The results returned by this method are meant for debugging
97  /// and diagnostic purposes. It is **not** advisable to retain a
98  /// PropertyStack for the purposes of expedited value resolution for
99  /// properties, since the makeup of an attribute's PropertyStack may
100  /// itself be time-varying. To expedite repeated value resolution of
101  /// attributes, you should instead retain a \c UsdAttributeQuery .
102  USD_API
103  std::vector<std::pair<SdfPropertySpecHandle, SdfLayerOffset>>
106 
107  /// Return this property's name with all namespace prefixes removed,
108  /// i.e. the last component of the return value of GetName()
109  ///
110  /// This is generally the property's "client name"; property namespaces are
111  /// often used to group related properties together. The namespace prefixes
112  /// the property name but many consumers will care only about un-namespaced
113  /// name, i.e. its BaseName. For more information, see \ref Usd_Ordering
114  USD_API
115  TfToken GetBaseName() const;
116 
117  /// Return this property's complete namespace prefix. Return the empty
118  /// token if this property has no namespaces.
119  ///
120  /// This is the complement of GetBaseName(), although it does \em not
121  /// contain a trailing namespace delimiter
122  USD_API
123  TfToken GetNamespace() const;
124 
125  /// Return this property's name elements including namespaces and its base
126  /// name as the final element.
127  USD_API
128  std::vector<std::string> SplitName() const;
129 
130  /// @}
131  /// \name Core Metadata
132  /// @{
133 
134  /// Return this property's display group (metadata). This returns the
135  /// empty token if no display group has been set.
136  /// \sa SetDisplayGroup()
137  USD_API
139 
140  /// Sets this property's display group (metadata). Returns true on success.
141  ///
142  /// DisplayGroup provides UI hinting for grouping related properties
143  /// together for display. We define a convention for specifying nesting
144  /// of groups by recognizing the property namespace separator in
145  /// displayGroup as denoting group-nesting.
146  /// \sa SetNestedDisplayGroups()
147  USD_API
148  bool SetDisplayGroup(const std::string& displayGroup) const;
149 
150  /// Clears this property's display group (metadata) in
151  /// the current EditTarget (only). Returns true on success.
152  USD_API
153  bool ClearDisplayGroup() const;
154 
155  /// Returns true if displayGroup was explicitly authored and GetMetadata()
156  /// will return a meaningful value for displayGroup.
157  USD_API
158  bool HasAuthoredDisplayGroup() const;
159 
160  /// Return this property's displayGroup as a sequence of groups to be
161  /// nested, or an empty vector if displayGroup is empty or not authored.
162  USD_API
163  std::vector<std::string> GetNestedDisplayGroups() const;
164 
165  /// Sets this property's display group (metadata) to the nested sequence.
166  /// Returns true on success.
167  ///
168  /// A displayGroup set with this method can still be retrieved with
169  /// GetDisplayGroup(), with the namespace separator embedded in the result.
170  /// If \p nestedGroups is empty, we author an empty string for displayGroup.
171  /// \sa SetDisplayGroup()
172  USD_API
174  const std::vector<std::string>& nestedGroups) const;
175 
176  /// Return true if this is a custom property (i.e., not part of a
177  /// prim schema).
178  ///
179  /// The 'custom' modifier in USD serves the same function as Alembic's
180  /// 'userProperties', which is to say as a categorization for ad hoc
181  /// client data not formalized into any schema, and therefore not
182  /// carrying an expectation of specific processing by consuming applications.
183  USD_API
184  bool IsCustom() const;
185 
186  /// Set the value for custom at the current EditTarget, return true on
187  /// success, false if the value can not be written.
188  ///
189  /// \b Note that this value should not be changed as it is typically either
190  /// automatically authored or provided by a property definition. This method
191  /// is provided primarily for fixing invalid scene description.
192  USD_API
193  bool SetCustom(bool isCustom) const;
194 
195  /// @}
196  /// \name Existence and Validity
197  /// @{
198 
199  /// Return true if this is a builtin property or if the strongest
200  /// authored SdfPropertySpec for this property's path matches this
201  /// property's dynamic type. That is, SdfRelationshipSpec in case this is a
202  /// UsdRelationship, and SdfAttributeSpec in case this is a UsdAttribute.
203  /// Return \c false if this property's prim has expired.
204  ///
205  /// For attributes, a \c true return does not imply that this attribute
206  /// possesses a value, only that has been declared, is of a certain type and
207  /// variability, and that it is safe to use to query and author values and
208  /// metadata.
209  USD_API
210  bool IsDefined() const;
211 
212  /// Return true if there are any authored opinions for this property
213  /// in any layer that contributes to this stage, false otherwise.
214  USD_API
215  bool IsAuthored() const;
216 
217  /// Return true if there is an SdfPropertySpec authored for this
218  /// property at the given \a editTarget, otherwise return false. Note
219  /// that this method does not do partial composition. It does not consider
220  /// whether authored scene description exists at \a editTarget or weaker,
221  /// only <b>exactly at</b> the given \a editTarget.
222  USD_API
223  bool IsAuthoredAt(const class UsdEditTarget &editTarget) const;
224 
225  /// @}
226 
227  // --------------------------------------------------------------------- //
228  /// \name Flattening
229  // --------------------------------------------------------------------- //
230 
231  /// Flattens this property to a property spec with the same name
232  /// beneath the given \p parent prim in the edit target of its owning stage.
233  ///
234  /// The \p parent prim may belong to a different stage than this property's
235  /// owning stage.
236  ///
237  /// Flattening authors all authored resolved values and metadata for
238  /// this property into the destination property spec. If this property
239  /// is a builtin property, fallback values and metadata will also be
240  /// authored if the destination property has a different fallback
241  /// value or no fallback value, or if the destination property has an
242  /// authored value that overrides its fallback.
243  ///
244  /// Attribute connections and relationship targets that target an
245  /// object beneath this property's owning prim will be remapped to
246  /// target objects beneath the destination \p parent prim.
247  ///
248  /// If the destination spec already exists, it will be overwritten.
249  ///
250  /// \sa UsdStage::Flatten
251  USD_API
252  UsdProperty FlattenTo(const UsdPrim &parent) const;
253 
254  /// \overload
255  /// Flattens this property to a property spec with the given
256  /// \p propName beneath the given \p parent prim in the edit target of its
257  /// owning stage.
258  ///
259  /// The \p parent prim may belong to a different stage than this property's
260  /// owning stage.
261  USD_API
262  UsdProperty FlattenTo(const UsdPrim &parent,
263  const TfToken &propName) const;
264 
265  /// \overload
266  /// Flattens this property to a property spec for the given
267  /// \p property in the edit target of its owning prim's stage.
268  ///
269  /// The \p property owning prim may belong to a different stage than this
270  /// property's owning stage.
271  USD_API
272  UsdProperty FlattenTo(const UsdProperty &property) const;
273 
274 protected:
275  template <class Derived>
277 
278  // Gets the targets of the given spec type. Returns true if an authored
279  // opinion is found and no composition errors occured. If foundErrors is
280  // provided, it will be set to true only if errors are encountered.
281  bool _GetTargets(SdfSpecType specType, SdfPathVector *out,
282  bool *foundErrors = nullptr) const;
283 
284 private:
285  friend class UsdAttribute;
286  friend class UsdObject;
287  friend class UsdPrim;
288  friend class UsdRelationship;
289  friend class Usd_PrimData;
290 
291  UsdProperty(UsdObjType objType,
292  const Usd_PrimDataHandle &prim,
293  const SdfPath &proxyPrimPath,
294  const TfToken &propName)
295  : UsdObject(objType, prim, proxyPrimPath, propName) {}
296 
297 };
298 
299 
301 
302 #endif // PXR_USD_USD_PROPERTY_H
USD_API bool IsDefined() const
UsdObjType
Definition: object.h:51
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
#define USD_API
Definition: api.h:40
USD_API TfToken GetBaseName() const
UsdProperty(_Null< Derived >)
Definition: property.h:276
GT_API const UT_StringHolder time
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USD_API bool ClearDisplayGroup() const
USD_API std::vector< std::string > GetNestedDisplayGroups() const
USD_API std::vector< std::pair< SdfPropertySpecHandle, SdfLayerOffset > > GetPropertyStackWithLayerOffsets(UsdTimeCode time=UsdTimeCode::Default()) const
bool _GetTargets(SdfSpecType specType, SdfPathVector *out, bool *foundErrors=nullptr) const
Definition: token.h:87
USD_API std::vector< std::string > SplitName() const
USD_API UsdProperty FlattenTo(const UsdPrim &parent) const
UsdProperty()
Construct an invalid property.
Definition: property.h:58
USD_API bool IsAuthoredAt(const class UsdEditTarget &editTarget) const
Definition: prim.h:133
USD_API TfToken GetNamespace() const
Definition: path.h:290
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
USD_API bool SetDisplayGroup(const std::string &displayGroup) const
USD_API SdfPropertySpecHandleVector GetPropertyStack(UsdTimeCode time=UsdTimeCode::Default()) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USD_API bool SetCustom(bool isCustom) const
SdfSpecType
Definition: types.h:85
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API std::string GetDisplayGroup() const
USD_API bool IsCustom() const
USD_API bool SetNestedDisplayGroups(const std::vector< std::string > &nestedGroups) const
USD_API bool IsAuthored() const
USD_API bool HasAuthoredDisplayGroup() const