HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
layer.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_LAYER_H
25 #define PXR_USD_SDF_LAYER_H
26 
27 /// \file sdf/layer.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
31 #include "pxr/usd/sdf/data.h"
33 #include "pxr/usd/sdf/identity.h"
34 #include "pxr/usd/sdf/layerHints.h"
37 #include "pxr/usd/sdf/path.h"
38 #include "pxr/usd/sdf/proxyTypes.h"
39 #include "pxr/usd/sdf/spec.h"
40 #include "pxr/usd/sdf/types.h"
41 #include "pxr/usd/ar/ar.h"
42 #include "pxr/usd/ar/assetInfo.h"
45 #include "pxr/base/vt/value.h"
47 
48 #include <hboost/optional.hpp>
49 
50 #include <atomic>
51 #include <functional>
52 #include <memory>
53 #include <set>
54 #include <string>
55 #include <vector>
56 
58 
61 
62 struct Sdf_AssetInfo;
63 
64 /// \class SdfLayer
65 ///
66 /// A scene description container that can combine with other such containers
67 /// to form simple component assets, and successively larger aggregates. The
68 /// contents of an SdfLayer adhere to the SdfData data model. A layer can be
69 /// ephemeral, or be an asset accessed and serialized through the ArAsset and
70 /// ArResolver interfaces.
71 ///
72 /// The SdfLayer class provides a consistent API for accesing and serializing
73 /// scene description, using any data store provided by Ar plugins. Sdf
74 /// itself provides a UTF-8 text format for layers identified by the ".sdf"
75 /// identifier extension, but via the SdfFileFormat abstraction, allows
76 /// downstream modules and plugins to adapt arbitrary data formats to the
77 /// SdfData/SdfLayer model.
78 ///
79 /// The FindOrOpen() method returns a new SdfLayer object with scene
80 /// description from any supported asset format. Once read, a layer
81 /// remembers which asset it was read from. The Save() method saves the layer
82 /// back out to the original asset. You can use the Export() method to write
83 /// the layer to a different location. You can use the GetIdentifier() method
84 /// to get the layer's Id or GetRealPath() to get the resolved, full URI.
85 ///
86 /// Layers can have a timeCode range (startTimeCode and endTimeCode). This range
87 /// represents the suggested playback range, but has no impact on the extent of
88 /// the animation data that may be stored in the layer. The metadatum
89 /// "timeCodesPerSecond" is used to annotate how the time ordinate for samples
90 /// contained in the file scales to seconds. For example, if timeCodesPerSecond
91 /// is 24, then a sample at time ordinate 24 should be viewed exactly one second
92 /// after the sample at time ordinate 0.
93 ///
94 class SdfLayer
95  : public TfRefBase
96  , public TfWeakBase
97 {
98 public:
99  /// Destructor
100  SDF_API
101  virtual ~SdfLayer();
102 
103  /// Noncopyable
104  SdfLayer(const SdfLayer&) = delete;
105  SdfLayer& operator=(const SdfLayer&) = delete;
106 
107  ///
108  /// \name Primary API
109  /// @{
110 
111  /// Returns the schema this layer adheres to. This schema provides details
112  /// about the scene description that may be authored in this layer.
113  SDF_API const SdfSchemaBase& GetSchema() const;
114 
115  /// Returns the file format used by this layer.
116  SDF_API const SdfFileFormatConstPtr& GetFileFormat() const;
117 
118  /// Type for specifying additional file format-specific arguments to
119  /// layer API.
120  typedef std::map<std::string, std::string> FileFormatArguments;
121 
122  /// Returns the file format-specific arguments used during the construction
123  /// of this layer.
125 
126  /// Creates a new empty layer with the given identifier.
127  ///
128  /// Additional arguments may be supplied via the \p args parameter.
129  /// These arguments may control behavior specific to the layer's
130  /// file format.
131  SDF_API
132  static SdfLayerRefPtr CreateNew(const std::string &identifier,
133  const FileFormatArguments &args =
135 
136  /// Creates a new empty layer with the given identifier for a given file
137  /// format class.
138  ///
139  /// This function has the same behavior as the other CreateNew function,
140  /// but uses the explicitly-specified \p fileFormat instead of attempting
141  /// to discern the format from \p identifier.
142  SDF_API
143  static SdfLayerRefPtr CreateNew(const SdfFileFormatConstPtr& fileFormat,
144  const std::string &identifier,
145  const FileFormatArguments &args =
147 
148  /// Creates a new empty layer with the given identifier for a given file
149  /// format class.
150  ///
151  /// The new layer will not be dirty and will not be saved.
152  ///
153  /// Additional arguments may be supplied via the \p args parameter.
154  /// These arguments may control behavior specific to the layer's
155  /// file format.
156  SDF_API
157  static SdfLayerRefPtr New(const SdfFileFormatConstPtr& fileFormat,
158  const std::string &identifier,
159  const FileFormatArguments &args =
161 
162  /// Return an existing layer with the given \p identifier and \p args. If
163  /// the layer can't be found, an error is posted and a null layer is
164  /// returned.
165  ///
166  /// Arguments in \p args will override any arguments specified in
167  /// \p identifier.
168  SDF_API
169  static SdfLayerHandle Find(
170  const std::string &identifier,
172 
173  /// Return an existing layer with the given \p identifier and \p args.
174  /// The given \p identifier will be resolved relative to the \p anchor
175  /// layer. If the layer can't be found, an error is posted and a null
176  /// layer is returned.
177  ///
178  /// If the \p anchor layer is invalid, a coding error is raised, and a null
179  /// handle is returned.
180  ///
181  /// Arguments in \p args will override any arguments specified in
182  /// \p identifier.
183  SDF_API
184  static SdfLayerHandle FindRelativeToLayer(
185  const SdfLayerHandle &anchor,
186  const std::string &identifier,
188 
189  /// Return an existing layer with the given \p identifier and \p args, or
190  /// else load it. If the layer can't be found or loaded, an error is posted
191  /// and a null layer is returned.
192  ///
193  /// Arguments in \p args will override any arguments specified in
194  /// \p identifier.
195  SDF_API
196  static SdfLayerRefPtr FindOrOpen(
197  const std::string &identifier,
199 
200  /// Return an existing layer with the given \p identifier and \p args, or
201  /// else load it. The given \p identifier will be resolved relative to the
202  /// \p anchor layer. If the layer can't be found or loaded, an error is
203  /// posted and a null layer is returned.
204  ///
205  /// If the \p anchor layer is invalid, issues a coding error and returns
206  /// a null handle.
207  ///
208  /// Arguments in \p args will override any arguments specified in
209  /// \p identifier.
210  SDF_API
212  const SdfLayerHandle &anchor,
213  const std::string &identifier,
215 
216  /// Load the given layer from disk as a new anonymous layer. If the
217  /// layer can't be found or loaded, an error is posted and a null
218  /// layer is returned.
219  ///
220  /// The anonymous layer does not retain any knowledge of the backing
221  /// file on the filesystem.
222  ///
223  /// \p metadataOnly is a flag that asks for only the layer metadata
224  /// to be read in, which can be much faster if that is all that is
225  /// required. Note that this is just a hint: some FileFormat readers
226  /// may disregard this flag and still fully populate the layer contents.
227  ///
228  /// An optional \p tag may be specified. See CreateAnonymous for details.
229  SDF_API
231  const std::string &layerPath,
232  bool metadataOnly = false,
233  const std::string& tag = std::string());
234 
235  /// Returns the data from the absolute root path of this layer.
236  SDF_API
237  SdfDataRefPtr GetMetadata() const;
238 
239  /// Return hints about the layer's current contents. Any operation that
240  /// dirties the layer will invalidate all hints.
241  /// \sa SdfLayerHints
242  SDF_API
243  SdfLayerHints GetHints() const;
244 
245  /// Returns handles for all layers currently held by the layer registry.
246  SDF_API
248 
249  /// Returns whether this layer has no significant data.
250  SDF_API
251  bool IsEmpty() const;
252 
253  /// Returns true if this layer streams data from its serialized data
254  /// store on demand, false otherwise.
255  ///
256  /// Layers with streaming data are treated differently to avoid pulling
257  /// in data unnecessarily. For example, reloading a streaming layer
258  /// will not perform fine-grained change notification, since doing
259  /// so would require the full contents of the layer to be loaded.
260  SDF_API
261  bool StreamsData() const;
262 
263  /// Returns true if this layer is detached from its serialized data
264  /// store, false otherwise.
265  ///
266  /// Detached layers are isolated from external changes to their serialized
267  /// data.
268  SDF_API
269  bool IsDetached() const;
270 
271  /// Copies the content of the given layer into this layer.
272  /// Source layer is unmodified.
273  SDF_API
274  void TransferContent(const SdfLayerHandle& layer);
275 
276  /// Creates a new \e anonymous layer with an optional \p tag. An anonymous
277  /// layer is a layer with a system assigned identifier, that cannot be
278  /// saved to disk via Save(). Anonymous layers have an identifier, but no
279  /// real path or other asset information fields.
280  ///
281  /// Anonymous layers may be tagged, which can be done to aid debugging
282  /// subsystems that make use of anonymous layers. The tag becomes the
283  /// display name of an anonymous layer, and is also included in the
284  /// generated identifier. Untagged anonymous layers have an empty display
285  /// name.
286  ///
287  /// Additional arguments may be supplied via the \p args parameter.
288  /// These arguments may control behavior specific to the layer's
289  /// file format.
290  SDF_API
292  const std::string& tag = std::string(),
294 
295  /// Create an anonymous layer with a specific \p format.
296  SDF_API
298  const std::string &tag, const SdfFileFormatConstPtr &format,
300 
301  /// Returns true if this layer is an anonymous layer.
302  SDF_API
303  bool IsAnonymous() const;
304 
305  /// Returns true if the \p identifier is an anonymous layer unique
306  /// identifier.
307  SDF_API
308  static bool IsAnonymousLayerIdentifier(const std::string& identifier);
309 
310  /// Returns the display name for the given \p identifier, using the same
311  /// rules as GetDisplayName.
312  SDF_API
314  const std::string& identifier);
315 
316  /// @}
317  /// \name File I/O
318  /// @{
319 
320  /// Returns \c true if successful, \c false if an error occurred.
321  /// Returns \c false if the layer has no remembered file name or the
322  /// layer type cannot be saved. The layer will not be overwritten if the
323  /// file exists and the layer is not dirty unless \p force is true.
324  SDF_API
325  bool Save(bool force = false) const;
326 
327  /// Exports this layer to a file.
328  /// Returns \c true if successful, \c false if an error occurred.
329  ///
330  /// If \p comment is not empty, the layer gets exported with the given
331  /// comment. Additional arguments may be supplied via the \p args parameter.
332  /// These arguments may control behavior specific to the exported layer's
333  /// file format.
334  ///
335  /// Note that the file name or comment of the original layer is not
336  /// updated. This only saves a copy of the layer to the given filename.
337  /// Subsequent calls to Save() will still save the layer to it's
338  /// previously remembered file name.
339  SDF_API
340  bool Export(const std::string& filename,
341  const std::string& comment = std::string(),
342  const FileFormatArguments& args = FileFormatArguments()) const;
343 
344  /// Writes this layer to the given string.
345  ///
346  /// Returns \c true if successful and sets \p result, otherwise
347  /// returns \c false.
348  SDF_API
349  bool ExportToString(std::string* result) const;
350 
351  /// Reads this layer from the given string.
352  ///
353  /// Returns \c true if successful, otherwise returns \c false.
354  SDF_API
355  bool ImportFromString(const std::string &string);
356 
357  /// Clears the layer of all content.
358  ///
359  /// This restores the layer to a state as if it had just been created
360  /// with CreateNew(). This operation is Undo-able.
361  ///
362  /// The fileName and whether journaling is enabled are not affected
363  /// by this method.
364  SDF_API
365  void Clear();
366 
367  /// Reloads the layer from its persistent representation.
368  ///
369  /// This restores the layer to a state as if it had just been created
370  /// with FindOrOpen(). This operation is Undo-able.
371  ///
372  /// The fileName and whether journaling is enabled are not affected
373  /// by this method.
374  ///
375  /// When called with force = false (the default), Reload attempts to
376  /// avoid reloading layers that have not changed on disk. It does so
377  /// by comparing the file's modification time (mtime) to when the
378  /// file was loaded. If the layer has unsaved modifications, this
379  /// mechanism is not used, and the layer is reloaded from disk. If the
380  /// layer has any
381  /// \ref GetExternalAssetDependencies "external asset dependencies"
382  /// their modification state will also be consulted when determining if
383  /// the layer needs to be reloaded.
384  ///
385  /// Passing true to the \p force parameter overrides this behavior,
386  /// forcing the layer to be reloaded from disk regardless of whether
387  /// it has changed.
388  SDF_API
389  bool Reload(bool force = false);
390 
391  /// Reloads the specified layers.
392  ///
393  /// Returns \c false if one or more layers failed to reload.
394  ///
395  /// See \c Reload() for a description of the \p force flag.
396  ///
397  SDF_API
398  static bool ReloadLayers(const std::set<SdfLayerHandle>& layers,
399  bool force = false);
400 
401  /// Imports the content of the given layer path, replacing the content
402  /// of the current layer.
403  /// Note: If the layer path is the same as the current layer's real path,
404  /// no action is taken (and a warning occurs). For this case use
405  /// Reload().
406  SDF_API
407  bool Import(const std::string &layerPath);
408 
409  /// @}
410  /// \name External references
411  /// @{
412 
413  /// \deprecated
414  /// Use GetCompositionAssetDependencies instead.
415  SDF_API
416  std::set<std::string> GetExternalReferences() const;
417 
418  /// \deprecated
419  /// Use UpdateCompositionAssetDependency instead.
420  SDF_API
422  const std::string &oldAssetPath,
423  const std::string &newAssetPath=std::string());
424 
425  /// Return paths of all assets this layer depends on due to composition
426  /// fields.
427  ///
428  /// This includes the paths of all layers referred to by reference,
429  /// payload, and sublayer fields in this layer. This function only returns
430  /// direct composition dependencies of this layer, i.e. it does not recurse
431  /// to find composition dependencies from its dependent layer assets.
432  SDF_API
433  std::set<std::string> GetCompositionAssetDependencies() const;
434 
435  /// Updates the asset path of a composation dependency in this layer.
436  ///
437  /// If \p newAssetPath is supplied, the update works as "rename", updating
438  /// any occurrence of \p oldAssetPath to \p newAssetPath in all reference,
439  /// payload, and sublayer fields.
440  ///
441  /// If \p newAssetPath is not given, this update behaves as a "delete",
442  /// removing all occurrences of \p oldAssetPath from all reference, payload,
443  /// and sublayer fields.
444  SDF_API
446  const std::string &oldAssetPath,
447  const std::string &newAssetPath=std::string());
448 
449  /// Returns a set of resolved paths to all external asset dependencies
450  /// the layer needs to generate its contents. These are additional asset
451  /// dependencies that are determined by the layer's
452  /// \ref SdfFileFormat::GetExternalAssetDependencies "file format" and
453  /// will be consulted during Reload() when determining if the layer needs
454  /// to be reloaded. This specifically does not include dependencies related
455  /// to composition, i.e. this will not include assets from references,
456  /// payloads, and sublayers.
457  SDF_API
458  std::set<std::string> GetExternalAssetDependencies() const;
459 
460  /// @}
461  /// \name Identification
462  ///
463  /// A layer's identifier is a string that uniquely identifies a layer.
464  /// At minimum, it is the string by which the layer was created, either
465  /// via FindOrOpen or CreateNew. If additional arguments were passed
466  /// to those functions, those arguments will be encoded in the identifier.
467  ///
468  /// For example:
469  /// FindOrOpen('foo.sdf', args={'a':'b', 'c':'d'}).identifier
470  /// => "foo.sdf:SDF_FORMAT_ARGS:a=b&c=d"
471  ///
472  /// Note that this means the identifier may in general not be a path.
473  ///
474  /// The identifier format is subject to change; consumers should NOT
475  /// parse layer identifiers themselves, but should use the supplied
476  /// SplitIdentifier and CreateIdentifier helper functions.
477  ///
478  /// @{
479 
480  /// Splits the given layer identifier into its constituent layer path
481  /// and arguments.
482  SDF_API
483  static bool SplitIdentifier(
484  const std::string& identifier,
485  std::string* layerPath,
486  FileFormatArguments* arguments);
487 
488  /// Joins the given layer path and arguments into an identifier.
489  SDF_API
491  const std::string& layerPath,
492  const FileFormatArguments& arguments);
493 
494  /// Returns the layer identifier.
495  SDF_API
496  const std::string& GetIdentifier() const;
497 
498  /// Sets the layer identifier.
499  /// Note that the new identifier must have the same arguments (if any)
500  /// as the old identifier.
501  SDF_API
502  void SetIdentifier(const std::string& identifier);
503 
504  /// Update layer asset information. Calling this method re-resolves the
505  /// layer identifier, which updates asset information such as the layer's
506  /// resolved path and other asset info. This may be used to update the
507  /// layer after external changes to the underlying asset system.
508  SDF_API
509  void UpdateAssetInfo();
510 
511  /// Returns the layer's display name.
512  ///
513  /// The display name is the base filename of the identifier.
514  SDF_API
515  std::string GetDisplayName() const;
516 
517  /// Returns the resolved path for this layer. This is the path where
518  /// this layer exists or may exist after a call to Save().
519  SDF_API
520  const ArResolvedPath& GetResolvedPath() const;
521 
522  /// Returns the resolved path for this layer. This is equivalent to
523  /// GetResolvedPath().GetPathString().
524  SDF_API
525  const std::string& GetRealPath() const;
526 
527  /// Returns the file extension to use for this layer.
528  /// If this layer was loaded from disk, it should match the extension
529  /// of the file format it was loaded as; if this is an anonymous
530  /// in-memory layer it will be the default extension.
531  SDF_API
533 
534  /// Returns the asset system version of this layer. If a layer is loaded
535  /// from a location that is not version managed, or a configured asset
536  /// system is not present when the layer is loaded or created, the version
537  /// is empty. By default, asset version tracking is disabled; this method
538  /// returns empty unless asset version tracking is enabled.
539  SDF_API
540  const std::string& GetVersion() const;
541 
542  /// Returns the layer identifier in asset path form. In the presence of a
543  /// properly configured path resolver, the asset path is a double-slash
544  /// prefixed depot path. If the path resolver is not configured, the asset
545  /// path of a layer is empty.
546  SDF_API
547  const std::string& GetRepositoryPath() const;
548 
549  /// Returns the asset name associated with this layer.
550  SDF_API
551  const std::string& GetAssetName() const;
552 
553  /// Returns resolve information from the last time the layer identifier
554  /// was resolved.
555  SDF_API
556  const VtValue& GetAssetInfo() const;
557 
558  /// Returns the path to the asset specified by \p assetPath using this layer
559  /// to anchor the path if necessary. Returns \p assetPath if it's empty or
560  /// an anonymous layer identifier.
561  ///
562  /// This method can be used on asset paths that are authored in this layer
563  /// to create new asset paths that can be copied to other layers. These new
564  /// asset paths should refer to the same assets as the original asset
565  /// paths. For example, if the underlying ArResolver is filesystem-based and
566  /// \p assetPath is a relative filesystem path, this method might return the
567  /// absolute filesystem path using this layer's location as the anchor.
568  ///
569  /// The returned path should in general not be assumed to be an absolute
570  /// filesystem path or any other specific form. It is "absolute" in that it
571  /// should resolve to the same asset regardless of what layer it's authored
572  /// in.
573  SDF_API
574  std::string ComputeAbsolutePath(const std::string& assetPath) const;
575 
576  /// @}
577 
578  /// \name Fields
579  ///
580  /// All scene description for a given object is stored as a set of
581  /// key/value pairs called fields. These methods provide direct access to
582  /// those fields, though most clients should use the Spec API to ensure
583  /// data consistency.
584  ///
585  /// These methods all take SdfPath to identify the queried spec.
586  ///
587  /// @{
588 
589  /// Return the spec type for \a path. This returns SdfSpecTypeUnknown if no
590  /// spec exists at \a path.
591  SDF_API
592  SdfSpecType GetSpecType(const SdfPath& path) const;
593 
594  /// Return whether a spec exists at \a path.
595  SDF_API
596  bool HasSpec(const SdfPath& path) const;
597 
598  /// Return the names of all the fields that are set at \p path.
599  SDF_API
600  std::vector<TfToken> ListFields(const SdfPath& path) const;
601 
602  /// Return whether a value exists for the given \a path and \a fieldName.
603  /// Optionally returns the value if it exists.
604  SDF_API
605  bool HasField(const SdfPath& path, const TfToken& fieldName,
606  VtValue *value=NULL) const;
607  SDF_API
608  bool HasField(const SdfPath& path, const TfToken& fieldName,
609  SdfAbstractDataValue *value) const;
610 
611  /// Returns \c true if the object has a non-empty value with name
612  /// \p name and type \p T. If value ptr is provided, returns the
613  /// value found.
614  template <class T>
615  bool HasField(const SdfPath& path, const TfToken &name,
616  T* value) const
617  {
618  if (!value) {
619  return HasField(path, name, static_cast<VtValue *>(NULL));
620  }
621 
622  SdfAbstractDataTypedValue<T> outValue(value);
623  const bool hasValue = HasField(
624  path, name, static_cast<SdfAbstractDataValue *>(&outValue));
625 
627  return hasValue && outValue.isValueBlock;
628  }
629 
630  return hasValue && (!outValue.isValueBlock);
631  }
632 
633  /// Return the type of the value for \p name on spec \p path. If no such
634  /// field exists, return typeid(void).
635  std::type_info const &GetFieldTypeid(
636  const SdfPath &path, const TfToken &name) const {
637  return _data->GetTypeid(path, name);
638  }
639 
640  /// Return whether a value exists for the given \a path and \a fieldName and
641  /// \a keyPath. The \p keyPath is a ':'-separated path addressing an
642  /// element in sub-dictionaries. Optionally returns the value if it exists.
643  SDF_API
644  bool HasFieldDictKey(const SdfPath& path,
645  const TfToken &fieldName,
646  const TfToken &keyPath,
647  VtValue *value=NULL) const;
648  SDF_API
649  bool HasFieldDictKey(const SdfPath& path,
650  const TfToken &fieldName,
651  const TfToken &keyPath,
652  SdfAbstractDataValue *value) const;
653 
654  /// Returns \c true if the object has a non-empty value with name \p name
655  /// and \p keyPath and type \p T. If value ptr is provided, returns the
656  /// value found. The \p keyPath is a ':'-separated path addressing an
657  /// element in sub-dictionaries.
658  template <class T>
659  bool HasFieldDictKey(const SdfPath& path, const TfToken &name,
660  const TfToken &keyPath, T* value) const
661  {
662  if (!value) {
663  return HasFieldDictKey(path, name, keyPath,
664  static_cast<VtValue *>(NULL));
665  }
666 
667  SdfAbstractDataTypedValue<T> outValue(value);
668  return HasFieldDictKey(path, name, keyPath,
669  static_cast<SdfAbstractDataValue *>(&outValue));
670  }
671 
672 
673  /// Return the value for the given \a path and \a fieldName. Returns an
674  /// empty value if none is set.
675  SDF_API
676  VtValue GetField(const SdfPath& path,
677  const TfToken& fieldName) const;
678 
679  /// Return the value for the given \a path and \a fieldName. Returns the
680  /// provided \a defaultValue value if none is set.
681  template <class T>
682  inline T GetFieldAs(const SdfPath& path,
683  const TfToken& fieldName, const T& defaultValue = T()) const
684  {
685  return _data->GetAs<T>(path, fieldName, defaultValue);
686  }
687 
688  /// Return the value for the given \a path and \a fieldName at \p
689  /// keyPath. Returns an empty value if none is set. The \p keyPath is a
690  /// ':'-separated path addressing an element in sub-dictionaries.
691  SDF_API
693  const TfToken& fieldName,
694  const TfToken& keyPath) const;
695 
696  /// Set the value of the given \a path and \a fieldName.
697  SDF_API
698  void SetField(const SdfPath& path, const TfToken& fieldName,
699  const VtValue& value);
700  SDF_API
701  void SetField(const SdfPath& path, const TfToken& fieldName,
703 
704  /// Set the value of the given \a path and \a fieldName.
705  template <class T>
706  void SetField(const SdfPath& path, const TfToken& fieldName,
707  const T& val)
708  {
709  // Ideally, this would make use of the SdfAbstractDataConstValue
710  // API to avoid unnecessarily copying the value into a VtValue.
711  // However, Sdf needs to create a VtValue for change processing.
712  // If the underlying SdAbstractData implementation also needs a
713  // VtValue, using the SdfAbstractDataConstValue API would cause
714  // another copy to be made. So, it's more efficient to just create
715  // the VtValue once here and push that along.
716  SetField(path, fieldName, VtValue(val));
717  }
718 
719  /// Set the value of the given \a path and \a fieldName. The \p keyPath is a
720  /// ':'-separated path addressing an element in sub-dictionaries.
721  SDF_API
722  void SetFieldDictValueByKey(const SdfPath& path,
723  const TfToken& fieldName,
724  const TfToken& keyPath,
725  const VtValue& value);
726  SDF_API
727  void SetFieldDictValueByKey(const SdfPath& path,
728  const TfToken& fieldName,
729  const TfToken& keyPath,
731 
732  /// Set the value of the given \a path and \a fieldName. The \p keyPath is
733  /// a ':'-separated path addressing an element in sub-dictionaries.
734  template <class T>
735  void SetFieldDictValueByKey(const SdfPath& path,
736  const TfToken& fieldName,
737  const TfToken& keyPath,
738  const T& val)
739  {
740  // Ideally, this would make use of the SdfAbstractDataConstValue
741  // API to avoid unnecessarily copying the value into a VtValue.
742  // However, Sdf needs to create a VtValue for change processing.
743  // If the underlying SdAbstractData implementation also needs
744  // VtValue, using the SdfAbstractDataConstValue API would cause
745  // another copy to be made. So, it's more efficient to just create
746  // the VtValue once here and push that along.
747  SetFieldDictValueByKey(path, fieldName, keyPath, VtValue(val));
748  }
749 
750  /// Remove the field at \p path and \p fieldName, if one exists.
751  SDF_API
752  void EraseField(const SdfPath& path, const TfToken& fieldName);
753 
754  /// Remove the field at \p path and \p fieldName and \p keyPath, if one
755  /// exists. The \p keyPath is a ':'-separated path addressing an
756  /// element in sub-dictionaries.
757  SDF_API
758  void EraseFieldDictValueByKey(const SdfPath& path,
759  const TfToken& fieldName,
760  const TfToken& keyPath);
761 
762  /// \name Traversal
763  /// @{
764 
765  /// Callback function for Traverse. This callback will be invoked with
766  /// the path of each spec that is visited.
767  /// \sa Traverse
768  typedef std::function<void(const SdfPath&)> TraversalFunction;
769 
770  // Traverse will perform a traversal of the scene description hierarchy
771  // rooted at \a path, calling \a func on each spec that it finds.
772  SDF_API
773  void Traverse(const SdfPath& path, const TraversalFunction& func);
774 
775  /// @}
776 
777  /// \name Metadata
778  /// @{
779 
780  /// Returns the color configuration asset-path for this layer.
781  ///
782  /// The default value is an empty asset-path.
783  SDF_API
785 
786  /// Sets the color configuration asset-path for this layer.
787  SDF_API
788  void SetColorConfiguration(const SdfAssetPath &colorConfiguration);
789 
790  /// Returns true if color configuration metadata is set in this layer.
791  /// \sa GetColorConfiguration(), SetColorConfiguration()
792  SDF_API
793  bool HasColorConfiguration() const;
794 
795  /// Clears the color configuration metadata authored in this layer.
796  /// \sa HasColorConfiguration(), SetColorConfiguration()
797  SDF_API
799 
800  /// Returns the color management system used to interpret the color
801  /// configuration asset-path authored in this layer.
802  ///
803  /// The default value is an empty token, which implies that the clients
804  /// will have to determine the color management system from the color
805  /// configuration asset path (i.e. from its file extension), if it's
806  /// specified.
807  SDF_API
809 
810  /// Sets the color management system used to interpret the color
811  /// configuration asset-path authored this layer.
812  SDF_API
813  void SetColorManagementSystem(const TfToken &cms);
814 
815  /// Returns true if colorManagementSystem metadata is set in this layer.
816  /// \sa GetColorManagementSystem(), SetColorManagementSystem()
817  SDF_API
818  bool HasColorManagementSystem() const;
819 
820  /// Clears the 'colorManagementSystem' metadata authored in this layer.
821  /// \sa HascolorManagementSystem(), SetColorManagementSystem()
822  SDF_API
824 
825  /// Returns the comment string for this layer.
826  ///
827  /// The default value for comment is "".
828  SDF_API
829  std::string GetComment() const;
830 
831  /// Sets the comment string for this layer.
832  SDF_API
833  void SetComment(const std::string &comment);
834 
835  /// Return the defaultPrim metadata for this layer. This field
836  /// indicates the name of which root prim should be targeted by a reference
837  /// or payload to this layer that doesn't specify a prim path.
838  ///
839  /// The default value is the empty token.
840  SDF_API
841  TfToken GetDefaultPrim() const;
842 
843  /// Set the default prim metadata for this layer. The root prim with this
844  /// name will be targeted by a reference or a payload to this layer that
845  /// doesn't specify a prim path. Note that this must be a root prim
846  /// <b>name</b> not a path. E.g. "rootPrim" rather than "/rootPrim". See
847  /// GetDefaultPrim().
848  SDF_API
849  void SetDefaultPrim(const TfToken &name);
850 
851  /// Clear the default prim metadata for this layer. See GetDefaultPrim()
852  /// and SetDefaultPrim().
853  SDF_API
854  void ClearDefaultPrim();
855 
856  /// Return true if the default prim metadata is set in this layer. See
857  /// GetDefaultPrim() and SetDefaultPrim().
858  SDF_API
859  bool HasDefaultPrim();
860 
861  /// Returns the documentation string for this layer.
862  ///
863  /// The default value for documentation is "".
864  SDF_API
866 
867  /// Sets the documentation string for this layer.
868  SDF_API
869  void SetDocumentation(const std::string &documentation);
870 
871  /// Returns the layer's start timeCode.
872  ///
873  /// The start and end timeCodes of a layer represent the suggested playback
874  /// range. However, time-varying content is not limited to the timeCode range
875  /// of the layer.
876  ///
877  /// The default value for startTimeCode is 0.
878  SDF_API
879  double GetStartTimeCode() const;
880 
881  /// Sets the layer's start timeCode.
882  SDF_API
883  void SetStartTimeCode(double startTimecode);
884 
885  /// Returns true if the layer has a startTimeCode opinion.
886  SDF_API
887  bool HasStartTimeCode() const;
888 
889  /// Clear the startTimeCode opinion.
890  SDF_API
891  void ClearStartTimeCode();
892 
893  /// Returns the layer's end timeCode.
894  /// The start and end timeCode of a layer represent a suggested playback range.
895  /// However, time-varying content is not limited to the timeCode range of the
896  /// layer.
897  ///
898  /// The default value for endTimeCode is 0.
899  SDF_API
900  double GetEndTimeCode() const;
901 
902  /// Sets the layer's end timeCode.
903  SDF_API
904  void SetEndTimeCode(double endTimeCode);
905 
906  /// Returns true if the layer has an endTimeCode opinion.
907  SDF_API
908  bool HasEndTimeCode() const;
909 
910  /// Clear the endTimeCode opinion.
911  SDF_API
912  void ClearEndTimeCode();
913 
914  /// Returns the layer's timeCodes per second.
915  ///
916  /// Scales the time ordinate for samples contained in the file to seconds.
917  /// If timeCodesPerSecond is 24, then a sample at time ordinate 24 should
918  /// be viewed exactly one second after the sample at time ordinate 0.
919  ///
920  /// If this layer doesn't have an authored value for timeCodesPerSecond, but
921  /// it does have an authored value for framesPerSecond, this method will
922  /// return the value of framesPerSecond. This "dynamic fallback" allows
923  /// layers to lock framesPerSecond and timeCodesPerSecond to the same value
924  /// by specifying only framesPerSecond.
925  ///
926  /// The default value of timeCodesPerSecond, used only if there is no
927  /// authored value for either timeCodesPerSecond or framesPerSecond, is 24.
928  SDF_API
929  double GetTimeCodesPerSecond() const;
930 
931  /// Sets the layer's timeCodes per second
932  SDF_API
933  void SetTimeCodesPerSecond(double timeCodesPerSecond);
934 
935  /// Returns true if the layer has a timeCodesPerSecond opinion.
936  SDF_API
937  bool HasTimeCodesPerSecond() const;
938 
939  /// Clear the timeCodesPerSecond opinion.
940  SDF_API
942 
943  /// Returns the layer's frames per second.
944  ///
945  /// This makes an advisory statement about how the contained data can be
946  /// most usefully consumed and presented. It's primarily an indication of
947  /// the expected playback rate for the data, but a timeline editing tool
948  /// might also want to use this to decide how to scale and label its
949  /// timeline.
950  ///
951  /// The default value for framesPerSecond is 24.
952  SDF_API
953  double GetFramesPerSecond() const;
954 
955  /// Sets the layer's frames per second
956  SDF_API
957  void SetFramesPerSecond(double framesPerSecond);
958 
959  /// Returns true if the layer has a frames per second opinion.
960  SDF_API
961  bool HasFramesPerSecond() const;
962 
963  /// Clear the framesPerSecond opinion.
964  SDF_API
965  void ClearFramesPerSecond();
966 
967  /// Returns the layer's frame precision.
968  SDF_API
969  int GetFramePrecision() const;
970 
971  /// Sets the layer's frame precision.
972  SDF_API
973  void SetFramePrecision(int framePrecision);
974 
975  /// Returns true if the layer has a frames precision opinion.
976  SDF_API
977  bool HasFramePrecision() const;
978 
979  /// Clear the framePrecision opinion.
980  SDF_API
981  void ClearFramePrecision();
982 
983  /// Returns the layer's owner.
984  SDF_API
985  std::string GetOwner() const;
986 
987  /// Sets the layer's owner.
988  SDF_API
989  void SetOwner(const std::string& owner);
990 
991  /// Returns true if the layer has an owner opinion.
992  SDF_API
993  bool HasOwner() const;
994 
995  /// Clear the owner opinion.
996  SDF_API
997  void ClearOwner();
998 
999  /// Returns the layer's session owner.
1000  /// Note: This should only be used by session layers.
1001  SDF_API
1002  std::string GetSessionOwner() const;
1003 
1004  /// Sets the layer's session owner.
1005  /// Note: This should only be used by session layers.
1006  SDF_API
1007  void SetSessionOwner(const std::string& owner);
1008 
1009  /// Returns true if the layer has a session owner opinion.
1010  SDF_API
1011  bool HasSessionOwner() const;
1012 
1013  // Clear the session owner opinion.
1014  SDF_API
1015  void ClearSessionOwner();
1016 
1017  /// Returns true if the layer's sublayers are expected to have owners.
1018  SDF_API
1019  bool GetHasOwnedSubLayers() const;
1020 
1021  /// Sets whether the layer's sublayers are expected to have owners.
1022  SDF_API
1023  void SetHasOwnedSubLayers(bool);
1024 
1025  /// Returns the CustomLayerData dictionary associated with this layer.
1026  ///
1027  /// This is a dictionary is custom metadata that is associated with
1028  /// this layer. It allows users to encode any set of information for
1029  /// human or program consumption.
1030  SDF_API
1032 
1033  /// Sets the CustomLayerData dictionary associated with this layer.
1034  SDF_API
1035  void SetCustomLayerData(const VtDictionary& value);
1036 
1037  /// Returns true if CustomLayerData is authored on the layer.
1038  SDF_API
1039  bool HasCustomLayerData() const;
1040 
1041  /// Clears out the CustomLayerData dictionary associated with this layer.
1042  SDF_API
1043  void ClearCustomLayerData();
1044 
1045  /// Returns the expression variables dictionary authored on this layer.
1046  /// See \ref Sdf_Page_VariableExpressions for more details.
1047  SDF_API
1049 
1050  /// Sets the expression variables dictionary for this layer.
1051  SDF_API
1052  void SetExpressionVariables(const VtDictionary& expressionVars);
1053 
1054  /// Returns true if expression variables are authored on this layer.
1055  SDF_API
1056  bool HasExpressionVariables() const;
1057 
1058  /// Clears the expression variables dictionary authored on this layer.
1059  SDF_API
1060  void ClearExpressionVariables();
1061 
1062  /// @}
1063  /// \name Prims
1064  /// @{
1065 
1066  // Type for root prims view.
1068 
1069  /// Returns a vector of the layer's root prims
1070  SDF_API
1071  RootPrimsView GetRootPrims() const;
1072 
1073  /// Sets a new vector of root prims.
1074  /// You can re-order, insert and remove prims but cannot
1075  /// rename them this way. If any of the listed prims have
1076  /// an existing owner, they will be reparented.
1077  SDF_API
1078  void SetRootPrims(const SdfPrimSpecHandleVector &rootPrims);
1079 
1080  /// Adds a new root prim at the given index.
1081  /// If the index is -1, the prim is inserted at the end.
1082  /// The layer will take ownership of the prim, via a TfRefPtr.
1083  /// Returns true if successful, false if failed (for example,
1084  /// due to a duplicate name).
1085  SDF_API
1086  bool InsertRootPrim(const SdfPrimSpecHandle &prim, int index = -1);
1087 
1088  /// Remove a root prim.
1089  SDF_API
1090  void RemoveRootPrim(const SdfPrimSpecHandle &prim);
1091 
1092  /// Cause \p spec to be removed if it no longer affects the scene when the
1093  /// last change block is closed, or now if there are no change blocks.
1094  SDF_API
1095  void ScheduleRemoveIfInert(const SdfSpec& spec);
1096 
1097  /// Removes scene description that does not affect the scene in the
1098  /// layer namespace beginning with \p prim.
1099  ///
1100  /// Calling this method on a prim will only clean up prims with specifier
1101  /// 'over' that are not contributing any opinions. The \p prim will only
1102  /// be removed if all of its nameChildren are also inert. The hierarchy
1103  /// \p prim is defined in will be pruned up to the layer root for each
1104  /// successive inert parent that has specifier 'over'.
1105  ///
1106  /// note: PrimSpecs that contain any PropertySpecs, even PropertySpecs with
1107  /// required fields only (see PropertySpec::HasRequiredFieldsOnly)
1108  /// are not considered inert, and thus the prim won't be removed.
1109  SDF_API
1110  void RemovePrimIfInert(SdfPrimSpecHandle prim);
1111 
1112  /// Removes prop if it has only required fields (i.e. is not
1113  /// contributing any opinions to the scene other than property
1114  /// instantiation).
1115  ///
1116  /// The hierarchy \p prop is defined in will then be pruned up to the
1117  /// layer root for each successive inert parent.
1118  SDF_API
1119  void RemovePropertyIfHasOnlyRequiredFields(SdfPropertySpecHandle prop);
1120 
1121  /// Removes all scene description in this layer that does not affect the
1122  /// scene.
1123  ///
1124  /// This method walks the layer namespace hierarchy and removes any prims
1125  /// and that are not contributing any opinions.
1126  SDF_API
1128 
1129  /// Returns the list of prim names for this layer's reorder rootPrims
1130  /// statement.
1131  ///
1132  /// See SetRootPrimOrder() for more info.
1133  SDF_API
1135 
1136  /// Given a list of (possible sparse) prim names, authors a reorder
1137  /// rootPrims statement for this prim.
1138  ///
1139  /// This reorder statement can modify the order of root prims that have
1140  /// already been explicitly ordered with InsertRootPrim() or SetRootPrims();
1141  /// but only during composition. Therefore, GetRootPrims(),
1142  /// InsertRootPrim(), SetRootPrims(), etc. do not read, author, or pay any
1143  /// attention to this statement.
1144  SDF_API
1145  void SetRootPrimOrder(const std::vector<TfToken>& names);
1146 
1147  /// Adds a new root prim name in the root prim order.
1148  /// If the index is -1, the name is inserted at the end.
1149  SDF_API
1150  void InsertInRootPrimOrder(const TfToken &name, int index = -1);
1151 
1152  /// Removes a root prim name from the root prim order.
1153  SDF_API
1154  void RemoveFromRootPrimOrder(const TfToken & name);
1155 
1156  /// Removes a root prim name from the root prim order by index.
1157  SDF_API
1159 
1160  /// Reorders the given list of prim names according to the reorder rootPrims
1161  /// statement for this layer.
1162  ///
1163  /// This routine employs the standard list editing operations for ordered
1164  /// items in a ListEditor.
1165  SDF_API
1166  void ApplyRootPrimOrder(std::vector<TfToken> *vec) const;
1167 
1168  /// @}
1169  /// \name Sublayers
1170  /// @{
1171 
1172  /// Returns a proxy for this layer's sublayers.
1173  ///
1174  /// Sub-layers are the weaker layers directly included by this layer.
1175  /// They're in order from strongest to weakest and they're all weaker
1176  /// than this layer.
1177  ///
1178  /// Edits through the proxy changes the sublayers. If this layer does
1179  /// not have any sublayers the proxy is empty.
1180  ///
1181  /// Sub-layer paths are asset paths, and thus must contain valid asset path
1182  /// characters (UTF-8 without C0 and C1 controls). See SdfAssetPath for
1183  /// more details.
1184  SDF_API
1186 
1187  /// Sets the paths of the layer's sublayers.
1188  SDF_API
1189  void SetSubLayerPaths(const std::vector<std::string>& newPaths);
1190 
1191  /// Returns the number of sublayer paths (and offsets).
1192  SDF_API
1193  size_t GetNumSubLayerPaths() const;
1194 
1195  /// Inserts new sublayer path at the given index.
1196  ///
1197  /// The default index of -1 means to insert at the end.
1198  SDF_API
1199  void InsertSubLayerPath(const std::string& path, int index = -1);
1200 
1201  /// Removes sublayer path at the given index.
1202  SDF_API
1203  void RemoveSubLayerPath(int index);
1204 
1205  /// Returns the layer offsets for all the subLayer paths.
1206  SDF_API
1208 
1209  /// Returns the layer offset for the subLayer path at the given index.
1210  SDF_API
1212 
1213  /// Sets the layer offset for the subLayer path at the given index.
1214  SDF_API
1215  void SetSubLayerOffset(const SdfLayerOffset& offset, int index);
1216 
1217  /// @}
1218 
1219  /// \name Detached Layers
1220  ///
1221  /// Detached layers are layers that are detached from the serialized
1222  /// data store and isolated from any external changes to that serialized
1223  /// data.
1224  ///
1225  /// File format plugins may produce layers that maintain a persistent
1226  /// connection to their serialized representation to read data on-demand.
1227  /// For example, a file format might set up layers to hold an open file
1228  /// handle and read attribute time samples from it only when requested, to
1229  /// avoid pulling in unnecessary data. However, there may be times when
1230  /// keeping this connection is undesirable. In the previous example, a
1231  /// crash might occur if some other process were to change the file on
1232  /// disk, or users might be prevented from overwriting the file at all
1233  /// which could interfere with workflow.
1234  ///
1235  /// To avoid these problems, the functions below may be used to specify
1236  /// layers that are to be detached from the original serialized data.
1237  ///
1238  /// @{
1239 
1240  /// \class DetachedLayerRules
1241  ///
1242  /// Object used to specify detached layers. Layers may be included or
1243  /// excluded from the detached layer set by specifying simple substring
1244  /// patterns for layer identifiers. For example, the following will
1245  /// include all layers in the detached layer set, except for those whose
1246  /// identifiers contain the substring "sim" or "geom":
1247  ///
1248  /// \code
1249  /// SdfLayer::SetDetachedLayerRules(
1250  /// SdfLayer::DetachedLayerRules()
1251  /// .IncludeAll();
1252  /// .Exclude({"sim", "geom"})
1253  /// );
1254  /// \endcode
1256  {
1257  public:
1258  /// A default constructed rules object Excludes all layers from
1259  /// the detached layer set.
1260  DetachedLayerRules() = default;
1261 
1262  /// Include all layers in the detached layer set.
1264  {
1265  _includeAll = true;
1266  _include.clear();
1267  return *this;
1268  }
1269 
1270  /// Include layers whose identifiers contain any of the strings in
1271  /// \p patterns in the detached layer set.
1272  SDF_API
1273  DetachedLayerRules& Include(const std::vector<std::string>& patterns);
1274 
1275  /// Exclude layers whose identifiers contain any of the strings in
1276  /// \p patterns from the detached layer set.
1277  SDF_API
1278  DetachedLayerRules& Exclude(const std::vector<std::string>& patterns);
1279 
1280  bool IncludedAll() const { return _includeAll; }
1281  const std::vector<std::string>& GetIncluded() const { return _include; }
1282  const std::vector<std::string>& GetExcluded() const { return _exclude; }
1283 
1284  /// Returns true if \p identifier is included in the detached layer set,
1285  /// false otherwise.
1286  ///
1287  /// \p identifier is included if it matches an include pattern (or the
1288  /// mask includes all identifiers) and it does not match any of the
1289  /// exclude patterns. Anonymous layer identifiers are always excluded
1290  /// from the mask.
1291  SDF_API
1292  bool IsIncluded(const std::string& identifier) const;
1293 
1294  private:
1295  friend class SdfLayer;
1296 
1297  std::vector<std::string> _include;
1298  std::vector<std::string> _exclude;
1299  bool _includeAll = false;
1300  };
1301 
1302  /// Sets the rules specifying detached layers.
1303  ///
1304  /// Newly-created or opened layers whose identifiers are included in
1305  /// \p rules will be opened as detached layers. Existing layers that are now
1306  /// included or no longer included will be reloaded. Any unsaved
1307  /// modifications to those layers will be lost.
1308  ///
1309  /// This function is not thread-safe. It may not be run concurrently with
1310  /// any other functions that open, close, or read from any layers.
1311  ///
1312  /// The detached layer rules are initially set to exclude all layers.
1313  /// This may be overridden by setting the environment variables
1314  /// SDF_LAYER_INCLUDE_DETACHED and SDF_LAYER_EXCLUDE_DETACHED to specify
1315  /// the initial set of include and exclude patterns in the rules. These
1316  /// variables can be set to a comma-delimited list of patterns.
1317  /// SDF_LAYER_INCLUDE_DETACHED may also be set to "*" to include
1318  /// all layers. Note that these environment variables only set the initial
1319  /// state of the detached layer rules; these values may be overwritten by
1320  /// subsequent calls to this function.
1321  ///
1322  /// See SdfLayer::DetachedLayerRules::IsIncluded for details on how the
1323  /// rules are applied to layer identifiers.
1324  SDF_API
1325  static void SetDetachedLayerRules(const DetachedLayerRules& mask);
1326 
1327  /// Returns the current rules for the detached layer set.
1328  SDF_API
1329  static const DetachedLayerRules& GetDetachedLayerRules();
1330 
1331  /// Returns whether the given layer identifier is included in the
1332  /// current rules for the detached layer set. This is equivalent to
1333  /// GetDetachedLayerRules().IsIncluded(identifier).
1334  SDF_API
1335  static bool IsIncludedByDetachedLayerRules(const std::string& identifier);
1336 
1337  /// @}
1338 
1339  /// \name Muting
1340  /// @{
1341 
1342  /// Returns the set of muted layer paths.
1343  SDF_API
1344  static std::set<std::string> GetMutedLayers();
1345 
1346  /// Returns \c true if the current layer is muted.
1347  SDF_API
1348  bool IsMuted() const;
1349 
1350  /// Returns \c true if the specified layer path is muted.
1351  SDF_API
1352  static bool IsMuted(const std::string &path);
1353 
1354  /// Mutes the current layer if \p muted is \c true, and unmutes it
1355  /// otherwise.
1356  SDF_API
1357  void SetMuted(bool muted);
1358 
1359  /// Add the specified path to the muted layers set.
1360  SDF_API
1361  static void AddToMutedLayers(const std::string &mutedPath);
1362 
1363  /// Remove the specified path from the muted layers set.
1364  SDF_API
1365  static void RemoveFromMutedLayers(const std::string &mutedPath);
1366 
1367  /// @}
1368  /// \name Lookup
1369  /// @{
1370 
1371  /// Returns the layer's pseudo-root prim.
1372  ///
1373  /// The layer's root prims are namespace children of the pseudo-root.
1374  /// The pseudo-root exists to make the namespace hierarchy a tree
1375  /// instead of a forest. This simplifies the implementation of
1376  /// some algorithms.
1377  ///
1378  /// A layer always has a pseudo-root prim.
1379  SDF_API
1380  SdfPrimSpecHandle GetPseudoRoot() const;
1381 
1382  /// Returns the object at the given \p path.
1383  ///
1384  /// There is no distinction between an absolute and relative path
1385  /// at the SdLayer level.
1386  ///
1387  /// Returns \c NULL if there is no object at \p path.
1388  SDF_API
1389  SdfSpecHandle GetObjectAtPath(const SdfPath &path);
1390 
1391  /// Returns the prim at the given \p path.
1392  ///
1393  /// Returns \c NULL if there is no prim at \p path.
1394  /// This is simply a more specifically typed version of
1395  /// \c GetObjectAtPath().
1396  SDF_API
1397  SdfPrimSpecHandle GetPrimAtPath(const SdfPath &path);
1398 
1399  /// Returns a property at the given \p path.
1400  ///
1401  /// Returns \c NULL if there is no property at \p path.
1402  /// This is simply a more specifically typed version of
1403  /// \c GetObjectAtPath().
1404  SDF_API
1405  SdfPropertySpecHandle GetPropertyAtPath(const SdfPath &path);
1406 
1407  /// Returns an attribute at the given \p path.
1408  ///
1409  /// Returns \c NULL if there is no attribute at \p path.
1410  /// This is simply a more specifically typed version of
1411  /// \c GetObjectAtPath().
1412  SDF_API
1413  SdfAttributeSpecHandle GetAttributeAtPath(const SdfPath &path);
1414 
1415  /// Returns a relationship at the given \p path.
1416  ///
1417  /// Returns \c NULL if there is no relationship at \p path.
1418  /// This is simply a more specifically typed version of
1419  /// \c GetObjectAtPath().
1420  SDF_API
1421  SdfRelationshipSpecHandle GetRelationshipAtPath(const SdfPath &path);
1422 
1423  /// @}
1424  /// \name Permissions
1425  /// @{
1426 
1427  /// Returns true if the caller is allowed to modify the layer and
1428  /// false otherwise. A layer may have to perform some action to acquire
1429  /// permission to be edited.
1430  SDF_API
1431  bool PermissionToEdit() const;
1432 
1433  /// Returns true if the caller is allowed to save the layer to its
1434  /// existing fileName and false otherwise.
1435  SDF_API
1436  bool PermissionToSave() const;
1437 
1438  /// Sets permission to edit.
1439  SDF_API
1440  void SetPermissionToEdit(bool allow);
1441 
1442  /// Sets permission to save.
1443  SDF_API
1444  void SetPermissionToSave(bool allow);
1445 
1446  /// @}
1447  /// \name Batch namespace editing
1448  /// @{
1449 
1450  /// Check if a batch of namespace edits will succeed. This returns
1451  /// \c SdfNamespaceEditDetail::Okay if they will succeed as a batch,
1452  /// \c SdfNamespaceEditDetail::Unbatched if the edits will succeed but
1453  /// will be applied unbatched, and \c SdfNamespaceEditDetail::Error
1454  /// if they will not succeed. No edits will be performed in any case.
1455  ///
1456  /// If \p details is not \c NULL and the method does not return \c Okay
1457  /// then details about the problems will be appended to \p details. A
1458  /// problem may cause the method to return early, so \p details may not
1459  /// list every problem.
1460  ///
1461  /// Note that Sdf does not track backpointers so it's unable to fix up
1462  /// targets/connections to namespace edited objects. Clients must fix
1463  /// those to prevent them from falling off. In addition, this method
1464  /// will report failure if any relational attribute with a target to
1465  /// a namespace edited object is subsequently edited (in the same
1466  /// batch). Clients should perform edits on relational attributes
1467  /// first.
1468  ///
1469  /// Clients may wish to report unbatch details to the user to confirm
1470  /// that the edits should be applied unbatched. This will give the
1471  /// user a chance to correct any problems that cause batching to fail
1472  /// and try again.
1473  SDF_API
1476  SdfNamespaceEditDetailVector* details = NULL) const;
1477 
1478  /// Performs a batch of namespace edits. Returns \c true on success
1479  /// and \c false on failure. On failure, no namespace edits will have
1480  /// occurred.
1481  SDF_API
1482  bool Apply(const SdfBatchNamespaceEdit&);
1483 
1484  /// @}
1485  /// \name Layer state
1486  /// @{
1487 
1488  /// Returns the state delegate used to manage this layer's authoring
1489  /// state.
1490  SDF_API
1491  SdfLayerStateDelegateBasePtr GetStateDelegate() const;
1492 
1493  /// Sets the state delegate used to manage this layer's authoring
1494  /// state. The 'dirty' state of this layer will be transferred to
1495  /// the new delegate.
1496  SDF_API
1497  void SetStateDelegate(const SdfLayerStateDelegateBaseRefPtr& delegate);
1498 
1499  /// Returns \c true if the layer is dirty, i.e. has changed from
1500  /// its persistent representation.
1501  SDF_API
1502  bool IsDirty() const;
1503 
1504  /// @}
1505 
1506  /// \name Time-sample API
1507  /// @{
1508  SDF_API
1509  std::set<double> ListAllTimeSamples() const;
1510 
1511  SDF_API
1512  std::set<double>
1513  ListTimeSamplesForPath(const SdfPath& path) const;
1514 
1515  SDF_API
1516  bool GetBracketingTimeSamples(double time, double* tLower, double* tUpper);
1517 
1518  SDF_API
1519  size_t GetNumTimeSamplesForPath(const SdfPath& path) const;
1520 
1521  SDF_API
1522  bool GetBracketingTimeSamplesForPath(const SdfPath& path,
1523  double time,
1524  double* tLower, double* tUpper);
1525 
1526  SDF_API
1527  bool QueryTimeSample(const SdfPath& path, double time,
1528  VtValue *value=NULL) const;
1529  SDF_API
1530  bool QueryTimeSample(const SdfPath& path, double time,
1531  SdfAbstractDataValue *value) const;
1532 
1533  template <class T>
1534  bool QueryTimeSample(const SdfPath& path, double time,
1535  T* data) const
1536  {
1537  if (!data) {
1538  return QueryTimeSample(path, time);
1539  }
1540 
1541  SdfAbstractDataTypedValue<T> outValue(data);
1542  const bool hasValue = QueryTimeSample(
1543  path, time, static_cast<SdfAbstractDataValue *>(&outValue));
1544 
1546  return hasValue && outValue.isValueBlock;
1547  }
1548 
1549  return hasValue && (!outValue.isValueBlock);
1550  }
1551 
1552  SDF_API
1553  void SetTimeSample(const SdfPath& path, double time,
1554  const VtValue & value);
1555  SDF_API
1556  void SetTimeSample(const SdfPath& path, double time,
1558 
1559  template <class T>
1560  void SetTimeSample(const SdfPath& path, double time,
1561  const T& value)
1562  {
1563  const SdfAbstractDataConstTypedValue<T> inValue(&value);
1564  const SdfAbstractDataConstValue& untypedInValue = inValue;
1565  return SetTimeSample(path, time, untypedInValue);
1566  }
1567 
1568  SDF_API
1569  void EraseTimeSample(const SdfPath& path, double time);
1570 
1571  /// @}
1572 
1573  // Debugging
1574  // @{
1575 
1576  SDF_API
1577  static void DumpLayerInfo();
1578 
1579  // Write this layer's SdfData to a file in a simple generic format.
1580  SDF_API
1581  bool WriteDataFile(const std::string &filename);
1582 
1583  // @}
1584 
1585 protected:
1586  // Private constructor -- use New(), FindOrCreate(), etc.
1587  // Precondition: _layerRegistryMutex must be locked.
1588  SdfLayer(const SdfFileFormatConstPtr& fileFormat,
1589  const std::string &identifier,
1590  const std::string &realPath = std::string(),
1591  const ArAssetInfo& assetInfo = ArAssetInfo(),
1593  bool validateAuthoring = false);
1594 
1595 private:
1596  // Create a new layer.
1597  // Precondition: _layerRegistryMutex must be locked.
1598  static SdfLayerRefPtr _CreateNew(
1599  SdfFileFormatConstPtr fileFormat,
1600  const std::string& identifier,
1601  const FileFormatArguments& args,
1602  bool saveLayer = true);
1603 
1604  static SdfLayerRefPtr _CreateNewWithFormat(
1605  const SdfFileFormatConstPtr &fileFormat,
1606  const std::string& identifier,
1607  const std::string& realPath,
1608  const ArAssetInfo& assetInfo = ArAssetInfo(),
1610 
1611  static SdfLayerRefPtr _CreateAnonymousWithFormat(
1612  const SdfFileFormatConstPtr &fileFormat,
1613  const std::string& tag,
1614  const FileFormatArguments& args);
1615 
1616  // Finish initializing this layer (which may have succeeded or not)
1617  // and publish the results to other threads by unlocking the mutex.
1618  // Sets _initializationWasSuccessful.
1619  void _FinishInitialization(bool success);
1620 
1621  // Layers retrieved from the layer registry may still be in the
1622  // process of having their contents initialized. Other threads
1623  // retrieving layers from the registry must wait until initialization
1624  // is complete, using this method.
1625  // Returns _initializationWasSuccessful.
1626  //
1627  // Callers *must* be holding an SdfLayerRefPtr to this layer to
1628  // ensure that it is not deleted out from under them, in
1629  // case initialization fails. (This method cannot acquire the
1630  // reference itself internally without being susceptible to a race.)
1631  bool _WaitForInitializationAndCheckIfSuccessful();
1632 
1633  // Returns whether or not this layer should post change
1634  // notification. This simply returns (!_GetIsLoading())
1635  bool _ShouldNotify() const;
1636 
1637  // This function keeps track of the last state of IsDirty() before
1638  // updating it. It returns false if the last saved dirty state is the
1639  // same than the current state. It returns true if the state differs and
1640  // will update the 'last dirty state' to the current state. So, after
1641  // returning true, it would return false for subsequent calls until the
1642  // IsDirty() state would change again...
1643  bool _UpdateLastDirtinessState() const;
1644 
1645  // Returns a handle to the spec at the given path if it exists and matches
1646  // type T.
1647  template <class T>
1648  SdfHandle<T> _GetSpecAtPath(const SdfPath& path);
1649 
1650  // Returns true if a spec can be retrieved at the given path, false
1651  // otherwise. This function will return the canonicalized path to the
1652  // spec as well as the spec type.
1653  bool _CanGetSpecAtPath(const SdfPath& path,
1654  SdfPath* canonicalPath, SdfSpecType* specType) const;
1655 
1656  /// Initialize layer internals that are based on it's path.
1657  /// This includes the asset path and show path the layer to be loaded
1658  /// reflects at the point of initialization.
1659  void _InitializeFromIdentifier(
1660  const std::string &identifier,
1661  const std::string &realPath = std::string(),
1662  const std::string &fileVersion = std::string(),
1663  const ArAssetInfo& assetInfo = ArAssetInfo());
1664 
1665  // Helper for computing the necessary information to lookup a layer
1666  // in the registry or open the layer.
1667  struct _FindOrOpenLayerInfo;
1668  static bool _ComputeInfoToFindOrOpenLayer(
1669  const std::string& identifier,
1671  _FindOrOpenLayerInfo* info,
1672  bool computeAssetInfo = false);
1673 
1674  // Open a layer, adding an entry to the registry and releasing
1675  // the registry lock.
1676  // Precondition: _layerRegistryMutex must be locked.
1677  template <class Lock>
1678  static SdfLayerRefPtr _OpenLayerAndUnlockRegistry(
1679  Lock &lock,
1680  const _FindOrOpenLayerInfo& info,
1681  bool metadataOnly);
1682 
1683  // Helper function for finding a layer with \p identifier and \p args.
1684  // \p lock must be unlocked initially and will be locked by this
1685  // function when needed. See docs for \p retryAsWriter argument on
1686  // _TryToFindLayer for details on the final state of the lock when
1687  // this function returns.
1688  template <class ScopedLock>
1689  static SdfLayerRefPtr
1690  _Find(const std::string &identifier,
1691  const FileFormatArguments &args,
1692  ScopedLock &lock, bool retryAsWriter);
1693 
1694  // Helper function to try to find the layer with \p identifier and
1695  // pre-resolved path \p resolvedPath in the registry. Caller must hold
1696  // registry \p lock for reading. If \p retryAsWriter is false, lock is
1697  // released upon return. Otherwise the lock is released upon return if a
1698  // layer is found successfully. If no layer is found then the lock is
1699  // upgraded to a writer lock upon return. Note that this upgrade may not be
1700  // atomic, but this function ensures that if upon return there does not
1701  // exist a matching layer in the registry.
1702  template <class ScopedLock>
1703  static SdfLayerRefPtr
1704  _TryToFindLayer(const std::string &identifier,
1705  const ArResolvedPath &resolvedPath,
1706  ScopedLock &lock, bool retryAsWriter);
1707 
1708  /// Returns true if the spec at the specified path has no effect on the
1709  /// scene.
1710  ///
1711  /// If ignoreChildren is true, this will ignore prim and property
1712  /// children of prim specs. Property specs are always considered to be
1713  /// non-inert unless they have only required fields and
1714  /// requiredFieldOnlyPropertiesareInert is set to false.
1715  bool _IsInert(const SdfPath &path, bool ignoreChildren,
1716  bool requiredFieldOnlyPropertiesAreInert = false) const;
1717 
1718  /// Return true if the entire subtree rooted at \a path does not affect the
1719  /// scene. For this purpose, property specs that have only required fields
1720  /// are considered inert.
1721  bool _IsInertSubtree(const SdfPath &path) const;
1722 
1723  /// Cause \p spec to be removed if it does not affect the scene. This
1724  /// removes any empty descendants before checking if \p spec itself is
1725  /// inert. Property specs are always considered non-inert, so this will
1726  /// remove them if they have only required fields (see
1727  /// PropertySpec::HasOnlyRequiredFields). This also removes inert ancestors.
1728  void _RemoveIfInert(const SdfSpec& spec);
1729 
1730  /// Performs a depth first search of the namespace hierarchy, beginning at
1731  /// \p prim, removing prims that do not affect the scene. The return value
1732  /// indicates whether the prim passed in is now inert as a result of this
1733  /// call, and can itself be removed.
1734  bool _RemoveInertDFS(SdfPrimSpecHandle prim);
1735 
1736  /// If \p prim is inert (has no affect on the scene), removes prim, then
1737  /// prunes inert parent prims back to the root.
1738  void _RemoveInertToRootmost(SdfPrimSpecHandle prim);
1739 
1740  /// Returns whether this layer is validating authoring operations.
1741  bool _ValidateAuthoring() const { return _validateAuthoring; }
1742 
1743  /// Returns the path used in the muted layers set.
1744  std::string _GetMutedPath() const;
1745 
1746  // If old and new asset path is given, rename all external prim
1747  // composition dependency referring to the old path.
1748  void _UpdatePrimCompositionDependencyPaths(
1749  const SdfPrimSpecHandle &parent,
1750  const std::string &oldLayerPath,
1751  const std::string &newLayerPath);
1752 
1753  // Set the clean state to the current state.
1754  void _MarkCurrentStateAsClean() const;
1755 
1756  // Return the field definition for \p fieldName if \p fieldName is a
1757  // required field for the spec type identified by \p path.
1758  inline SdfSchema::FieldDefinition const *
1759  _GetRequiredFieldDef(const SdfPath &path,
1760  const TfToken &fieldName,
1761  SdfSpecType specType = SdfSpecTypeUnknown) const;
1762 
1763  // Return the field definition for \p fieldName if \p fieldName is a
1764  // required field for \p specType subject to \p schema.
1765  static inline SdfSchema::FieldDefinition const *
1766  _GetRequiredFieldDef(const SdfSchemaBase &schema,
1767  const TfToken &fieldName,
1768  SdfSpecType specType);
1769 
1770  // Helper to list all fields on \p data at \p path subject to \p schema.
1771  static std::vector<TfToken>
1772  _ListFields(SdfSchemaBase const &schema,
1773  SdfAbstractData const &data, const SdfPath& path);
1774 
1775  // Helper for HasField for \p path in \p data subject to \p schema.
1776  static inline bool
1777  _HasField(const SdfSchemaBase &schema,
1778  const SdfAbstractData &data,
1779  const SdfPath& path,
1780  const TfToken& fieldName,
1781  VtValue *value);
1782 
1783  // Helper to get a field value for \p path in \p data subject to \p schema.
1784  static inline VtValue
1785  _GetField(const SdfSchemaBase &schema,
1786  const SdfAbstractData &data,
1787  const SdfPath& path,
1788  const TfToken& fieldName);
1789 
1790  // Set a value.
1791  template <class T>
1792  void _SetValue(const TfToken& key, T value);
1793 
1794  // Get a value.
1795  template <class T>
1796  T _GetValue(const TfToken& key) const;
1797 
1798  enum _ReloadResult { _ReloadFailed, _ReloadSucceeded, _ReloadSkipped };
1799  _ReloadResult _Reload(bool force);
1800 
1801  // Reads contents of asset specified by \p identifier with resolved
1802  // path \p resolvedPath into this layer.
1803  bool _Read(const std::string& identifier,
1804  const ArResolvedPath& resolvedPath,
1805  bool metadataOnly);
1806 
1807  // Saves this layer if it is dirty or the layer doesn't already exist
1808  // on disk. If \p force is true, the layer will be written out
1809  // regardless of those conditions.
1810  bool _Save(bool force) const;
1811 
1812  // A helper method used by Save and Export.
1813  // This method allows Save to specify the existing file format and Export
1814  // to use the format provided by the file extension in newFileName. If no
1815  // file format can be discovered from the file name, the existing file
1816  // format associated with the layer will be used in both cases. This allows
1817  // users to export and save to any file name, regardless of extension.
1818  bool _WriteToFile(const std::string& newFileName,
1819  const std::string& comment,
1820  SdfFileFormatConstPtr fileFormat = TfNullPtr,
1822  const;
1823 
1824  // Swap contents of _data and data. This operation does not register
1825  // inverses or emit change notification.
1826  void _SwapData(SdfAbstractDataRefPtr &data);
1827 
1828  // Set _data to \p newData and send coarse DidReplaceLayerContent
1829  // invalidation notice.
1830  void _AdoptData(const SdfAbstractDataRefPtr &newData);
1831 
1832  // Set _data to match data, calling other primitive setter methods to
1833  // provide fine-grained inverses and notification. If \p data might adhere
1834  // to a different schema than this layer's, pass a pointer to it as \p
1835  // newDataSchema. In this case, check to see if fields from \p data are
1836  // known to this layer's schema, and if not, omit them and issue a TfError
1837  // with SdfAuthoringErrorUnrecognizedFields, but continue to set all other
1838  // known fields.
1839  void _SetData(const SdfAbstractDataPtr &newData,
1840  const SdfSchemaBase *newDataSchema=nullptr);
1841 
1842  // Returns const handle to _data.
1843  SdfAbstractDataConstPtr _GetData() const;
1844 
1845  // Returns a new SdfAbstractData object for this layer.
1846  SdfAbstractDataRefPtr _CreateData() const;
1847 
1848  // Inverse primitive for setting a single field. The previous value for the
1849  // field may be given via \p oldValue. If \p oldValue is non-nullptr, the
1850  // VtValue it points to will be moved-from after the function completes. If
1851  // \p oldValue is nullptr, the old field value will be retrieved
1852  // automatically.
1853  template <class T>
1854  void _PrimSetField(const SdfPath& path,
1855  const TfToken& fieldName,
1856  const T& value,
1857  VtValue *oldValue = nullptr,
1858  bool useDelegate = true);
1859 
1860  // Inverse primitive for setting a single key in a dict-valued field. The
1861  // previous dictionary value for the field (*not* the individual entry) may
1862  // be supplied via \p oldValue. If \p oldValue is non-nullptr, the VtValue
1863  // it points to will be moved-from after the function completes. If \p
1864  // oldValue is nullptr, the old field value will be retrieved automatically.
1865  template <class T>
1866  void _PrimSetFieldDictValueByKey(const SdfPath& path,
1867  const TfToken& fieldName,
1868  const TfToken& keyPath,
1869  const T& value,
1870  VtValue *oldValue = nullptr,
1871  bool useDelegate = true);
1872 
1873  // Primitive for appending a child to the list of children.
1874  template <class T>
1875  void _PrimPushChild(const SdfPath& parentPath,
1876  const TfToken& fieldName,
1877  const T& value,
1878  bool useDelegate = true);
1879  template <class T>
1880  void _PrimPopChild(const SdfPath& parentPath,
1881  const TfToken& fieldName,
1882  bool useDelegate = true);
1883 
1884  // Move all the fields at all paths at or below \a oldPath to be
1885  // at a corresponding location at or below \a newPath. This does
1886  // not update the children fields of the parents of these paths.
1887  bool _MoveSpec(const SdfPath &oldPath, const SdfPath &newPath);
1888 
1889  // Inverse primitive for moving a spec.
1890  void _PrimMoveSpec(const SdfPath &oldPath, const SdfPath &newPath,
1891  bool useDelegate = true);
1892 
1893  // Create a new spec of type \p specType at \p path.
1894  // Returns true if spec was successfully created, false otherwise.
1895  bool _CreateSpec(const SdfPath& path, SdfSpecType specType, bool inert);
1896 
1897  // Delete all the fields at or below the specified path. This does
1898  // not update the children field of the parent of \a path.
1899  bool _DeleteSpec(const SdfPath &path);
1900 
1901  // Inverse primitive for deleting a spec.
1902  void _PrimCreateSpec(const SdfPath &path, SdfSpecType specType, bool inert,
1903  bool useDelegate = true);
1904 
1905  // Inverse primitive for deleting a spec.
1906  void _PrimDeleteSpec(const SdfPath &path, bool inert,
1907  bool useDelegate = true);
1908 
1909  // Inverse primitive for setting time samples.
1910  template <class T>
1911  void _PrimSetTimeSample(const SdfPath& path, double time,
1912  const T& value,
1913  bool useDelegate = true);
1914 
1915  // Helper method for Traverse. Visits the children of \a path using the
1916  // specified \a ChildPolicy.
1917  template <typename ChildPolicy>
1918  void _TraverseChildren(const SdfPath &path, const TraversalFunction &func);
1919 
1920 private:
1921  SdfLayerHandle _self;
1922 
1923  // File format and arguments for this layer.
1924  SdfFileFormatConstPtr _fileFormat;
1925  FileFormatArguments _fileFormatArgs;
1926 
1927  // Cached reference to the _fileFormat's schema -- we need access to this to
1928  // be as fast as possible since we look at it on every SetField(), for
1929  // example.
1930  const SdfSchemaBase &_schema;
1931 
1932  // Registry of Sdf Identities
1933  mutable Sdf_IdentityRegistry _idRegistry;
1934 
1935  // The underlying SdfData which stores all the data in the layer.
1936  SdfAbstractDataRefPtr _data;
1937 
1938  // The state delegate for this layer.
1939  SdfLayerStateDelegateBaseRefPtr _stateDelegate;
1940 
1941  // Dispatcher used in layer initialization, letting waiters participate in
1942  // loading instead of just busy-waiting.
1943  WorkDispatcher _initDispatcher;
1944 
1945  // Atomic variable protecting layer initialization -- the interval between
1946  // adding a layer to the layer registry and finishing the process of
1947  // initializing its contents, at which point we can truly publish the layer
1948  // for consumption by concurrent threads. We add the layer to the registry
1949  // before initialization completes so that other threads can discover and
1950  // wait for it to finish initializing.
1951  std::atomic<bool> _initializationComplete;
1952 
1953  // This is an optional<bool> that is only set once initialization
1954  // is complete, before _initializationComplete is set.
1955  hboost::optional<bool> _initializationWasSuccessful;
1956 
1957  // remembers the last 'IsDirty' state.
1958  mutable bool _lastDirtyState;
1959 
1960  // Asset information for this layer.
1961  std::unique_ptr<Sdf_AssetInfo> _assetInfo;
1962 
1963  // Modification timestamp of the backing file asset when last read.
1964  mutable VtValue _assetModificationTime;
1965 
1966  // All external asset dependencies, with their modification timestamps, of
1967  // the layer when last read.
1968  mutable VtDictionary _externalAssetModificationTimes;
1969 
1970  // Mutable revision number for cache invalidation.
1971  mutable size_t _mutedLayersRevisionCache;
1972 
1973  // Cache of whether or not this layer is muted. Only valid if
1974  // _mutedLayersRevisionCache is up-to-date with the global revision number.
1975  mutable bool _isMutedCache;
1976 
1977  // Layer permission bits.
1978  bool _permissionToEdit;
1979  bool _permissionToSave;
1980 
1981  // Whether layer edits are validated.
1982  bool _validateAuthoring;
1983 
1984  // Layer hints as of the most recent save operation.
1985  mutable SdfLayerHints _hints;
1986 
1987  // Allow access to _ValidateAuthoring() and _IsInert().
1988  friend class SdfSpec;
1989  friend class SdfPropertySpec;
1990  friend class SdfAttributeSpec;
1991 
1992  friend class Sdf_ChangeManager;
1993 
1994  // Allow access to _CreateSpec and _DeleteSpec and _MoveSpec
1995  template <class ChildPolicy> friend class Sdf_ChildrenUtils;
1996 
1997  // Give the file format access to our data. Limit breaking encapsulation
1998  // to the base SdFileFormat class so we don't have to friend every
1999  // implementation here.
2000  friend class SdfFileFormat;
2001 
2002  // Give layer state delegates access to our data as well as to
2003  // the various _Prim functions.
2005 };
2006 
2008 
2009 #endif // PXR_USD_SDF_LAYER_H
static SDF_API SdfLayerRefPtr FindOrOpen(const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
SDF_API void ClearColorConfiguration()
std::vector< SdfNamespaceEditDetail > SdfNamespaceEditDetailVector
A sequence of SdfNamespaceEditDetail.
SDF_API bool HasDefaultPrim()
SDF_API void SetFieldDictValueByKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, const VtValue &value)
Definition: layer.h:94
T GetFieldAs(const SdfPath &path, const TfToken &fieldName, const T &defaultValue=T()) const
Definition: layer.h:682
SDF_API SdfAssetPath GetColorConfiguration() const
SDF_API void EraseTimeSample(const SdfPath &path, double time)
const std::vector< std::string > & GetExcluded() const
Definition: layer.h:1282
DetachedLayerRules & IncludeAll()
Include all layers in the detached layer set.
Definition: layer.h:1263
Result
Validity of an edit.
GT_API const UT_StringHolder filename
SDF_API void SetSubLayerPaths(const std::vector< std::string > &newPaths)
Sets the paths of the layer's sublayers.
SDF_API bool WriteDataFile(const std::string &filename)
SDF_API void RemoveInertSceneDescription()
SDF_API bool InsertRootPrim(const SdfPrimSpecHandle &prim, int index=-1)
SDF_API bool HasEndTimeCode() const
Returns true if the layer has an endTimeCode opinion.
SDF_API void SetComment(const std::string &comment)
Sets the comment string for this layer.
SDF_API VtDictionary GetCustomLayerData() const
SDF_API void SetFramePrecision(int framePrecision)
Sets the layer's frame precision.
SDF_API std::string ComputeAbsolutePath(const std::string &assetPath) const
SDF_API std::set< std::string > GetExternalReferences() const
SDF_API void EraseFieldDictValueByKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath)
bool HasFieldDictKey(const SdfPath &path, const TfToken &name, const TfToken &keyPath, T *value) const
Definition: layer.h:659
SDF_API void RemovePropertyIfHasOnlyRequiredFields(SdfPropertySpecHandle prop)
SDF_API void SetDocumentation(const std::string &documentation)
Sets the documentation string for this layer.
SDF_API void ClearFramesPerSecond()
Clear the framesPerSecond opinion.
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_PTRS(SdfFileFormat)
static SDF_API SdfLayerRefPtr New(const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
static SDF_API bool ReloadLayers(const std::set< SdfLayerHandle > &layers, bool force=false)
SDF_API bool IsMuted() const
Returns true if the current layer is muted.
SDF_API void SetStartTimeCode(double startTimecode)
Sets the layer's start timeCode.
SDF_API bool ExportToString(std::string *result) const
GT_API const UT_StringHolder time
SDF_API const VtValue & GetAssetInfo() const
static SDF_API bool SplitIdentifier(const std::string &identifier, std::string *layerPath, FileFormatArguments *arguments)
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLfloat * value
Definition: glcorearb.h:824
SDF_API bool HasStartTimeCode() const
Returns true if the layer has a startTimeCode opinion.
static SDF_API SdfLayerRefPtr FindOrOpenRelativeToLayer(const SdfLayerHandle &anchor, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
SDF_API const std::string & GetAssetName() const
Returns the asset name associated with this layer.
SDF_API void SetDefaultPrim(const TfToken &name)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
std::map< std::string, std::string > FileFormatArguments
Definition: layer.h:120
SDF_API bool QueryTimeSample(const SdfPath &path, double time, VtValue *value=NULL) const
SDF_API void ClearSessionOwner()
SDF_API SdfNameOrderProxy GetRootPrimOrder() const
std::type_info const & GetFieldTypeid(const SdfPath &path, const TfToken &name) const
Definition: layer.h:635
SDF_API bool HasSpec(const SdfPath &path) const
Return whether a spec exists at path.
SDF_API SdfAttributeSpecHandle GetAttributeAtPath(const SdfPath &path)
SDF_API void RemoveFromRootPrimOrderByIndex(int index)
Removes a root prim name from the root prim order by index.
SDF_API SdfRelationshipSpecHandle GetRelationshipAtPath(const SdfPath &path)
SDF_API void SetPermissionToEdit(bool allow)
Sets permission to edit.
SDF_API void Traverse(const SdfPath &path, const TraversalFunction &func)
TF_API const TfNullPtrType TfNullPtr
TF_DECLARE_WEAK_AND_REF_PTRS(SdfLayerStateDelegateBase)
Definition: spec.h:49
SDF_API bool HasSessionOwner() const
Returns true if the layer has a session owner opinion.
friend class Sdf_ChangeManager
Definition: layer.h:1992
SDF_API SdfPrimSpecHandle GetPseudoRoot() const
SDF_API bool PermissionToEdit() const
std::set< SdfHandleTo< SdfLayer >::Handle > SdfLayerHandleSet
static SDF_API SdfLayerRefPtr CreateAnonymous(const std::string &tag=std::string(), const FileFormatArguments &args=FileFormatArguments())
SDF_API void SetSubLayerOffset(const SdfLayerOffset &offset, int index)
Sets the layer offset for the subLayer path at the given index.
SDF_API void ScheduleRemoveIfInert(const SdfSpec &spec)
**But if you need a result
Definition: thread.h:613
std::function< void(const SdfPath &)> TraversalFunction
Definition: layer.h:768
static SDF_API std::string CreateIdentifier(const std::string &layerPath, const FileFormatArguments &arguments)
Joins the given layer path and arguments into an identifier.
SDF_API std::string GetDocumentation() const
SDF_API void SetPermissionToSave(bool allow)
Sets permission to save.
SDF_API bool Apply(const SdfBatchNamespaceEdit &)
SDF_API bool Import(const std::string &layerPath)
SDF_API const std::string & GetRepositoryPath() const
SDF_API SdfPrimSpecHandle GetPrimAtPath(const SdfPath &path)
SDF_API void SetTimeCodesPerSecond(double timeCodesPerSecond)
Sets the layer's timeCodes per second.
static SDF_API std::set< std::string > GetMutedLayers()
Returns the set of muted layer paths.
SDF_API std::set< double > ListTimeSamplesForPath(const SdfPath &path) const
SDF_API SdfLayerOffset GetSubLayerOffset(int index) const
Returns the layer offset for the subLayer path at the given index.
SDF_API double GetTimeCodesPerSecond() const
SDF_API void SetColorConfiguration(const SdfAssetPath &colorConfiguration)
Sets the color configuration asset-path for this layer.
SDF_API std::string GetSessionOwner() const
static SDF_API bool IsIncludedByDetachedLayerRules(const std::string &identifier)
SDF_API SdfSpecType GetSpecType(const SdfPath &path) const
SDF_API void SetEndTimeCode(double endTimeCode)
Sets the layer's end timeCode.
SDF_API bool Reload(bool force=false)
SDF_API double GetStartTimeCode() const
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
SDF_API size_t GetNumSubLayerPaths() const
Returns the number of sublayer paths (and offsets).
SDF_API SdfLayerOffsetVector GetSubLayerOffsets() const
Returns the layer offsets for all the subLayer paths.
SDF_API const SdfFileFormatConstPtr & GetFileFormat() const
Returns the file format used by this layer.
SDF_API void ClearOwner()
Clear the owner opinion.
SDF_API const FileFormatArguments & GetFileFormatArguments() const
SDF_API SdfDataRefPtr GetMetadata() const
Returns the data from the absolute root path of this layer.
SDF_API void RemoveRootPrim(const SdfPrimSpecHandle &prim)
Remove a root prim.
static SDF_API SdfLayerRefPtr OpenAsAnonymous(const std::string &layerPath, bool metadataOnly=false, const std::string &tag=std::string())
SDF_API void ClearFramePrecision()
Clear the framePrecision opinion.
SDF_API void SetStateDelegate(const SdfLayerStateDelegateBaseRefPtr &delegate)
SDF_API void SetColorManagementSystem(const TfToken &cms)
std::vector< SdfLayerOffset > SdfLayerOffsetVector
Definition: layerOffset.h:155
Definition: token.h:87
SDF_API bool HasField(const SdfPath &path, const TfToken &fieldName, VtValue *value=NULL) const
SDF_API void SetSessionOwner(const std::string &owner)
GLintptr offset
Definition: glcorearb.h:665
SDF_API void SetRootPrims(const SdfPrimSpecHandleVector &rootPrims)
SDF_API void SetCustomLayerData(const VtDictionary &value)
Sets the CustomLayerData dictionary associated with this layer.
SDF_API void EraseField(const SdfPath &path, const TfToken &fieldName)
Remove the field at path and fieldName, if one exists.
SDF_API std::set< std::string > GetCompositionAssetDependencies() const
SDF_API void ClearEndTimeCode()
Clear the endTimeCode opinion.
SDF_API bool HasCustomLayerData() const
Returns true if CustomLayerData is authored on the layer.
SDF_API bool UpdateExternalReference(const std::string &oldAssetPath, const std::string &newAssetPath=std::string())
SDF_API double GetFramesPerSecond() const
SDF_API void ClearDefaultPrim()
SDF_API void Clear()
static SDF_API std::string GetDisplayNameFromIdentifier(const std::string &identifier)
SDF_API VtValue GetFieldDictValueByKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath) const
SDF_API bool ImportFromString(const std::string &string)
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
SDF_API std::set< std::string > GetExternalAssetDependencies() const
const std::vector< std::string > & GetIncluded() const
Definition: layer.h:1281
GLint GLuint mask
Definition: glcorearb.h:124
SDF_API bool HasFramesPerSecond() const
Returns true if the layer has a frames per second opinion.
SdfPrimSpecView RootPrimsView
Returns a vector of the layer's root prims.
Definition: layer.h:1067
SDF_API void SetRootPrimOrder(const std::vector< TfToken > &names)
SDF_API bool Export(const std::string &filename, const std::string &comment=std::string(), const FileFormatArguments &args=FileFormatArguments()) const
SDF_API double GetEndTimeCode() const
SDF_API SdfLayerStateDelegateBasePtr GetStateDelegate() const
SDF_API DetachedLayerRules & Include(const std::vector< std::string > &patterns)
SDF_API void SetHasOwnedSubLayers(bool)
Sets whether the layer's sublayers are expected to have owners.
SDF_API const std::string & GetRealPath() const
SDF_API void ClearTimeCodesPerSecond()
Clear the timeCodesPerSecond opinion.
SDF_API void RemoveFromRootPrimOrder(const TfToken &name)
Removes a root prim name from the root prim order.
SDF_API TfToken GetColorManagementSystem() const
SDF_API bool HasTimeCodesPerSecond() const
Returns true if the layer has a timeCodesPerSecond opinion.
GLuint const GLchar * name
Definition: glcorearb.h:786
SDF_API void ClearExpressionVariables()
Clears the expression variables dictionary authored on this layer.
void SetFieldDictValueByKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, const T &val)
Definition: layer.h:735
Definition: path.h:291
SdfLayer & operator=(const SdfLayer &)=delete
bool IncludedAll() const
Definition: layer.h:1280
SDF_API bool StreamsData() const
SDF_API DetachedLayerRules & Exclude(const std::vector< std::string > &patterns)
SDF_API bool HasFieldDictKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, VtValue *value=NULL) const
SDF_API bool HasExpressionVariables() const
Returns true if expression variables are authored on this layer.
SDF_API bool GetBracketingTimeSamples(double time, double *tLower, double *tUpper)
SDF_API void SetFramesPerSecond(double framesPerSecond)
Sets the layer's frames per second.
SDF_API std::string GetDisplayName() const
SDF_API void UpdateAssetInfo()
SDF_API bool IsIncluded(const std::string &identifier) const
SDF_API bool UpdateCompositionAssetDependency(const std::string &oldAssetPath, const std::string &newAssetPath=std::string())
SDF_API const ArResolvedPath & GetResolvedPath() const
SdfLayer(const SdfLayer &)=delete
Noncopyable.
SDF_API SdfNamespaceEditDetail::Result CanApply(const SdfBatchNamespaceEdit &, SdfNamespaceEditDetailVector *details=NULL) const
static SDF_API void SetDetachedLayerRules(const DetachedLayerRules &mask)
SDF_API void InsertSubLayerPath(const std::string &path, int index=-1)
static SDF_API SdfLayerHandle FindRelativeToLayer(const SdfLayerHandle &anchor, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
SDF_API SdfSpecHandle GetObjectAtPath(const SdfPath &path)
#define SDF_API
Definition: api.h:40
SDF_API void SetIdentifier(const std::string &identifier)
SDF_API void SetExpressionVariables(const VtDictionary &expressionVars)
Sets the expression variables dictionary for this layer.
SDF_API bool IsAnonymous() const
Returns true if this layer is an anonymous layer.
bool HasField(const SdfPath &path, const TfToken &name, T *value) const
Definition: layer.h:615
GLenum func
Definition: glcorearb.h:783
SDF_API std::string GetFileExtension() const
SDF_API void InsertInRootPrimOrder(const TfToken &name, int index=-1)
SDF_API void RemoveSubLayerPath(int index)
Removes sublayer path at the given index.
SDF_API void SetField(const SdfPath &path, const TfToken &fieldName, const VtValue &value)
Set the value of the given path and fieldName.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
SDF_API bool GetBracketingTimeSamplesForPath(const SdfPath &path, double time, double *tLower, double *tUpper)
SDF_API void TransferContent(const SdfLayerHandle &layer)
SIM_API const UT_StringHolder force
void SetField(const SdfPath &path, const TfToken &fieldName, const T &val)
Set the value of the given path and fieldName.
Definition: layer.h:706
bool QueryTimeSample(const SdfPath &path, double time, T *data) const
Definition: layer.h:1534
SDF_API bool HasColorManagementSystem() const
SDF_API VtDictionary GetExpressionVariables() const
SdfSpecType
Definition: types.h:90
SDF_API std::string GetOwner() const
Returns the layer's owner.
SDF_API void SetMuted(bool muted)
SDF_API void ClearCustomLayerData()
Clears out the CustomLayerData dictionary associated with this layer.
SDF_API bool PermissionToSave() const
virtual SDF_API ~SdfLayer()
Destructor.
SDF_API bool HasColorConfiguration() const
GLuint index
Definition: glcorearb.h:786
SDF_API bool HasOwner() const
Returns true if the layer has an owner opinion.
SDF_API void SetTimeSample(const SdfPath &path, double time, const VtValue &value)
GLuint GLfloat * val
Definition: glcorearb.h:1608
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDF_API bool IsDetached() const
SDF_API bool HasFramePrecision() const
Returns true if the layer has a frames precision opinion.
**If you just want to fire and args
Definition: thread.h:609
SDF_API int GetFramePrecision() const
Returns the layer's frame precision.
SDF_API void SetOwner(const std::string &owner)
Sets the layer's owner.
SDF_API const std::string & GetIdentifier() const
Returns the layer identifier.
SDF_API bool GetHasOwnedSubLayers() const
Returns true if the layer's sublayers are expected to have owners.
static SDF_API void RemoveFromMutedLayers(const std::string &mutedPath)
Remove the specified path from the muted layers set.
SDF_API RootPrimsView GetRootPrims() const
Returns a vector of the layer's root prims.
static SDF_API void AddToMutedLayers(const std::string &mutedPath)
Add the specified path to the muted layers set.
Definition: core.h:1131
SDF_API TfToken GetDefaultPrim() const
SDF_API std::vector< TfToken > ListFields(const SdfPath &path) const
Return the names of all the fields that are set at path.
SDF_API SdfPropertySpecHandle GetPropertyAtPath(const SdfPath &path)
static SDF_API void DumpLayerInfo()
SDF_API size_t GetNumTimeSamplesForPath(const SdfPath &path) const
SDF_API const std::string & GetVersion() const
SDF_API SdfSubLayerProxy GetSubLayerPaths() const
SDF_API void RemovePrimIfInert(SdfPrimSpecHandle prim)
static SDF_API const DetachedLayerRules & GetDetachedLayerRules()
Returns the current rules for the detached layer set.
static SDF_API SdfLayerRefPtr CreateNew(const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
SDF_API SdfLayerHints GetHints() const
static SDF_API SdfLayerHandleSet GetLoadedLayers()
Returns handles for all layers currently held by the layer registry.
SDF_API const SdfSchemaBase & GetSchema() const
SDF_API bool IsDirty() const
SDF_API void ApplyRootPrimOrder(std::vector< TfToken > *vec) const
SDF_API void ClearStartTimeCode()
Clear the startTimeCode opinion.
SDF_API void ClearColorManagementSystem()
Definition: value.h:167
SDF_API std::string GetComment() const
SDF_API bool Save(bool force=false) const
SDF_API VtValue GetField(const SdfPath &path, const TfToken &fieldName) const
static SDF_API bool IsAnonymousLayerIdentifier(const std::string &identifier)
Definition: format.h:895
SDF_API std::set< double > ListAllTimeSamples() const
SDF_API bool IsEmpty() const
Returns whether this layer has no significant data.
static SDF_API SdfLayerHandle Find(const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
void SetTimeSample(const SdfPath &path, double time, const T &value)
Definition: layer.h:1560