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  /// Return this property's name with all namespace prefixes removed,
90  /// i.e. the last component of the return value of GetName()
91  ///
92  /// This is generally the property's "client name"; property namespaces are
93  /// often used to group related properties together. The namespace prefixes
94  /// the property name but many consumers will care only about un-namespaced
95  /// name, i.e. its BaseName. For more information, see \ref Usd_Ordering
96  USD_API
97  TfToken GetBaseName() const;
98 
99  /// Return this property's complete namespace prefix. Return the empty
100  /// token if this property has no namespaces.
101  ///
102  /// This is the complement of GetBaseName(), although it does \em not
103  /// contain a trailing namespace delimiter
104  USD_API
105  TfToken GetNamespace() const;
106 
107  /// Return this property's name elements including namespaces and its base
108  /// name as the final element.
109  USD_API
110  std::vector<std::string> SplitName() const;
111 
112  /// @}
113  /// \name Core Metadata
114  /// @{
115 
116  /// Return this property's display group (metadata). This returns the
117  /// empty token if no display group has been set.
118  /// \sa SetDisplayGroup()
119  USD_API
121 
122  /// Sets this property's display group (metadata). Returns true on success.
123  ///
124  /// DisplayGroup provides UI hinting for grouping related properties
125  /// together for display. We define a convention for specifying nesting
126  /// of groups by recognizing the property namespace separator in
127  /// displayGroup as denoting group-nesting.
128  /// \sa SetNestedDisplayGroups()
129  USD_API
130  bool SetDisplayGroup(const std::string& displayGroup) const;
131 
132  /// Clears this property's display group (metadata) in
133  /// the current EditTarget (only). Returns true on success.
134  USD_API
135  bool ClearDisplayGroup() const;
136 
137  /// Returns true if displayGroup was explicitly authored and GetMetadata()
138  /// will return a meaningful value for displayGroup.
139  USD_API
140  bool HasAuthoredDisplayGroup() const;
141 
142  /// Return this property's displayGroup as a sequence of groups to be
143  /// nested, or an empty vector if displayGroup is empty or not authored.
144  USD_API
145  std::vector<std::string> GetNestedDisplayGroups() const;
146 
147  /// Sets this property's display group (metadata) to the nested sequence.
148  /// Returns true on success.
149  ///
150  /// A displayGroup set with this method can still be retrieved with
151  /// GetDisplayGroup(), with the namespace separator embedded in the result.
152  /// If \p nestedGroups is empty, we author an empty string for displayGroup.
153  /// \sa SetDisplayGroup()
154  USD_API
156  const std::vector<std::string>& nestedGroups) const;
157 
158  /// Return this property's display name (metadata). This returns the
159  /// empty string if no display name has been set.
160  /// \sa SetDisplayName()
161  USD_API
162  std::string GetDisplayName() const;
163 
164  /// Sets this property's display name (metadata). Returns true on success.
165  ///
166  /// DisplayName is meant to be a descriptive label, not necessarily an
167  /// alternate identifier; therefore there is no restriction on which
168  /// characters can appear in it.
169  USD_API
170  bool SetDisplayName(const std::string& name) const;
171 
172  /// Clears this property's display name (metadata) in the current EditTarget
173  /// (only). Returns true on success.
174  USD_API
175  bool ClearDisplayName() const;
176 
177  /// Returns true if displayName was explicitly authored and GetMetadata()
178  /// will return a meaningful value for displayName.
179  USD_API
180  bool HasAuthoredDisplayName() const;
181 
182  /// Return true if this is a custom property (i.e., not part of a
183  /// prim schema).
184  ///
185  /// The 'custom' modifier in USD serves the same function as Alembic's
186  /// 'userProperties', which is to say as a categorization for ad hoc
187  /// client data not formalized into any schema, and therefore not
188  /// carrying an expectation of specific processing by consuming applications.
189  USD_API
190  bool IsCustom() const;
191 
192  /// Set the value for custom at the current EditTarget, return true on
193  /// success, false if the value can not be written.
194  ///
195  /// \b Note that this value should not be changed as it is typically either
196  /// automatically authored or provided by a property definition. This method
197  /// is provided primarily for fixing invalid scene description.
198  USD_API
199  bool SetCustom(bool isCustom) const;
200 
201  /// @}
202  /// \name Existence and Validity
203  /// @{
204 
205  /// Return true if this is a builtin property or if the strongest
206  /// authored SdfPropertySpec for this property's path matches this
207  /// property's dynamic type. That is, SdfRelationshipSpec in case this is a
208  /// UsdRelationship, and SdfAttributeSpec in case this is a UsdAttribute.
209  /// Return \c false if this property's prim has expired.
210  ///
211  /// For attributes, a \c true return does not imply that this attribute
212  /// possesses a value, only that has been declared, is of a certain type and
213  /// variability, and that it is safe to use to query and author values and
214  /// metadata.
215  USD_API
216  bool IsDefined() const;
217 
218  /// Return true if there are any authored opinions for this property
219  /// in any layer that contributes to this stage, false otherwise.
220  USD_API
221  bool IsAuthored() const;
222 
223  /// Return true if there is an SdfPropertySpec authored for this
224  /// property at the given \a editTarget, otherwise return false. Note
225  /// that this method does not do partial composition. It does not consider
226  /// whether authored scene description exists at \a editTarget or weaker,
227  /// only <b>exactly at</b> the given \a editTarget.
228  USD_API
229  bool IsAuthoredAt(const class UsdEditTarget &editTarget) const;
230 
231  /// @}
232 
233  // --------------------------------------------------------------------- //
234  /// \name Flattening
235  // --------------------------------------------------------------------- //
236 
237  /// Flattens this property to a property spec with the same name
238  /// beneath the given \p parent prim in the edit target of its owning stage.
239  ///
240  /// The \p parent prim may belong to a different stage than this property's
241  /// owning stage.
242  ///
243  /// Flattening authors all authored resolved values and metadata for
244  /// this property into the destination property spec. If this property
245  /// is a builtin property, fallback values and metadata will also be
246  /// authored if the destination property has a different fallback
247  /// value or no fallback value, or if the destination property has an
248  /// authored value that overrides its fallback.
249  ///
250  /// Attribute connections and relationship targets that target an
251  /// object beneath this property's owning prim will be remapped to
252  /// target objects beneath the destination \p parent prim.
253  ///
254  /// If the destination spec already exists, it will be overwritten.
255  ///
256  /// \sa UsdStage::Flatten
257  USD_API
258  UsdProperty FlattenTo(const UsdPrim &parent) const;
259 
260  /// \overload
261  /// Flattens this property to a property spec with the given
262  /// \p propName beneath the given \p parent prim in the edit target of its
263  /// owning stage.
264  ///
265  /// The \p parent prim may belong to a different stage than this property's
266  /// owning stage.
267  USD_API
268  UsdProperty FlattenTo(const UsdPrim &parent,
269  const TfToken &propName) const;
270 
271  /// \overload
272  /// Flattens this property to a property spec for the given
273  /// \p property in the edit target of its owning prim's stage.
274  ///
275  /// The \p property owning prim may belong to a different stage than this
276  /// property's owning stage.
277  USD_API
279 
280 protected:
281  template <class Derived>
283 
284  // Gets the targets of the given spec type. Returns true if an authored
285  // opinion is found and no composition errors occured. If foundErrors is
286  // provided, it will be set to true only if errors are encountered.
287  bool _GetTargets(SdfSpecType specType, SdfPathVector *out,
288  bool *foundErrors = nullptr) const;
289 
290 private:
291  friend class UsdAttribute;
292  friend class UsdObject;
293  friend class UsdPrim;
294  friend class UsdRelationship;
295  friend class Usd_PrimData;
296 
297  UsdProperty(UsdObjType objType,
298  const Usd_PrimDataHandle &prim,
299  const SdfPath &proxyPrimPath,
300  const TfToken &propName)
301  : UsdObject(objType, prim, proxyPrimPath, propName) {}
302 
303 };
304 
305 
307 
308 #endif // PXR_USD_USD_PROPERTY_H
USD_API bool IsDefined() const
UsdObjType
Definition: object.h:49
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
#define USD_API
Definition: api.h:40
USD_API TfToken GetBaseName() const
UsdProperty(_Null< Derived >)
Definition: property.h:282
USD_API std::string GetDisplayName() const
GT_API const UT_StringHolder time
USD_API bool ClearDisplayGroup() const
GLuint const GLchar * name
Definition: glcorearb.h:785
USD_API std::vector< std::string > GetNestedDisplayGroups() 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
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
INT property
Definition: wglew.h:145
USD_API bool IsAuthoredAt(const class UsdEditTarget &editTarget) const
Definition: prim.h:132
USD_API TfToken GetNamespace() const
Definition: path.h:288
USD_API bool SetDisplayName(const std::string &name) const
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
USD_API bool HasAuthoredDisplayName() const
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:1375
USD_API bool ClearDisplayName() const
USD_API bool SetCustom(bool isCustom) const
SdfSpecType
Definition: types.h:91
#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