HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
propertySpec.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_SDF_PROPERTY_SPEC_H
25 #define PXR_USD_SDF_PROPERTY_SPEC_H
26 
27 /// \file sdf/propertySpec.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
32 #include "pxr/usd/sdf/spec.h"
34 #include "pxr/usd/sdf/proxyTypes.h"
35 #include "pxr/usd/sdf/types.h"
36 
37 #include "pxr/base/vt/value.h"
38 
40 #include "pxr/base/tf/token.h"
41 
42 #include <iosfwd>
43 #include <string>
44 
46 
47 /// \class SdfPropertySpec
48 ///
49 /// Base class for SdfAttributeSpec and SdfRelationshipSpec.
50 ///
51 /// Scene Spec Attributes (SdfAttributeSpec) and Relationships
52 /// (SdfRelationshipSpec) are the basic properties that make up Scene Spec Prims
53 /// (SdfPrimSpec). They share many qualities and can sometimes be treated
54 /// uniformly. The common qualities are provided by this base class.
55 ///
56 /// NOTE: Do not use Python reserved words and keywords as attribute names.
57 /// This will cause attribute resolution to fail.
58 ///
59 class SdfPropertySpec : public SdfSpec
60 {
61  SDF_DECLARE_ABSTRACT_SPEC(SdfPropertySpec, SdfSpec);
62 
63 public:
64  ///
65  /// \name Name
66  /// @{
67 
68  /// Returns the property's name.
69  SDF_API
70  const std::string &GetName() const;
71 
72  /// Returns the property's name, as a token.
73  SDF_API
74  TfToken GetNameToken() const;
75 
76  /// Returns true if setting the property spec's name to \p newName
77  /// will succeed.
78  ///
79  /// Returns false if it won't, and sets \p whyNot with a string
80  /// describing why not.
81  SDF_API
82  bool CanSetName(const std::string &newName, std::string *whyNot) const;
83 
84  /// Sets the property's name.
85  ///
86  /// A Prim's properties must be unique by name. Setting the
87  /// name to the same name as an existing property is an error.
88  ///
89  /// Setting \p validate to false, will skip validation of the newName
90  /// (that is, CanSetName will not be called).
91  SDF_API
92  bool SetName(const std::string &newName, bool validate = true);
93 
94  /// Returns true if the given name is considered a valid name for a
95  /// property. A valid name is not empty, and does not use invalid
96  /// characters (such as '/', '[', or '.').
97  SDF_API
98  static bool IsValidName(const std::string &name);
99 
100  /// @}
101  /// \name Ownership
102  /// @{
103 
104  /// Returns the owner prim or relationship of this property.
105  SDF_API
106  SdfSpecHandle GetOwner() const;
107 
108  /// @}
109  /// \name Metadata
110  /// @{
111 
112  /// Returns the property's custom data.
113  ///
114  /// The default value for custom data is an empty dictionary.
115  ///
116  /// Custom data is for use by plugins or other non-tools supplied
117  /// extensions that need to be able to store data attached to arbitrary
118  /// scene objects. Note that if the only objects you want to store data
119  /// on are prims, using custom attributes is probably a better choice.
120  /// But if you need to possibly store this data on attributes or
121  /// relationships or as annotations on reference arcs, then custom data
122  /// is an appropriate choice.
123  SDF_API
125 
126  /// Returns the asset info dictionary for this property.
127  ///
128  /// The default value is an empty dictionary.
129  ///
130  /// The asset info dictionary is used to annotate SdfAssetPath-valued
131  /// attributes pointing to the root-prims of assets (generally organized
132  /// as models) with various data related to asset management. For example,
133  /// asset name, root layer identifier, asset version etc.
134  ///
135  /// \note It is only valid to author assetInfo on attributes that are of
136  /// type SdfAssetPath.
137  ///
138  SDF_API
140 
141  /// Sets a property custom data entry.
142  ///
143  /// If \p value is empty, then this removes the given custom data entry.
144  SDF_API
145  void SetCustomData(const std::string &name, const VtValue &value);
146 
147  /// Sets a asset info entry for this property.
148  ///
149  /// If \p value is empty, then this removes the given asset info entry.
150  ///
151  /// \sa GetAssetInfo()
152  ///
153  SDF_API
154  void SetAssetInfo(const std::string& name, const VtValue& value);
155 
156  /// Returns the displayGroup string for this property spec.
157  ///
158  /// The default value for displayGroup is empty string.
159  SDF_API
161 
162  /// Sets the displayGroup string for this property spec.
163  SDF_API
164  void SetDisplayGroup(const std::string &value);
165 
166  /// Returns the displayName string for this property spec.
167  ///
168  /// The default value for displayName is empty string.
169  SDF_API
170  std::string GetDisplayName() const;
171 
172  /// Sets the displayName string for this property spec.
173  SDF_API
174  void SetDisplayName(const std::string &value);
175 
176  /// Returns the documentation string for this property spec.
177  ///
178  /// The default value for documentation is empty string.
179  SDF_API
181 
182  /// Sets the documentation string for this property spec.
183  SDF_API
184  void SetDocumentation(const std::string &value);
185 
186  /// Returns whether this property spec will be hidden in browsers.
187  ///
188  /// The default value for hidden is false.
189  SDF_API
190  bool GetHidden() const;
191 
192  /// Sets whether this property spec will be hidden in browsers.
193  SDF_API
194  void SetHidden(bool value);
195 
196  /// Returns the property's permission restriction.
197  ///
198  /// The default value for permission is SdfPermissionPublic.
199  SDF_API
201 
202  /// Sets the property's permission restriction.
203  SDF_API
204  void SetPermission(SdfPermission value);
205 
206  /// Returns the prefix string for this property spec.
207  ///
208  /// The default value for prefix is "".
209  SDF_API
210  std::string GetPrefix() const;
211 
212  /// Sets the prefix string for this property spec.
213  SDF_API
214  void SetPrefix(const std::string &value);
215 
216  /// Returns the suffix string for this property spec.
217  ///
218  /// The default value for suffix is "".
219  SDF_API
220  std::string GetSuffix() const;
221 
222  /// Sets the suffix string for this property spec.
223  SDF_API
224  void SetSuffix(const std::string &value);
225 
226  /// Returns the property's symmetric peer.
227  ///
228  /// The default value for the symmetric peer is an empty string.
229  SDF_API
231 
232  /// Sets the property's symmetric peer.
233  ///
234  /// If \p peerName is empty, then this removes any symmetric peer for the
235  /// given property.
236  SDF_API
237  void SetSymmetricPeer(const std::string &peerName);
238 
239  /// Returns the property's symmetry arguments.
240  ///
241  /// The default value for symmetry arguments is an empty dictionary.
242  SDF_API
244 
245  /// Sets a property symmetry argument.
246  ///
247  /// If \p value is empty, then this removes the argument with the given
248  /// \p name.
249  SDF_API
250  void SetSymmetryArgument(const std::string &name, const VtValue &value);
251 
252  /// Returns the property's symmetry function.
253  ///
254  /// The default value for the symmetry function is an empty token.
255  SDF_API
257 
258  /// Sets the property's symmetry function.
259  ///
260  /// If \p functionName is empty, then this removes any symmetry function
261  /// for the given property.
262  SDF_API
263  void SetSymmetryFunction(const TfToken &functionName);
264 
265  /// @}
266  /// \name Property value API
267  /// @{
268 
269  /// Returns the entire set of time samples.
270  SDF_API
272 
273  /// Returns the TfType representing the value type this property holds.
274  SDF_API
275  TfType GetValueType() const;
276 
277  /// Returns the name of the value type that this property holds.
278  ///
279  /// Returns the typename used to represent the types of value held by
280  /// this attribute.
281  SDF_API
283 
284  /// Returns the attribute's default value.
285  ///
286  /// If it doesn't have a default value, an empty VtValue is returned.
287  SDF_API
288  VtValue GetDefaultValue() const;
289 
290  /// Sets the attribute's default value.
291  ///
292  /// Returns true if successful, false otherwise. Fails if \p defaultValue
293  /// has wrong type.
294  SDF_API
295  bool SetDefaultValue(const VtValue &defaultValue);
296 
297  /// Returns true if a default value is set for this attribute.
298  SDF_API
299  bool HasDefaultValue() const;
300 
301  /// Clear the attribute's default value.
302  SDF_API
303  void ClearDefaultValue();
304 
305  /// @}
306  /// \name Spec properties
307  /// @{
308 
309  /// Returns the comment string for this property spec.
310  ///
311  /// The default value for comment is "".
312  SDF_API
313  std::string GetComment() const;
314 
315  /// Sets the comment string for this property spec.
316  SDF_API
317  void SetComment(const std::string &value);
318 
319  /// Returns true if this spec declares a custom property
320  SDF_API
321  bool IsCustom() const;
322 
323  /// Sets whether this spec declares a custom property
324  SDF_API
325  void SetCustom(bool custom);
326 
327  /// Returns the variability of the property.
328  ///
329  /// An attribute's variability may be \c Varying (the default),
330  /// \c Uniform, \c Config, or \c Computed.
331  ///
332  /// A relationship's variability may be \c Varying or \c Uniform (the
333  /// default)
334  ///
335  /// <ul>
336  /// <li>\c Varying attributes may be directly authored, animated and
337  /// affected by \p Actions. They are the most flexible.
338  /// Varying relationships can have a default and an anim spline,
339  /// in addition to a list of targets.
340  ///
341  /// <li>\c Uniform attributes may be authored only with non-animated
342  /// values (default values). They cannot be affected by \p Actions,
343  /// but they can be connected to other Uniform attributes.
344  /// Uniform relationships have a list of targets but do not have
345  /// default or anim spline values.
346  ///
347  /// <li>\c Config attributes are the same as Uniform except that a Prim
348  /// can choose to alter its collection of built-in properties based
349  /// on the values of its Config attributes.
350  ///
351  /// <li>\c Computed attributes may not be authored in scene description.
352  /// Prims determine the values of their Computed attributes through
353  /// Prim-specific computation. They may not be connected.
354  /// </ul>
355  SDF_API
357 
358  /// Returns true if this PropertySpec has no significant data other than
359  /// just what is necessary for instantiation.
360  ///
361  /// For example, "double foo" has only required fields, but "double foo = 3"
362  /// has more than just what is required.
363  ///
364  /// This is similar to IsInert except that IsInert will always return false
365  /// even for properties that have only required fields; PropertySpecs are
366  /// never considered inert because even a spec with only required fields
367  /// will cause instantiation of on-demand properties.
368  ///
369  SDF_API
370  bool HasOnlyRequiredFields() const;
371 
372 private:
373  inline TfToken _GetAttributeValueTypeName() const;
374 };
375 
377 
378 #endif // #ifndef PXR_USD_SDF_PROPERTY_SPEC_H
SDF_API void SetPermission(SdfPermission value)
Sets the property's permission restriction.
SDF_API bool GetHidden() const
SDF_API SdfDictionaryProxy GetCustomData() const
SDF_API bool HasOnlyRequiredFields() const
SDF_API void SetDisplayGroup(const std::string &value)
Sets the displayGroup string for this property spec.
SDF_API void SetDocumentation(const std::string &value)
Sets the documentation string for this property spec.
SDF_API VtValue GetDefaultValue() const
SDF_API const std::string & GetName() const
Returns the property's name.
SDF_API void SetCustom(bool custom)
Sets whether this spec declares a custom property.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
SDF_API std::string GetDisplayName() const
SDF_API void SetSymmetryFunction(const TfToken &functionName)
Definition: spec.h:49
SDF_API void SetSuffix(const std::string &value)
Sets the suffix string for this property spec.
SDF_API SdfDictionaryProxy GetSymmetryArguments() const
SDF_API bool SetDefaultValue(const VtValue &defaultValue)
SDF_API SdfSpecHandle GetOwner() const
Returns the owner prim or relationship of this property.
SDF_API void SetHidden(bool value)
Sets whether this property spec will be hidden in browsers.
SDF_API void SetComment(const std::string &value)
Sets the comment string for this property spec.
SDF_API SdfValueTypeName GetTypeName() const
SDF_API TfType GetValueType() const
Returns the TfType representing the value type this property holds.
SDF_API std::string GetPrefix() const
Definition: token.h:87
static SDF_API bool IsValidName(const std::string &name)
SDF_API void SetPrefix(const std::string &value)
Sets the prefix string for this property spec.
SDF_API SdfVariability GetVariability() const
SDF_API void SetCustomData(const std::string &name, const VtValue &value)
SDF_API SdfTimeSampleMap GetTimeSampleMap() const
Returns the entire set of time samples.
SDF_API std::string GetDisplayGroup() const
SDF_API TfToken GetNameToken() const
Returns the property's name, as a token.
SDF_API bool SetName(const std::string &newName, bool validate=true)
GLuint const GLchar * name
Definition: glcorearb.h:786
SDF_API TfToken GetSymmetryFunction() const
SDF_API SdfDictionaryProxy GetAssetInfo() const
SDF_API std::string GetComment() const
SdfVariability
Definition: types.h:173
SDF_API bool IsCustom() const
Returns true if this spec declares a custom property.
SDF_API std::string GetDocumentation() const
#define SDF_API
Definition: api.h:40
SDF_API void SetSymmetricPeer(const std::string &peerName)
SDF_API std::string GetSymmetricPeer() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
SDF_API bool CanSetName(const std::string &newName, std::string *whyNot) const
SDF_API void SetAssetInfo(const std::string &name, const VtValue &value)
SDF_API bool HasDefaultValue() const
Returns true if a default value is set for this attribute.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
SDF_API SdfPermission GetPermission() const
Definition: core.h:1131
std::map< double, VtValue > SdfTimeSampleMap
A map from sample times to sample values.
Definition: types.h:287
SDF_API std::string GetSuffix() const
SDF_API void SetDisplayName(const std::string &value)
Sets the displayName string for this property spec.
Definition: value.h:164
SDF_API void SetSymmetryArgument(const std::string &name, const VtValue &value)
SDF_API void ClearDefaultValue()
Clear the attribute's default value.
SdfPermission
Definition: types.h:149