HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
spec.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_SPEC_H
25 #define PXR_USD_SDF_SPEC_H
26 
27 /// \file sdf/spec.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
32 #include "pxr/usd/sdf/identity.h"
34 #include "pxr/usd/sdf/schema.h"
35 #include "pxr/usd/sdf/types.h"
36 #include "pxr/base/vt/value.h"
37 #include "pxr/base/tf/token.h"
38 #include "pxr/base/tf/type.h"
39 
40 #include <hboost/type_traits/is_base_of.hpp>
41 #include <hboost/utility/enable_if.hpp>
42 
43 #include <iosfwd>
44 
46 
47 /// \class SdfSpec
48 ///
49 /// Base class for all Sdf spec classes.
50 ///
51 class SdfSpec
52 {
53  SDF_DECLARE_BASE_SPEC(SdfSpec);
54 
55 public:
56  SDF_API
57  SdfSpec &operator=(const SdfSpec &other);
58 
59  SDF_API
60  ~SdfSpec();
61 
62  /// \name SdSpec generic API
63  ///
64  /// @{
65 
66  /// Returns the SdfSchemaBase for the layer that owns this spec.
67  SDF_API
68  const SdfSchemaBase& GetSchema() const;
69 
70  /// Returns the SdfSpecType specifying the spec type this object
71  /// represents.
72  SDF_API
73  SdfSpecType GetSpecType() const;
74 
75  /// Returns true if this object is invalid or expired.
76  SDF_API
77  bool IsDormant() const;
78 
79  /// Returns the layer that this object belongs to.
80  SDF_API
81  SdfLayerHandle GetLayer() const;
82 
83  /// Returns the scene path of this object.
84  SDF_API
85  SdfPath GetPath() const;
86 
87  /// Returns whether this object's layer can be edited.
88  SDF_API
89  bool PermissionToEdit() const;
90 
91  /// Returns the full list of info keys currently set on this object.
92  /// \note This does not include fields that represent names of children.
93  SDF_API
94  std::vector<TfToken> ListInfoKeys() const;
95 
96  /// Returns the list of metadata info keys for this object.
97  ///
98  /// This is not the complete list of keys, it is only those that
99  /// should be considered to be metadata by inspectors or other
100  /// presentation UI.
101  ///
102  /// This is interim API which is likely to change. Only editors with
103  /// an immediate specific need (like the Inspector) should use this API.
104  SDF_API
105  std::vector<TfToken> GetMetaDataInfoKeys() const;
106 
107  /// Returns this metadata key's displayGroup.
108  ///
109  SDF_API
110  TfToken GetMetaDataDisplayGroup(TfToken const &key) const;
111 
112  /// Gets the value for the given metadata key.
113  ///
114  /// This is interim API which is likely to change. Only editors with
115  /// an immediate specific need (like the Inspector) should use this API.
116  SDF_API
117  VtValue GetInfo(const TfToken &key) const;
118 
119  /// Sets the value for the given metadata key.
120  ///
121  /// It is an error to pass a value that is not the correct type for
122  /// that given key.
123  ///
124  /// This is interim API which is likely to change. Only editors with
125  /// an immediate specific need (like the Inspector) should use this API.
126  SDF_API
127  void SetInfo(const TfToken &key, const VtValue &value);
128 
129  /// Sets the value for \p entryKey to \p value within the dictionary
130  /// with the given metadata key \p dictionaryKey
131  SDF_API
132  void SetInfoDictionaryValue(const TfToken &dictionaryKey,
133  const TfToken &entryKey, const VtValue &value);
134 
135  /// Returns whether there is a setting for the scene spec info
136  /// with the given key.
137  ///
138  /// When asked for a value for one of its scene spec info, a valid value
139  /// will always be returned. But if this API returns \b false for a scene
140  /// spec info, the value of that info will be the defined default value.
141  ///
142  /// When dealing with a composedLayer, it is not necessary to worry about
143  /// whether a scene spec info "has a value" because the composed layer will
144  /// always have a valid value, even if it is the default.
145  ///
146  /// A spec may or may not have an expressed value for some of its
147  /// scene spec info.
148  ///
149  /// This is interim API which is likely to change. Only editors with
150  /// an immediate specific need (like the Inspector) should use this API.
151  SDF_API
152  bool HasInfo(const TfToken &key) const;
153 
154  /// Clears the value for scene spec info with the given \a key.
155  ///
156  /// After calling this, HasInfo() will return \b false.
157  /// To make HasInfo() return \b true just set a value for that
158  /// scene spec info.
159  ///
160  /// This is interim API which is likely to change. Only editors with
161  /// an immediate specific need (like the Inspector) should use this API.
162  SDF_API
163  void ClearInfo(const TfToken &key);
164 
165  /// Returns the data type for the info with the given \a key.
166  SDF_API
167  TfType GetTypeForInfo(const TfToken &key) const;
168 
169  /// Returns the fallback for the info with the given \a key.
170  SDF_API
171  const VtValue& GetFallbackForInfo(const TfToken &key) const;
172 
173  /// Writes this spec to the given stream.
174  SDF_API
175  bool WriteToStream(std::ostream&, size_t indent = 0) const;
176 
177  /// Returns whether this object has no significant data.
178  ///
179  /// "Significant" here means that the object contributes opinions to
180  /// a scene. If this spec has any child scenegraph objects (e.g.,
181  /// prim or property spec), it will be considered significant even if
182  /// those child objects are not.
183  /// However, if \p ignoreChildren is \c true, these child objects
184  /// will be ignored.
185  SDF_API
186  bool IsInert(bool ignoreChildren = false) const;
187 
188  /// @}
189 
190  /// \name Field-based Generic API
191  /// @{
192 
193  /// Returns all fields with values.
194  SDF_API
195  std::vector<TfToken> ListFields() const;
196 
197  /// Returns \c true if the spec has a non-empty value with field
198  /// name \p name.
199  SDF_API
200  bool HasField(const TfToken &name) const;
201 
202  /// Returns \c true if the object has a non-empty value with name
203  /// \p name and type \p T. If value ptr is provided, returns the
204  /// value found.
205  template <class T>
206  bool HasField(const TfToken &name, T* value) const
207  {
208  if (!value) {
209  return HasField(name);
210  }
211 
212  SdfAbstractDataTypedValue<T> outValue(value);
213  return _HasField(name, &outValue);
214  }
215 
216  /// Returns a field value by name.
217  SDF_API
218  VtValue GetField(const TfToken &name) const;
219 
220  /// Returns a field value by name. If the object is invalid, or the
221  /// value doesn't exist, isn't set, or isn't of the given type then
222  /// returns defaultValue.
223  template <typename T>
224  T GetFieldAs(const TfToken & name, const T& defaultValue = T()) const
225  {
226  VtValue v = GetField(name);
227  if (v.IsEmpty() || !v.IsHolding<T>())
228  return defaultValue;
229  return v.UncheckedGet<T>();
230  }
231 
232  /// Sets a field value as a boxed VtValue.
233  SDF_API
234  bool SetField(const TfToken & name, const VtValue& value);
235 
236  /// Sets a field value of type T.
237  template <typename T>
238  bool SetField(const TfToken & name, const T& value)
239  {
240  return SetField(name, VtValue(value));
241  }
242 
243  /// Clears a field.
244  SDF_API
245  bool ClearField(const TfToken & name);
246 
247  /// @}
248 
249  /// \name Comparison operators
250  /// @{
251 
252  SDF_API bool operator==(const SdfSpec& rhs) const;
253  SDF_API bool operator<(const SdfSpec& rhs) const;
254 
255  /// @}
256 
257  /// Hash.
258  friend size_t hash_value(const SdfSpec &x) {
259  return hash_value(x._id);
260  }
261 
262 private:
263  SDF_API
264  bool _HasField(const TfToken& name, SdfAbstractDataValue* value) const;
265 
266 protected:
267  bool _MoveSpec(const SdfPath &oldPath, const SdfPath &newPath) const;
268  bool _DeleteSpec(const SdfPath &path);
269 
270 private:
271  Sdf_IdentityRefPtr _id;
272 };
273 
275 
276 #endif // PXR_USD_SDF_SPEC_H
SDF_API SdfSpec & operator=(const SdfSpec &other)
bool HasField(const TfToken &name, T *value) const
Definition: spec.h:206
SDF_API VtValue GetInfo(const TfToken &key) const
SDF_API bool operator<(const SdfSpec &rhs) const
T const & UncheckedGet() const
Definition: value.h:1101
SDF_API bool HasField(const TfToken &name) const
SDF_API VtValue GetField(const TfToken &name) const
Returns a field value by name.
GLuint const GLchar * name
Definition: glew.h:1814
SDF_API void SetInfoDictionaryValue(const TfToken &dictionaryKey, const TfToken &entryKey, const VtValue &value)
SDF_API bool SetField(const TfToken &name, const VtValue &value)
Sets a field value as a boxed VtValue.
SDF_API bool operator==(const SdfSpec &rhs) const
SDF_API const VtValue & GetFallbackForInfo(const TfToken &key) const
Returns the fallback for the info with the given key.
Definition: spec.h:51
friend size_t hash_value(const SdfSpec &x)
Hash.
Definition: spec.h:258
SDF_API std::vector< TfToken > ListInfoKeys() const
SDF_API ~SdfSpec()
const GLdouble * v
Definition: glew.h:1391
bool IsEmpty() const
Returns true iff this value is empty.
Definition: value.h:1255
hboost::intrusive_ptr< Sdf_Identity > Sdf_IdentityRefPtr
SDF_API bool PermissionToEdit() const
Returns whether this object's layer can be edited.
SDF_API const SdfSchemaBase & GetSchema() const
Returns the SdfSchemaBase for the layer that owns this spec.
SDF_API SdfLayerHandle GetLayer() const
Returns the layer that this object belongs to.
T GetFieldAs(const TfToken &name, const T &defaultValue=T()) const
Definition: spec.h:224
SDF_API std::vector< TfToken > ListFields() const
Returns all fields with values.
SDF_API bool ClearField(const TfToken &name)
Clears a field.
Definition: token.h:87
SDF_API bool HasInfo(const TfToken &key) const
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
SDF_API void SetInfo(const TfToken &key, const VtValue &value)
SDF_API SdfSpecType GetSpecType() const
Definition: path.h:288
SDF_API bool IsInert(bool ignoreChildren=false) const
GLsizei const GLchar *const * path
Definition: glew.h:6461
#define SDF_API
Definition: api.h:40
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
SdfSpecType
Definition: types.h:91
SDF_API TfToken GetMetaDataDisplayGroup(TfToken const &key) const
bool IsHolding() const
Definition: value.h:1073
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
Definition: type.h:64
SDF_API SdfPath GetPath() const
Returns the scene path of this object.
bool _DeleteSpec(const SdfPath &path)
SDF_API bool WriteToStream(std::ostream &, size_t indent=0) const
Writes this spec to the given stream.
SDF_API TfType GetTypeForInfo(const TfToken &key) const
Returns the data type for the info with the given key.
SDF_API void ClearInfo(const TfToken &key)
GLsizei const GLfloat * value
Definition: glew.h:1849
bool SetField(const TfToken &name, const T &value)
Sets a field value of type T.
Definition: spec.h:238
Definition: value.h:174
bool _MoveSpec(const SdfPath &oldPath, const SdfPath &newPath) const
SDF_API std::vector< TfToken > GetMetaDataInfoKeys() const
SDF_API bool IsDormant() const
Returns true if this object is invalid or expired.