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