HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stage.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_STAGE_H
25 #define PXR_USD_USD_STAGE_H
26 
27 /// \file usd/stage.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.h"
31 #include "pxr/usd/usd/common.h"
32 #include "pxr/usd/usd/editTarget.h"
37 #include "pxr/usd/usd/primFlags.h"
38 
40 #include "pxr/base/tf/hashmap.h"
41 #include "pxr/base/tf/weakBase.h"
42 
44 #include "pxr/usd/sdf/notice.h"
45 #include "pxr/usd/sdf/path.h"
46 #include "pxr/usd/sdf/types.h"
47 #include "pxr/usd/pcp/cache.h"
48 #include "pxr/base/vt/value.h"
50 
51 #include <hboost/optional.hpp>
52 
53 #include <tbb/concurrent_vector.h>
54 #include <tbb/concurrent_unordered_set.h>
55 #include <tbb/spin_rw_mutex.h>
56 
57 #include <functional>
58 #include <string>
59 #include <memory>
60 #include <unordered_map>
61 #include <utility>
62 
64 
65 
66 class ArResolverContext;
67 class GfInterval;
69 class Usd_ClipCache;
70 class Usd_InstanceCache;
71 class Usd_InstanceChanges;
72 class Usd_InterpolatorBase;
73 class UsdResolveInfo;
74 class Usd_Resolver;
75 class UsdPrim;
76 class UsdPrimRange;
77 
79 
80 /// \class UsdStage
81 ///
82 /// The outermost container for scene description, which owns and presents
83 /// composed prims as a scenegraph, following the composition recipe
84 /// recursively described in its associated "root layer".
85 ///
86 /// USD derives its persistent-storage scalability by combining and reusing
87 /// simple compositions into richer aggregates using referencing and layering
88 /// with sparse overrides. Ultimately, every composition (i.e. "scene") is
89 /// identifiable by its root layer, i.e. the <tt>.usd</tt> file, and a scene
90 /// is instantiated in an application on a UsdStage that presents a composed
91 /// view of the scene's root layer. Each simple composition referenced into
92 /// a larger composition could be presented on its own UsdStage, at the same
93 /// (or not) time that it is participating in the larger composition on its
94 /// own UsdStage; all of the underlying layers will be shared by the two
95 /// stages, while each maintains its own scenegraph of composed prims.
96 ///
97 /// A UsdStage has sole ownership over the UsdPrim 's with which it is populated,
98 /// and retains \em shared ownership (with other stages and direct clients of
99 /// SdfLayer's, via the Sdf_LayerRegistry that underlies all SdfLayer creation
100 /// methods) of layers. It provides roughly five categories of API that
101 /// address different aspects of scene management:
102 ///
103 /// - \ref Usd_lifetimeManagement "Stage lifetime management" methods for
104 /// constructing and initially populating a UsdStage from an existing layer
105 /// file, or one that will be created as a result, in memory or on the
106 /// filesystem.
107 /// - \ref Usd_workingSetManagement "Load/unload working set management" methods
108 /// that allow you to specify which \ref Usd_Payloads "payloads" should be
109 /// included and excluded from the stage's composition.
110 /// - \ref Usd_variantManagement "Variant management" methods to manage
111 /// policy for which variant to use when composing prims that provide
112 /// a named variant set, but do not specify a selection.
113 /// - \ref Usd_primManagement "Prim access, creation, and mutation" methods
114 /// that allow you to find, create, or remove a prim identified by a path on
115 /// the stage. This group also provides methods for efficiently traversing the
116 /// prims on the stage.
117 /// - \ref Usd_layerManagement "Layers and EditTargets" methods provide access
118 /// to the layers in the stage's <em>root LayerStack</em> (i.e. the root layer
119 /// and all of its recursive sublayers), and the ability to set a UsdEditTarget
120 /// into which all subsequent mutations to objects associated with the stage
121 /// (e.g. prims, properties, etc) will go.
122 /// - \ref Usd_stageSerialization "Serialization" methods for "flattening" a
123 /// composition (to varying degrees), and exporting a completely flattened
124 /// view of the stage to a string or file. These methods can be very useful
125 /// for targetted asset optimization and debugging, though care should be
126 /// exercized with large scenes, as flattening defeats some of the benefits of
127 /// referenced scene description, and may produce very large results,
128 /// especially in file formats that do not support data de-duplication, like
129 /// the usda ASCII format!
130 ///
131 /// \section Usd_SessionLayer Stage Session Layers
132 ///
133 /// Each UsdStage can possess an optional "session layer". The purpose of
134 /// a session layer is to hold ephemeral edits that modify a UsdStage's contents
135 /// or behavior in a way that is useful to the client, but should not be
136 /// considered as permanent mutations to be recorded upon export. A very
137 /// common use of session layers is to make variant selections, to pick a
138 /// specific LOD or shading variation, for example. The session layer is
139 /// also frequently used to perform interactive vising/invsning of geometry
140 /// and assets in the scene. A session layer, if present, contributes to a
141 /// UsdStage's identity, for purposes of stage-caching, etc.
142 ///
143 class UsdStage : public TfRefBase, public TfWeakBase {
144 public:
145 
146  // --------------------------------------------------------------------- //
147  /// \anchor Usd_lifetimeManagement
148  /// \name Lifetime Management
149  /// @{
150  // --------------------------------------------------------------------- //
151 
152  /// \enum InitialLoadSet
153  ///
154  /// Specifies the initial set of prims to load when opening a UsdStage.
155  ///
157  {
158  LoadAll, ///< Load all loadable prims
159  LoadNone ///< Load no loadable prims
160  };
161 
162  /// Create a new stage with root layer \p identifier, destroying
163  /// potentially existing files with that identifier; it is considered an
164  /// error if an existing, open layer is present with this identifier.
165  ///
166  /// \sa SdfLayer::CreateNew()
167  ///
168  /// Invoking an overload that does not take a \p sessionLayer argument will
169  /// create a stage with an anonymous in-memory session layer. To create a
170  /// stage without a session layer, pass TfNullPtr (or None in python) as the
171  /// \p sessionLayer argument.
172  //
173  /// The initial set of prims to load on the stage can be specified
174  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
175  ///
176  /// Note that the \p pathResolverContext passed here will apply to all path
177  /// resolutions for this stage, regardless of what other context may be
178  /// bound at resolve time. If no context is passed in here, Usd will create
179  /// one by calling \sa ArResolver::CreateDefaultContextForAsset with the
180  /// root layer's repository path if the layer has one, otherwise its real
181  /// path.
182  USD_API
183  static UsdStageRefPtr
184  CreateNew(const std::string& identifier,
185  InitialLoadSet load = LoadAll);
186  /// \overload
187  USD_API
188  static UsdStageRefPtr
189  CreateNew(const std::string& identifier,
190  const SdfLayerHandle& sessionLayer,
191  InitialLoadSet load = LoadAll);
192  /// \overload
193  USD_API
194  static UsdStageRefPtr
195  CreateNew(const std::string& identifier,
196  const SdfLayerHandle& sessionLayer,
197  const ArResolverContext& pathResolverContext,
198  InitialLoadSet load = LoadAll);
199  /// \overload
200  USD_API
201  static UsdStageRefPtr
202  CreateNew(const std::string& identifier,
203  const ArResolverContext& pathResolverContext,
204  InitialLoadSet load = LoadAll);
205 
206  /// Creates a new stage only in memory, analogous to creating an
207  /// anonymous SdfLayer.
208  ///
209  /// Note that the \p pathResolverContext passed here will apply to all path
210  /// resolutions for this stage, regardless of what other context may be
211  /// bound at resolve time. If no context is passed in here, Usd will create
212  /// one by calling \sa ArResolver::CreateDefaultContext.
213  ///
214  /// The initial set of prims to load on the stage can be specified
215  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
216  ///
217  /// Invoking an overload that does not take a \p sessionLayer argument will
218  /// create a stage with an anonymous in-memory session layer. To create a
219  /// stage without a session layer, pass TfNullPtr (or None in python) as the
220  /// \p sessionLayer argument.
221  USD_API
222  static UsdStageRefPtr
224  /// \overload
225  USD_API
226  static UsdStageRefPtr
227  CreateInMemory(const std::string& identifier,
228  InitialLoadSet load = LoadAll);
229  /// \overload
230  USD_API
231  static UsdStageRefPtr
232  CreateInMemory(const std::string& identifier,
233  const ArResolverContext& pathResolverContext,
234  InitialLoadSet load = LoadAll);
235  /// \overload
236  USD_API
237  static UsdStageRefPtr
238  CreateInMemory(const std::string& identifier,
239  const SdfLayerHandle &sessionLayer,
240  InitialLoadSet load = LoadAll);
241  /// \overload
242  USD_API
243  static UsdStageRefPtr
244  CreateInMemory(const std::string& identifier,
245  const SdfLayerHandle &sessionLayer,
246  const ArResolverContext& pathResolverContext,
247  InitialLoadSet load = LoadAll);
248 
249 
250  /// Attempt to find a matching existing stage in a cache if
251  /// UsdStageCacheContext objects exist on the stack. Failing that, create a
252  /// new stage and recursively compose prims defined within and referenced by
253  /// the layer at \p filePath, which must already exist.
254  ///
255  /// The initial set of prims to load on the stage can be specified
256  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
257  ///
258  /// Note that the \p pathResolverContext passed here will apply to all path
259  /// resolutions for this stage, regardless of what other context may be
260  /// bound at resolve time. If no context is passed in here, Usd will create
261  /// one by calling \sa ArResolver::CreateDefaultContextForAsset with the
262  /// root layer's repository path if the layer has one, otherwise its real
263  /// path.
264  USD_API
265  static UsdStageRefPtr
266  Open(const std::string& filePath, InitialLoadSet load = LoadAll);
267  /// \overload
268  USD_API
269  static UsdStageRefPtr
270  Open(const std::string& filePath,
271  const ArResolverContext& pathResolverContext,
272  InitialLoadSet load = LoadAll);
273 
274  /// Create a new stage and recursively compose prims defined within and
275  /// referenced by the layer at \p filePath which must already exist, subject
276  /// to \p mask.
277  ///
278  /// These OpenMasked() methods do not automatically consult or populate
279  /// UsdStageCache s.
280  ///
281  /// The initial set of prims to load on the stage can be specified
282  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
283  ///
284  /// Note that the \p pathResolverContext passed here will apply to all path
285  /// resolutions for this stage, regardless of what other context may be
286  /// bound at resolve time. If no context is passed in here, Usd will create
287  /// one by calling \sa ArResolver::CreateDefaultContextForAsset with the
288  /// root layer's repository path if the layer has one, otherwise its real
289  /// path.
290  USD_API
291  static UsdStageRefPtr
292  OpenMasked(const std::string &filePath,
294  InitialLoadSet load = LoadAll);
295  /// \overload
296  USD_API
297  static UsdStageRefPtr
298  OpenMasked(const std::string &filePath,
299  const ArResolverContext &pathResolverContext,
301  InitialLoadSet load = LoadAll);
302 
303  /// Open a stage rooted at \p rootLayer.
304  ///
305  /// Attempt to find a stage that matches the passed arguments in a
306  /// UsdStageCache if UsdStageCacheContext objects exist on the calling
307  /// stack. If a matching stage is found, return that stage. Otherwise,
308  /// create a new stage rooted at \p rootLayer.
309  ///
310  /// Invoking an overload that does not take a \p sessionLayer argument will
311  /// create a stage with an anonymous in-memory session layer. To create a
312  /// stage without a session layer, pass TfNullPtr (or None in python) as the
313  /// \p sessionLayer argument.
314  ///
315  /// The initial set of prims to load on the stage can be specified
316  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
317  ///
318  /// Note that the \p pathResolverContext passed here will apply to all path
319  /// resolutions for this stage, regardless of what other context may be
320  /// bound at resolve time. If no context is passed in here, Usd will create
321  /// one by calling \sa ArResolver::CreateDefaultContextForAsset with the
322  /// root layer's repository path if the layer has one, otherwise its real
323  /// path.
324  ///
325  /// When searching for a matching stage in bound UsdStageCache s, only the
326  /// provided arguments matter for cache lookup. For example, if only a root
327  /// layer (or a root layer file path) is provided, the first stage found in
328  /// any cache that has that root layer is returned. So, for example if you
329  /// require that the stage have no session layer, you must explicitly
330  /// specify TfNullPtr (or None in python) for the sessionLayer argument.
331  USD_API
332  static UsdStageRefPtr
333  Open(const SdfLayerHandle& rootLayer,
334  InitialLoadSet load=LoadAll);
335  /// \overload
336  USD_API
337  static UsdStageRefPtr
338  Open(const SdfLayerHandle& rootLayer,
339  const SdfLayerHandle& sessionLayer,
340  InitialLoadSet load=LoadAll);
341  /// \overload
342  USD_API
343  static UsdStageRefPtr
344  Open(const SdfLayerHandle& rootLayer,
345  const ArResolverContext& pathResolverContext,
346  InitialLoadSet load=LoadAll);
347  /// \overload
348  USD_API
349  static UsdStageRefPtr
350  Open(const SdfLayerHandle& rootLayer,
351  const SdfLayerHandle& sessionLayer,
352  const ArResolverContext& pathResolverContext,
353  InitialLoadSet load=LoadAll);
354 
355  /// Open a stage rooted at \p rootLayer and with limited population subject
356  /// to \p mask.
357  ///
358  /// These OpenMasked() methods do not automatically consult or populate
359  /// UsdStageCache s.
360  ///
361  /// Invoking an overload that does not take a \p sessionLayer argument will
362  /// create a stage with an anonymous in-memory session layer. To create a
363  /// stage without a session layer, pass TfNullPtr (or None in python) as the
364  /// \p sessionLayer argument.
365  ///
366  /// The initial set of prims to load on the stage can be specified
367  /// using the \p load parameter. \sa UsdStage::InitialLoadSet.
368  ///
369  /// Note that the \p pathResolverContext passed here will apply to all path
370  /// resolutions for this stage, regardless of what other context may be
371  /// bound at resolve time. If no context is passed in here, Usd will create
372  /// one by calling \sa ArResolver::CreateDefaultContextForAsset with the
373  /// root layer's repository path if the layer has one, otherwise its real
374  /// path.
375  USD_API
376  static UsdStageRefPtr
377  OpenMasked(const SdfLayerHandle& rootLayer,
379  InitialLoadSet load=LoadAll);
380  /// \overload
381  USD_API
382  static UsdStageRefPtr
383  OpenMasked(const SdfLayerHandle& rootLayer,
384  const SdfLayerHandle& sessionLayer,
386  InitialLoadSet load=LoadAll);
387  /// \overload
388  USD_API
389  static UsdStageRefPtr
390  OpenMasked(const SdfLayerHandle& rootLayer,
391  const ArResolverContext& pathResolverContext,
393  InitialLoadSet load=LoadAll);
394  /// \overload
395  USD_API
396  static UsdStageRefPtr
397  OpenMasked(const SdfLayerHandle& rootLayer,
398  const SdfLayerHandle& sessionLayer,
399  const ArResolverContext& pathResolverContext,
401  InitialLoadSet load=LoadAll);
402 
403  USD_API
404  virtual ~UsdStage();
405 
406  /// Calls SdfLayer::Reload on all layers contributing to this stage,
407  /// except session layers and sublayers of session layers.
408  ///
409  /// This includes non-session sublayers, references and payloads.
410  /// Note that reloading anonymous layers clears their content, so
411  /// invoking Reload() on a stage constructed via CreateInMemory()
412  /// will clear its root layer.
413  ///
414  /// \note This method is considered a mutation, which has potentially
415  /// global effect! Unlike the various Load() methods whose actions
416  /// affect only **this stage**, Reload() may cause layers to change their
417  /// contents, and because layers are global resources shared by
418  /// potentially many Stages, calling Reload() on one stage may result in
419  /// a mutation to any number of stages. In general, unless you are
420  /// highly confident your stage is the only consumer of its layers, you
421  /// should only call Reload() when you are assured no other threads may
422  /// be reading from any Stages.
423  USD_API
424  void Reload();
425 
426  /// Indicates whether the specified file is supported by UsdStage.
427  ///
428  /// This function is a cheap way to determine whether a
429  /// file might be open-able with UsdStage::Open. It is
430  /// purely based on the given \p filePath and does not
431  /// open the file or perform analysis on the contents.
432  /// As such, UsdStage::Open may still fail even if this
433  /// function returns true.
434  USD_API
435  static bool
436  IsSupportedFile(const std::string& filePath);
437 
438  /// @}
439 
440  // --------------------------------------------------------------------- //
441  /// \anchor Usd_layerSerialization
442  /// \name Layer Serialization
443  ///
444  /// Functions for saving changes to layers that contribute opinions to
445  /// this stage. Layers may also be saved by calling SdfLayer::Save or
446  /// exported to a new file by calling SdfLayer::Export.
447  ///
448  /// @{
449 
450  /// Calls SdfLayer::Save on all dirty layers contributing to this stage
451  /// except session layers and sublayers of session layers.
452  ///
453  /// This function will emit a warning and skip each dirty anonymous
454  /// layer it encounters, since anonymous layers cannot be saved with
455  /// SdfLayer::Save. These layers must be manually exported by calling
456  /// SdfLayer::Export.
457  USD_API
458  void Save();
459 
460  /// Calls SdfLayer::Save on all dirty session layers and sublayers of
461  /// session layers contributing to this stage.
462  ///
463  /// This function will emit a warning and skip each dirty anonymous
464  /// layer it encounters, since anonymous layers cannot be saved with
465  /// SdfLayer::Save. These layers must be manually exported by calling
466  /// SdfLayer::Export.
467  USD_API
468  void SaveSessionLayers();
469 
470  /// @}
471 
472  // --------------------------------------------------------------------- //
473  /// \anchor Usd_variantManagement
474  /// \name Variant Management
475  ///
476  /// These methods provide control over the policy to use when composing
477  /// prims that specify a variant set but do not specify a selection.
478  ///
479  /// The first is to declare a list of preferences in plugInfo.json
480  /// metadata on a plugin using this structure:
481  ///
482  /// \code{.json}
483  /// "UsdVariantFallbacks": { # top level key
484  /// "shadingComplexity": [ # example variant set
485  /// "full", # example fallback #1
486  /// "light" # example fallback #2
487  /// ]
488  /// },
489  /// \endcode
490  ///
491  /// This example ensures that we will get the "full" shadingComplexity
492  /// for any prim with a shadingComplexity VariantSet that doesn't
493  /// otherwise specify a selection, \em and has a "full" variant; if its
494  /// shadingComplexity does not have a "full" variant, but \em does have
495  /// a "light" variant, then the selection will be "light". In other
496  /// words, the entries in the "shadingComplexity" list in the plugInfo.json
497  /// represent a priority-ordered list of fallback selections.
498  ///
499  /// The plugin metadata is discovered and applied before the first
500  /// UsdStage is constructed in a given process. It can be defined
501  /// in any plugin. However, if multiple plugins express contrary
502  /// lists for the same named variant set, the result is undefined.
503  ///
504  /// The plugin metadata approach is useful for ensuring that sensible
505  /// default behavior applies across a pipeline without requiring
506  /// every script and binary to explicitly configure every VariantSet
507  /// that subscribes to fallback in the pipeline.
508  /// There may be times when you want to override this behavior in a
509  /// particular script -- for example, a pipeline script that knows
510  /// it wants to entirely ignore shading in order to minimize
511  /// processing time -- which motivates the second approach.
512  ///
513  /// SetGlobalVariantFallbacks() provides a way to override, for
514  /// the entire process, which fallbacks to use in subsequently
515  /// constructed UsdStage instances.
516  ///
517  /// @{
518 
519  /// Get the global variant fallback preferences used in new UsdStages.
520  USD_API
522 
523  /// Set the global variant fallback preferences used in new
524  /// UsdStages. This overrides any fallbacks configured in plugin
525  /// metadata, and only affects stages created after this call.
526  ///
527  /// \note This does not affect existing UsdStages.
528  USD_API
529  static void
531 
532  /// @}
533 
534  // --------------------------------------------------------------------- //
535  /// \anchor Usd_workingSetManagement
536  /// \name Working Set Management
537  ///
538  /// The following rules apply to all Load/Unload methods:
539  ///
540  /// - Loading an already loaded prim is legal, though may result in
541  /// some recomposition cost. Similarly, unloading an unloaded prim
542  /// is legal.
543  /// - Specifying a path that does not target a prim is legal as long it
544  /// has an ancestor present in the scene graph (other than the
545  /// absolute root). If the given path has no such ancestor, it is an
546  /// error.
547  /// - Specifying a path to an inactive prim is an error.
548  /// - Specifying a path to a master prim or a prim within a master is an
549  /// error.
550  ///
551  /// If an instance prim (or a path identifying a prim descendant to an
552  /// instance) is encountered during a Load/Unload operation, these functions
553  /// may cause instancing to change on the stage in order to ensure that no
554  /// other instances are affected. The load/unload rules that affect a given
555  /// prim hierarchy are considered when determining which prims can be
556  /// instanced together. Instance sharing occurs when different instances
557  /// have equivalent load rules.
558  ///
559  /// The GetLoadRules() and SetLoadRules() provide direct low-level access to
560  /// the UsdStageLoadRules that govern payload inclusion on a stage.
561  ///
562  /// @{
563  // --------------------------------------------------------------------- //
564 
565  /// Modify this stage's load rules to load the prim at \p path, its
566  /// ancestors, and all of its descendants if \p policy is
567  /// UsdLoadWithDescendants. If \p policy is UsdLoadWithoutDescendants, then
568  /// payloads on descendant prims are not loaded.
569  ///
570  /// See \ref Usd_workingSetManagement "Working Set Management" for more
571  /// information.
572  USD_API
575 
576  /// Modify this stage's load rules to unload the prim and its descendants
577  /// specified by \p path.
578  ///
579  /// See \ref Usd_workingSetManagement "Working Set Management" for more
580  /// information.
581  USD_API
583 
584  /// Unload and load the given path sets. The effect is as if the unload set
585  /// were processed first followed by the load set.
586  ///
587  /// This is equivalent to calling UsdStage::Unload for each item in the
588  /// unloadSet followed by UsdStage::Load for each item in the loadSet,
589  /// however this method is more efficient as all operations are committed in
590  /// a single batch. The \p policy argument is described in the
591  /// documentation for Load().
592  ///
593  /// See \ref Usd_workingSetManagement "Working Set Management" for more
594  /// information.
595  USD_API
596  void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet,
598 
599  /// Returns a set of all loaded paths.
600  ///
601  /// The paths returned are both those that have been explicitly loaded and
602  /// those that were loaded as a result of dependencies, ancestors or
603  /// descendants of explicitly loaded paths.
604  ///
605  /// This method does not return paths to inactive prims.
606  ///
607  /// See \ref Usd_workingSetManagement "Working Set Management" for more
608  /// information.
609  USD_API
611 
612  /// Returns an SdfPathSet of all paths that can be loaded.
613  ///
614  /// Note that this method does not return paths to inactive prims as they
615  /// cannot be loaded.
616  ///
617  /// The set returned includes loaded and unloaded paths. To determine the
618  /// set of unloaded paths, one can diff this set with the current load set,
619  /// for example:
620  /// \code
621  /// SdfPathSet loaded = stage->GetLoadSet(),
622  /// all = stage->FindLoadable(),
623  /// result;
624  /// std::set_difference(loaded.begin(), loaded.end(),
625  /// all.begin(), all.end(),
626  /// std::inserter(result, result.end()));
627  /// \endcode
628  ///
629  /// See \ref Usd_workingSetManagement "Working Set Management" for more
630  /// information.
631  USD_API
633  const SdfPath& rootPath = SdfPath::AbsoluteRootPath());
634 
635  /// Return the stage's current UsdStageLoadRules governing payload
636  /// inclusion.
637  ///
638  /// See \ref Usd_workingSetManagement "Working Set Management" for more
639  /// information.
641  return _loadRules;
642  }
643 
644  /// Set the UsdStageLoadRules to govern payload inclusion on this stage.
645  /// This rebuilds the stage's entire prim hierarchy to follow \p rules.
646  ///
647  /// Note that subsequent calls to Load(), Unload(), LoadAndUnload() will
648  /// modify this stages load rules as described in the documentation for
649  /// those member functions.
650  ///
651  /// See \ref Usd_workingSetManagement "Working Set Management" for more
652  /// information.
653  USD_API
654  void SetLoadRules(UsdStageLoadRules const &rules);
655 
656  /// Return this stage's population mask.
658  return _populationMask;
659  }
660 
661  /// Set this stage's population mask and recompose the stage.
662  USD_API
664 
665  /// Expand this stage's population mask to include the targets of all
666  /// relationships that pass \p relPred and connections to all attributes
667  /// that pass \p attrPred recursively. If \p relPred is null, include all
668  /// relationship targets; if \p attrPred is null, include all connections.
669  ///
670  /// This function can be used, for example, to expand a population mask for
671  /// a given prim to include bound materials, if those bound materials are
672  /// expressed as relationships or attribute connections.
673  ///
674  /// See also UsdPrim::FindAllRelationshipTargetPaths() and
675  /// UsdPrim::FindAllAttributeConnectionPaths().
676  USD_API
678  std::function<bool (UsdRelationship const &)> const &relPred = nullptr,
679  std::function<bool (UsdAttribute const &)> const &attrPred = nullptr);
680 
681  /// @}
682 
683  // --------------------------------------------------------------------- //
684  /// \anchor Usd_primManagement
685  /// \name Prim Access, Creation and Mutation
686  /// All of the methods in this group that accept a prim path as argument
687  /// require paths in the namespace of the stage's root layer, \em regardless
688  /// of what the currently active UsdEditTarget is set to. In other words,
689  /// a UsdStage always presents a composed view of its scene, and all
690  /// prim operations are specified in the composed namespace.
691  /// @{
692  // --------------------------------------------------------------------- //
693 
694  /// Return the stage's "pseudo-root" prim, whose name is defined by Usd.
695  ///
696  /// The stage's named root prims are namespace children of this prim,
697  /// which exists to make the namespace hierarchy a tree instead of a
698  /// forest. This simplifies algorithms that want to traverse all prims.
699  ///
700  /// A UsdStage always has a pseudo-root prim, unless there was an error
701  /// opening or creating the stage, in which case this method returns
702  /// an invalid UsdPrim.
703  USD_API
704  UsdPrim GetPseudoRoot() const;
705 
706  /// Return the root UsdPrim on this stage whose name is the root layer's
707  /// defaultPrim metadata's value. Return an invalid prim if there is no
708  /// such prim or if the root layer's defaultPrim metadata is unset or is not
709  /// a valid prim name. Note that this function only examines this stage's
710  /// rootLayer. It does not consider sublayers of the rootLayer. See also
711  /// SdfLayer::GetDefaultPrim().
712  USD_API
713  UsdPrim GetDefaultPrim() const;
714 
715  /// Set the default prim layer metadata in this stage's root layer. This is
716  /// shorthand for:
717  /// \code
718  /// stage->GetRootLayer()->SetDefaultPrim(prim.GetName());
719  /// \endcode
720  /// Note that this function always authors to the stage's root layer. To
721  /// author to a different layer, use the SdfLayer::SetDefaultPrim() API.
722  USD_API
723  void SetDefaultPrim(const UsdPrim &prim);
724 
725  /// Clear the default prim layer metadata in this stage's root layer. This
726  /// is shorthand for:
727  /// \code
728  /// stage->GetRootLayer()->ClearDefaultPrim();
729  /// \endcode
730  /// Note that this function always authors to the stage's root layer. To
731  /// author to a different layer, use the SdfLayer::SetDefaultPrim() API.
732  USD_API
733  void ClearDefaultPrim();
734 
735  /// Return true if this stage's root layer has an authored opinion for the
736  /// default prim layer metadata. This is shorthand for:
737  /// \code
738  /// stage->GetRootLayer()->HasDefaultPrim();
739  /// \endcode
740  /// Note that this function only consults the stage's root layer. To
741  /// consult a different layer, use the SdfLayer::HasDefaultPrim() API.
742  USD_API
743  bool HasDefaultPrim() const;
744 
745  /// Return the UsdPrim at \p path, or an invalid UsdPrim if none exists.
746  ///
747  /// If \p path indicates a prim beneath an instance, returns an instance
748  /// proxy prim if a prim exists at the corresponding path in that instance's
749  /// master.
750  ///
751  /// Unlike OverridePrim() and DefinePrim(), this method will never author
752  /// scene description, and therefore is safe to use as a "reader" in the Usd
753  /// multi-threading model.
754  USD_API
755  UsdPrim GetPrimAtPath(const SdfPath &path) const;
756 
757  /// Return the UsdObject at \p path, or an invalid UsdObject if none exists.
758  ///
759  /// If \p path indicates a prim beneath an instance, returns an instance
760  /// proxy prim if a prim exists at the corresponding path in that instance's
761  /// master. If \p path indicates a property beneath a child of an instance,
762  /// returns a property whose parent prim is an instance proxy prim.
763  ///
764  /// Example:
765  ///
766  /// \code
767  ///if (UsdObject obj = stage->GetObjectAtPath(path)) {
768  /// if (UsdPrim prim = obj.As<UsdPrim>()) {
769  /// // Do things with prim
770  /// }
771  /// else if (UsdProperty prop = obj.As<UsdProperty>()) {
772  /// // Do things with property. We can also cast to
773  /// // UsdRelationship or UsdAttribute using this same pattern.
774  /// }
775  ///}
776  ///else {
777  /// // No object at specified path
778  ///}
779  /// \endcode
780  USD_API
781  UsdObject GetObjectAtPath(const SdfPath &path) const;
782 
783  /// Return the UsdProperty at \p path, or an invalid UsdProperty
784  /// if none exists.
785  ///
786  /// This is equivalent to
787  /// \code{.cpp}
788  /// stage.GetObjectAtPath(path).As<UsdProperty>();
789  /// \endcode
790  /// \sa GetObjectAtPath(const SdfPath&) const
791  USD_API
793 
794  /// Return the UsdAttribute at \p path, or an invalid UsdAttribute
795  /// if none exists.
796  ///
797  /// This is equivalent to
798  /// \code{.cpp}
799  /// stage.GetObjectAtPath(path).As<UsdAttribute>();
800  /// \endcode
801  /// \sa GetObjectAtPath(const SdfPath&) const
802  USD_API
804 
805  /// Return the UsdAttribute at \p path, or an invalid UsdAttribute
806  /// if none exists.
807  ///
808  /// This is equivalent to
809  /// \code{.cpp}
810  /// stage.GetObjectAtPath(path).As<UsdRelationship>();
811  /// \endcode
812  /// \sa GetObjectAtPath(const SdfPath&) const
813  USD_API
815 private:
816  // Return the primData object at \p path.
817  Usd_PrimDataConstPtr _GetPrimDataAtPath(const SdfPath &path) const;
818  Usd_PrimDataPtr _GetPrimDataAtPath(const SdfPath &path);
819 
820  // Return the primData object at \p path. If \p path indicates a prim
821  // beneath an instance, return the primData object for the corresponding
822  // prim in the instance's master.
824  _GetPrimDataAtPathOrInMaster(const SdfPath &path) const;
825 
826  /// See documentation on UsdPrim::GetInstances()
827  std::vector<UsdPrim> _GetInstancesForMaster(const UsdPrim& master) const;
828 
829 public:
830 
831  /// Traverse the active, loaded, defined, non-abstract prims on this stage
832  /// depth-first.
833  ///
834  /// Traverse() returns a UsdPrimRange , which allows low-latency
835  /// traversal, with the ability to prune subtrees from traversal. It
836  /// is python iterable, so in its simplest form, one can do:
837  ///
838  /// \code{.py}
839  /// for prim in stage.Traverse():
840  /// print prim.GetPath()
841  /// \endcode
842  ///
843  /// If either a pre-and-post-order traversal or a traversal rooted at a
844  /// particular prim is desired, construct a UsdPrimRange directly.
845  ///
846  /// This is equivalent to UsdPrimRange::Stage() .
847  USD_API
849 
850  /// \overload
851  /// Traverse the prims on this stage subject to \p predicate.
852  ///
853  /// This is equivalent to UsdPrimRange::Stage() .
854  USD_API
855  UsdPrimRange Traverse(const Usd_PrimFlagsPredicate &predicate);
856 
857  /// Traverse all the prims on this stage depth-first.
858  ///
859  /// \sa Traverse()
860  /// \sa UsdPrimRange::Stage()
861  USD_API
863 
864  /// Attempt to ensure a \a UsdPrim at \p path exists on this stage.
865  ///
866  /// If a prim already exists at \p path, return it. Otherwise author
867  /// \a SdfPrimSpecs with \a specifier == \a SdfSpecifierOver and empty
868  /// \a typeName at the current EditTarget to create this prim and any
869  /// nonexistent ancestors, then return it.
870  ///
871  /// The given \a path must be an absolute prim path that does not contain
872  /// any variant selections.
873  ///
874  /// If it is impossible to author any of the necessary PrimSpecs, (for
875  /// example, in case \a path cannot map to the current UsdEditTarget's
876  /// namespace) issue an error and return an invalid \a UsdPrim.
877  ///
878  /// If an ancestor of \p path identifies an \a inactive prim, author scene
879  /// description as described above but return an invalid prim, since the
880  /// resulting prim is descendant to an inactive prim.
881  ///
882  USD_API
884 
885  /// Attempt to ensure a \a UsdPrim at \p path is defined (according to
886  /// UsdPrim::IsDefined()) on this stage.
887  ///
888  /// If a prim at \p path is already defined on this stage and \p typeName is
889  /// empty or equal to the existing prim's typeName, return that prim.
890  /// Otherwise author an \a SdfPrimSpec with \a specifier ==
891  /// \a SdfSpecifierDef and \p typeName for the prim at \p path at the
892  /// current EditTarget. Author \a SdfPrimSpec s with \p specifier ==
893  /// \a SdfSpecifierDef and empty typeName at the current EditTarget for any
894  /// nonexistent, or existing but not \a Defined ancestors.
895  ///
896  /// The given \a path must be an absolute prim path that does not contain
897  /// any variant selections.
898  ///
899  /// If it is impossible to author any of the necessary PrimSpecs (for
900  /// example, in case \a path cannot map to the current UsdEditTarget's
901  /// namespace or one of the ancestors of \p path is inactive on the
902  /// UsdStage), issue an error and return an invalid \a UsdPrim.
903  ///
904  /// Note that this method may return a defined prim whose typeName does not
905  /// match the supplied \p typeName, in case a stronger typeName opinion
906  /// overrides the opinion at the current EditTarget.
907  ///
908  USD_API
910  const TfToken &typeName=TfToken());
911 
912  /// Author an \a SdfPrimSpec with \a specifier == \a SdfSpecifierClass for
913  /// the class at root prim path \p path at the current EditTarget. The
914  /// current EditTarget must have UsdEditTarget::IsLocalLayer() == true.
915  ///
916  /// The given \a path must be an absolute, root prim path that does not
917  /// contain any variant selections.
918  ///
919  /// If a defined (UsdPrim::IsDefined()) non-class prim already exists at
920  /// \p path, issue an error and return an invalid UsdPrim.
921  ///
922  /// If it is impossible to author the necessary PrimSpec, issue an error
923  /// and return an invalid \a UsdPrim.
924  USD_API
925  UsdPrim CreateClassPrim(const SdfPath &rootPrimPath);
926 
927  /// Remove all scene description for the given \p path and its subtree
928  /// <em>in the current UsdEditTarget</em>.
929  ///
930  /// This method does not do what you might initially think! Calling this
931  /// function will not necessarily cause the UsdPrim at \p path on this
932  /// stage to disappear. Completely eradicating a prim from a composition
933  /// can be an involved process, involving edits to many contributing layers,
934  /// some of which (in many circumstances) will not be editable by a client.
935  /// This method is a surgical instrument that \em can be used iteratively
936  /// to effect complete removal of a prim and its subtree from namespace,
937  /// assuming the proper permissions are acquired, but more commonly it
938  /// is used to perform layer-level operations; e.g.: ensuring that a given
939  /// layer (as expressed by a UsdEditTarget) provides no opinions for a
940  /// prim and its subtree.
941  ///
942  /// Generally, if your eye is attracted to this method, you probably want
943  /// to instead use UsdPrim::SetActive(false) , which will provide the
944  /// \ref Usd_ActiveInactive "composed effect" of removing the prim and
945  /// its subtree from the composition, without actually removing any
946  /// scene description, which as a bonus, means that the effect is
947  /// reversible at a later time!
948  USD_API
949  bool RemovePrim(const SdfPath& path);
950 
951  /// @}
952 
953  // --------------------------------------------------------------------- //
954  /// \anchor Usd_layerManagement
955  /// \name Layers and EditTargets
956  /// @{
957  // --------------------------------------------------------------------- //
958 
959  /// Return this stage's root session layer.
960  USD_API
961  SdfLayerHandle GetSessionLayer() const;
962 
963  /// Return this stage's root layer.
964  USD_API
965  SdfLayerHandle GetRootLayer() const;
966 
967  /// Return the path resolver context for all path resolution during
968  /// composition of this stage. Useful for external clients that want to
969  /// resolve paths with the same context as this stage, or create new
970  /// stages with the same context.
971  USD_API
973 
974  /// Resolve the given identifier using this stage's
975  /// ArResolverContext and the layer of its GetEditTarget()
976  /// as an anchor for relative references (e.g. \@./siblingFile.usd\@).
977  ///
978  /// \return a non-empty string containing either the same
979  /// identifier that was passed in (if the identifier refers to an
980  /// already-opened layer or an "anonymous", in-memory layer), or a resolved
981  /// layer filepath. If the identifier was not resolvable, return the
982  /// empty string.
983  USD_API
985  ResolveIdentifierToEditTarget(std::string const &identifier) const;
986 
987  /// Return this stage's local layers in strong-to-weak order. If
988  /// \a includeSessionLayers is true, return the linearized strong-to-weak
989  /// sublayers rooted at the stage's session layer followed by the linearized
990  /// strong-to-weak sublayers rooted at this stage's root layer. If
991  /// \a includeSessionLayers is false, omit the sublayers rooted at this
992  /// stage's session layer.
993  USD_API
994  SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const;
995 
996  /// Return a vector of all of the layers \em currently consumed by this
997  /// stage, as determined by the composition arcs that were traversed to
998  /// compose and populate the stage.
999  ///
1000  /// The list of consumed layers will change with the stage's load-set and
1001  /// variant selections, so the return value should be considered only
1002  /// a snapshot. The return value will include the stage's session layer,
1003  /// if it has one. If \a includeClipLayers is true, we will also include
1004  /// all of the layers that this stage has had to open so far to perform
1005  /// value resolution of attributes affected by
1006  /// \ref Usd_Page_ValueClips "Value Clips"
1007  USD_API
1008  SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const;
1009 
1010  /// Return true if \a layer is one of the layers in this stage's local,
1011  /// root layerStack.
1012  USD_API
1013  bool HasLocalLayer(const SdfLayerHandle &layer) const;
1014 
1015  /// Return the stage's EditTarget.
1016  USD_API
1017  const UsdEditTarget &GetEditTarget() const;
1018 
1019  /// Return a UsdEditTarget for editing the layer at index \a i in the
1020  /// layer stack. This edit target will incorporate any layer time
1021  /// offset that applies to the sublayer.
1022  USD_API
1024 
1025  /// Return a UsdEditTarget for editing the given local \a layer.
1026  /// If the given layer appears more than once in the layer stack,
1027  /// the time offset to the first occurrence will be used.
1028  USD_API
1029  UsdEditTarget GetEditTargetForLocalLayer(const SdfLayerHandle &layer);
1030 
1031  /// Set the stage's EditTarget. If \a editTarget.IsLocalLayer(), check to
1032  /// see if it's a layer in this stage's local LayerStack. If not, issue an
1033  /// error and do nothing. If \a editTarget is invalid, issue an error
1034  /// and do nothing. If \a editTarget differs from the stage's current
1035  /// EditTarget, set the EditTarget and send
1036  /// UsdNotice::StageChangedEditTarget. Otherwise do nothing.
1037  USD_API
1038  void SetEditTarget(const UsdEditTarget &editTarget);
1039 
1040  /// Mute the layer identified by \p layerIdentifier. Muted layers are
1041  /// ignored by the stage; they do not participate in value resolution
1042  /// or composition and do not appear in any LayerStack. If the root
1043  /// layer of a reference or payload LayerStack is muted, the behavior
1044  /// is as if the muted layer did not exist, which means a composition
1045  /// error will be generated.
1046  ///
1047  /// A canonical identifier for \p layerIdentifier will be
1048  /// computed using ArResolver::ComputeRepositoryPath. Any layer
1049  /// encountered during composition with the same repository path will
1050  /// be considered muted and ignored. Relative paths will be assumed
1051  /// to be relative to the cache's root layer. Search paths are immediately
1052  /// resolved and the result is used for computing the canonical path.
1053  ///
1054  /// Note that muting a layer will cause this stage to release all
1055  /// references to that layer. If no other client is holding on to
1056  /// references to that layer, it will be unloaded. In this case, if
1057  /// there are unsaved edits to the muted layer, those edits are lost.
1058  /// Since anonymous layers are not serialized, muting an anonymous
1059  /// layer will cause that layer and its contents to be lost in this
1060  /// case.
1061  ///
1062  /// Muting a layer that has not been used by this stage is not an error.
1063  /// If that layer is encountered later, muting will take effect and that
1064  /// layer will be ignored.
1065  ///
1066  /// The root layer of this stage may not be muted; attempting to do so
1067  /// will generate a coding error.
1068  USD_API
1069  void MuteLayer(const std::string &layerIdentifier);
1070 
1071  /// Unmute the layer identified by \p layerIdentifier if it had
1072  /// previously been muted.
1073  USD_API
1074  void UnmuteLayer(const std::string &layerIdentifier);
1075 
1076  /// Mute and unmute the layers identified in \p muteLayers and
1077  /// \p unmuteLayers.
1078  ///
1079  /// This is equivalent to calling UsdStage::UnmuteLayer for each layer
1080  /// in \p unmuteLayers followed by UsdStage::MuteLayer for each layer
1081  /// in \p muteLayers, however this method is more efficient as all
1082  /// operations are committed in a single batch.
1083  USD_API
1084  void MuteAndUnmuteLayers(const std::vector<std::string> &muteLayers,
1085  const std::vector<std::string> &unmuteLayers);
1086 
1087  /// Returns a vector of all layers that have been muted on this stage.
1088  USD_API
1089  const std::vector<std::string>& GetMutedLayers() const;
1090 
1091  /// Returns true if the layer specified by \p layerIdentifier is
1092  /// muted in this cache, false otherwise. See documentation on
1093  /// MuteLayer for details on how \p layerIdentifier is compared to the
1094  /// layers that have been muted.
1095  USD_API
1096  bool IsLayerMuted(const std::string& layerIdentifier) const;
1097 
1098  /// @}
1099 
1100  // --------------------------------------------------------------------- //
1101  /// \anchor Usd_stageSerialization
1102  /// \name Flatten & Export Utilities
1103  /// @{
1104  // --------------------------------------------------------------------- //
1105  // Future Work:
1106  // * Flatten sub-trees or individual prims
1107  // * Allow flattening of local LayerStack
1108  // * Move Flatten into a free-function to ensure it doesn't rely on
1109  // Stage internals.
1110 
1111  /// Writes out the composite scene as a single flattened layer into
1112  /// \a filename.
1113  ///
1114  /// If addSourceFileComment is true, a comment in the output layer
1115  /// will mention the input layer it was generated from.
1116  ///
1117  /// See UsdStage::Flatten for details of the flattening transformation.
1118  USD_API
1119  bool Export(const std::string &filename,
1120  bool addSourceFileComment=true,
1123 
1124  /// Writes the composite scene as a flattened Usd text
1125  /// representation into the given \a string.
1126  ///
1127  /// If addSourceFileComment is true, a comment in the output layer
1128  /// will mention the input layer it was generated from.
1129  ///
1130  /// See UsdStage::Flatten for details of the flattening transformation.
1131  USD_API
1133  bool addSourceFileComment=true) const;
1134 
1135  /// Returns a single, anonymous, merged layer for this composite
1136  /// scene.
1137  ///
1138  /// Specifically, this function removes **most** composition metadata and
1139  /// authors the resolved values for each object directly into the flattened
1140  /// layer.
1141  ///
1142  /// All VariantSets are removed and only the currently selected variants
1143  /// will be present in the resulting layer.
1144  ///
1145  /// Class prims will still exist, however all inherits arcs will have
1146  /// been removed and the inherited data will be copied onto each child
1147  /// object. Composition arcs authored on the class itself will be flattened
1148  /// into the class.
1149  ///
1150  /// Flatten preserves
1151  /// \ref Usd_Page_ScenegraphInstancing "scenegraph instancing" by creating
1152  /// independent roots for each master currently composed on this stage, and
1153  /// adding a single internal reference arc on each instance prim to its
1154  /// corresponding master.
1155  ///
1156  /// Time samples across sublayer offsets will will have the time offset and
1157  /// scale applied to each time index.
1158  ///
1159  /// Finally, any deactivated prims will be pruned from the result.
1160  ///
1161  USD_API
1162  SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const;
1163  /// @}
1164 
1165 public:
1166  // --------------------------------------------------------------------- //
1167  /// \anchor Usd_stageMetadata
1168  /// \name Stage Metadata
1169  /// Stage metadata applies to the entire contents of the stage, and is
1170  /// recorded only in the stage's root or primary session-layer. Most of
1171  /// the other, specific metadata methods on UsdStage are defined in terms
1172  /// of these generic methods.
1173  /// @{
1174  // --------------------------------------------------------------------- //
1175 
1176  /// Return in \p value an authored or fallback value (if one was defined
1177  /// for the given metadatum) for Stage metadatum \p key. Order of
1178  /// resolution is session layer, followed by root layer, else fallback to
1179  /// the SdfSchema.
1180  ///
1181  /// \return true if we successfully retrieved a value of the requested type;
1182  /// false if \p key is not allowed as layer metadata or no value was found.
1183  /// Generates a coding error if we retrieved a stored value of a type other
1184  /// than the requested type
1185  ///
1186  /// \sa \ref Usd_OM_Metadata
1187  template <class T>
1188  bool GetMetadata(const TfToken &key, T *value) const;
1189  /// \overload
1190  USD_API
1191  bool GetMetadata(const TfToken &key, VtValue *value) const;
1192 
1193  /// Returns true if the \a key has a meaningful value, that is, if
1194  /// GetMetadata() will provide a value, either because it was authored
1195  /// or because the Stage metadata was defined with a meaningful fallback
1196  /// value.
1197  ///
1198  /// Returns false if \p key is not allowed as layer metadata.
1199  USD_API
1200  bool HasMetadata(const TfToken &key) const;
1201 
1202  /// Returns \c true if the \a key has an authored value, \c false if no
1203  /// value was authored or the only value available is the SdfSchema's
1204  /// metadata fallback.
1205  ///
1206  /// \note If a value for a metadatum \em not legal to author on layers
1207  /// is present in the root or session layer (which could happen through
1208  /// hand-editing or use of certain low-level API's), this method will
1209  /// still return \c false.
1210  USD_API
1211  bool HasAuthoredMetadata(const TfToken &key) const;
1212 
1213  /// Set the value of Stage metadatum \p key to \p value, if the stage's
1214  /// current UsdEditTarget is the root or session layer.
1215  ///
1216  /// If the current EditTarget is any other layer, raise a coding error.
1217  /// \return true if authoring was successful, false otherwise.
1218  /// Generates a coding error if \p key is not allowed as layer metadata.
1219  ///
1220  /// \sa \ref Usd_OM_Metadata
1221  template<typename T>
1222  bool SetMetadata(const TfToken &key, const T &value) const;
1223  /// \overload
1224  USD_API
1225  bool SetMetadata(const TfToken &key, const VtValue &value) const;
1226 
1227  /// Clear the value of stage metadatum \p key, if the stage's
1228  /// current UsdEditTarget is the root or session layer.
1229  ///
1230  /// If the current EditTarget is any other layer, raise a coding error.
1231  /// \return true if authoring was successful, false otherwise.
1232  /// Generates a coding error if \p key is not allowed as layer metadata.
1233  ///
1234  /// \sa \ref Usd_OM_Metadata
1235  USD_API
1236  bool ClearMetadata(const TfToken &key) const;
1237 
1238  /// Resolve the requested dictionary sub-element \p keyPath of
1239  /// dictionary-valued metadatum named \p key, returning the resolved
1240  /// value.
1241  ///
1242  /// If you know you need just a small number of elements from a dictionary,
1243  /// accessing them element-wise using this method can be much less
1244  /// expensive than fetching the entire dictionary with GetMetadata(key).
1245  ///
1246  /// \return true if we successfully retrieved a value of the requested type;
1247  /// false if \p key is not allowed as layer metadata or no value was found.
1248  /// Generates a coding error if we retrieved a stored value of a type other
1249  /// than the requested type
1250  ///
1251  /// The \p keyPath is a ':'-separated path addressing an element
1252  /// in subdictionaries. If \p keyPath is empty, returns an empty VtValue.
1253  template<typename T>
1254  bool GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1255  T* value) const;
1256  /// overload
1257  USD_API
1258  bool GetMetadataByDictKey(
1259  const TfToken& key, const TfToken &keyPath, VtValue *value) const;
1260 
1261  /// Return true if there exists any authored or fallback opinion for
1262  /// \p key and \p keyPath.
1263  ///
1264  /// The \p keyPath is a ':'-separated path identifying a value in
1265  /// subdictionaries stored in the metadata field at \p key. If
1266  /// \p keyPath is empty, returns \c false.
1267  ///
1268  /// Returns false if \p key is not allowed as layer metadata.
1269  ///
1270  /// \sa \ref Usd_Dictionary_Type
1271  USD_API
1272  bool HasMetadataDictKey(
1273  const TfToken& key, const TfToken &keyPath) const;
1274 
1275  /// Return true if there exists any authored opinion (excluding
1276  /// fallbacks) for \p key and \p keyPath.
1277  ///
1278  /// The \p keyPath is a ':'-separated path identifying a value in
1279  /// subdictionaries stored in the metadata field at \p key. If
1280  /// \p keyPath is empty, returns \c false.
1281  ///
1282  /// \sa \ref Usd_Dictionary_Type
1283  USD_API
1285  const TfToken& key, const TfToken &keyPath) const;
1286 
1287  /// Author \p value to the field identified by \p key and \p keyPath
1288  /// at the current EditTarget.
1289  ///
1290  /// The \p keyPath is a ':'-separated path identifying a value in
1291  /// subdictionaries stored in the metadata field at \p key. If
1292  /// \p keyPath is empty, no action is taken.
1293  ///
1294  /// \return true if the value is authored successfully, false otherwise.
1295  /// Generates a coding error if \p key is not allowed as layer metadata.
1296  ///
1297  /// \sa \ref Usd_Dictionary_Type
1298  template<typename T>
1299  bool SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
1300  const T& value) const;
1301  /// \overload
1302  USD_API
1303  bool SetMetadataByDictKey(
1304  const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
1305 
1306  /// Clear any authored value identified by \p key and \p keyPath
1307  /// at the current EditTarget.
1308  ///
1309  /// The \p keyPath is a ':'-separated path identifying a path in
1310  /// subdictionaries stored in the metadata field at \p key. If
1311  /// \p keyPath is empty, no action is taken.
1312  ///
1313  /// \return true if the value is cleared successfully, false otherwise.
1314  /// Generates a coding error if \p key is not allowed as layer metadata.
1315  ///
1316  /// \sa \ref Usd_Dictionary_Type
1317  USD_API
1319  const TfToken& key, const TfToken& keyPath) const;
1320 
1321  /// Writes the fallback prim types defined in the schema registry to the
1322  /// stage as dictionary valued fallback prim type metadata. If the stage
1323  /// already has fallback prim type metadata, the fallback types from the
1324  /// schema registry will be added to the existing metadata, only for types
1325  /// that are already present in the dictionary, i.e. this won't overwrite
1326  /// existing fallback entries.
1327  ///
1328  /// The current edit target determines whether the metadata is written to
1329  /// the root layer or the session layer. If the edit target specifies
1330  /// another layer besides these, this will produce an error.
1331  ///
1332  /// This function can be used at any point before calling Save or Export on
1333  /// a stage to record the fallback types for the current schemas. This
1334  /// allows another version of Usd to open this stage and treat prim types it
1335  /// doesn't recognize as a type it does recognize defined for it in this
1336  /// metadata.
1337  ///
1338  /// \sa \ref Usd_OM_FallbackPrimTypes UsdSchemaRegistry::GetFallbackPrimTypes
1339  USD_API
1340  void WriteFallbackPrimTypes();
1341 
1342  /// @}
1343 
1344  // --------------------------------------------------------------------- //
1345  /// \anchor Usd_timeCodeAPI
1346  /// \name TimeCode API
1347  /// Methods for managing the Stage's active timeSample range, time units,
1348  /// and intended rate of playback. See \ref Usd_OM_UsdTimeCode for more
1349  /// on time and TimeCodes in USD.
1350  /// @{
1351  // --------------------------------------------------------------------- //
1352  /// Returns the stage's start timeCode. If the stage has an associated
1353  /// session layer with a start timeCode opinion, this value is returned.
1354  /// Otherwise, the start timeCode opinion from the root layer is returned.
1355  USD_API
1356  double GetStartTimeCode() const;
1357 
1358  /// Sets the stage's start timeCode.
1359  ///
1360  /// The start timeCode is set in the current EditTarget, if it is the root
1361  /// layer of the stage or the session layer associated with the stage. If
1362  /// the current EditTarget is neither, a warning is issued and the start
1363  /// timeCode is not set.
1364  USD_API
1365  void SetStartTimeCode(double);
1366 
1367  /// Returns the stage's end timeCode. If the stage has an associated
1368  /// session layer with an end timeCode opinion, this value is returned.
1369  /// Otherwise, the end timeCode opinion from the root layer is returned.
1370  USD_API
1371  double GetEndTimeCode() const;
1372 
1373  /// Sets the stage's end timeCode.
1374  ///
1375  /// The end timeCode is set in the current EditTarget, if it is the root
1376  /// layer of the stage or the session layer associated with the stage. If
1377  /// the current EditTarget is neither, a warning is issued and the end
1378  /// timeCode is not set.
1379  USD_API
1380  void SetEndTimeCode(double);
1381 
1382  /// Returns true if the stage has both start and end timeCodes
1383  /// authored in the session layer or the root layer of the stage.
1384  USD_API
1385  bool HasAuthoredTimeCodeRange() const;
1386 
1387  /// Returns the stage's timeCodesPerSecond value.
1388  ///
1389  /// The timeCodesPerSecond value scales the time ordinate for the samples
1390  /// contained in the stage to seconds. If timeCodesPerSecond is 24, then a
1391  /// sample at time ordinate 24 should be viewed exactly one second after the
1392  /// sample at time ordinate 0.
1393  ///
1394  /// Like SdfLayer::GetTimeCodesPerSecond, this accessor uses a dynamic
1395  /// fallback to framesPerSecond. The order of precedence is:
1396  ///
1397  /// \li timeCodesPerSecond from session layer
1398  /// \li timeCodesPerSecond from root layer
1399  /// \li framesPerSecond from session layer
1400  /// \li framesPerSecond from root layer
1401  /// \li fallback value of 24
1402  USD_API
1403  double GetTimeCodesPerSecond() const;
1404 
1405  /// Sets the stage's timeCodesPerSecond value.
1406  ///
1407  /// The timeCodesPerSecond value is set in the current EditTarget, if it
1408  /// is the root layer of the stage or the session layer associated with the
1409  /// stage. If the current EditTarget is neither, a warning is issued and no
1410  /// value is set.
1411  ///
1412  /// \sa GetTimeCodesPerSecond()
1413  USD_API
1414  void SetTimeCodesPerSecond(double timeCodesPerSecond) const;
1415 
1416  /// Returns the stage's framesPerSecond value.
1417  ///
1418  /// This makes an advisory statement about how the contained data can be
1419  /// most usefully consumed and presented. It's primarily an indication of
1420  /// the expected playback rate for the data, but a timeline editing tool
1421  /// might also want to use this to decide how to scale and label its
1422  /// timeline.
1423  ///
1424  /// The default value of framesPerSecond is 24.
1425  USD_API
1426  double GetFramesPerSecond() const;
1427 
1428  /// Sets the stage's framesPerSecond value.
1429  ///
1430  /// The framesPerSecond value is set in the current EditTarget, if it
1431  /// is the root layer of the stage or the session layer associated with the
1432  /// stage. If the current EditTarget is neither, a warning is issued and no
1433  /// value is set.
1434  ///
1435  /// \sa GetFramesPerSecond()
1436  USD_API
1437  void SetFramesPerSecond(double framesPerSecond) const;
1438 
1439  /// @}
1440 
1441  // --------------------------------------------------------------------- //
1442  /// \anchor Usd_ColorConfigurationAPI
1443  /// \name Color Configuration API
1444  ///
1445  /// Methods for authoring and querying the color configuration to
1446  /// be used to interpret the per-attribute color-spaces. An external
1447  /// system (like OpenColorIO) is typically used for interpreting the
1448  /// configuration.
1449  ///
1450  /// Site-wide fallback values for the colorConfiguration and
1451  /// colorManagementSystem metadata can be set in the plugInfo.json file of
1452  /// a plugin using this structure:
1453  ///
1454  /// \code{.json}
1455  /// "UsdColorConfigFallbacks": {
1456  /// "colorConfiguration" = "https://github.com/imageworks/OpenColorIO-Configs/blob/master/aces_1.0.1/config.ocio",
1457  /// "colorManagementSystem" : "OpenColorIO"
1458  /// }
1459  /// \endcode
1460  ///
1461  /// The color space in which a given color or texture attribute is authored
1462  /// is set as token-valued metadata 'colorSpace' on the attribute. For
1463  /// color or texture attributes that don't have an authored 'colorSpace'
1464  /// value, the fallback color-space is gleaned from the color configuration
1465  /// oracle. This is usually the config's <b>scene_linear</b> role
1466  /// color-space.
1467  ///
1468  /// Here's the pseudo-code for determining an attribute's color-space.
1469  ///
1470  /// \code{.cpp}
1471  /// UsdStageRefPtr stage = UsdStage::Open(filePath);
1472  /// UsdPrim prim = stage->GetPrimAtPath("/path/to/prim")
1473  /// UsdAttribute attr = prim.GetAttribute("someColorAttr");
1474  /// TfToken colorSpace = attr.GetColorSpace();
1475  /// if (colorSpace.IsEmpty()) {
1476  /// // If colorSpace is empty, get the default from the stage's
1477  /// // colorConfiguration, using external API (not provided by USD).
1478  /// colorSpace = ExternalAPI::GetDefaultColorSpace(
1479  /// stage->GetColorConfiguration());
1480  /// }
1481  /// \endcode
1482  ///
1483  /// \sa \ref Usd_AttributeColorSpaceAPI "UsdAttribute ColorSpace API"
1484  ///
1485  ///
1486  /// @{
1487  // --------------------------------------------------------------------- //
1488 
1489  /// Sets the default color configuration to be used to interpret the
1490  /// per-attribute color-spaces in the composed USD stage. This is specified
1491  /// as asset path which can be resolved to the color spec file.
1492  ///
1493  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1494  USD_API
1495  void SetColorConfiguration(const SdfAssetPath &colorConfig) const;
1496 
1497  /// Returns the default color configuration used to interpret the per-
1498  /// attribute color-spaces in the composed USD stage.
1499  ///
1500  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1501  USD_API
1503 
1504  /// Sets the name of the color management system used to interpret the
1505  /// color configuration file pointed at by the colorConfiguration metadata.
1506  ///
1507  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1508  USD_API
1509  void SetColorManagementSystem(const TfToken &cms) const;
1510 
1511  /// Sets the name of the color management system to be used for loading
1512  /// and interpreting the color configuration file.
1513  ///
1514  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1515  USD_API
1517 
1518  /// Returns the global fallback values of 'colorConfiguration' and
1519  /// 'colorManagementSystem'. These are set in the plugInfo.json file
1520  /// of a plugin, but can be overridden by calling the static method
1521  /// SetColorConfigFallbacks().
1522  ///
1523  /// The python wrapping of this method returns a tuple containing
1524  /// (colorConfiguration, colorManagementSystem).
1525  ///
1526  ///
1527  /// \sa SetColorConfigFallbacks,
1528  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1529  USD_API
1530  static void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration,
1531  TfToken *colorManagementSystem);
1532 
1533  /// Sets the global fallback values of color configuration metadata which
1534  /// includes the 'colorConfiguration' asset path and the name of the
1535  /// color management system. This overrides any fallback values authored
1536  /// in plugInfo files.
1537  ///
1538  /// If the specified value of \p colorConfiguration or
1539  /// \p colorManagementSystem is empty, then the corresponding fallback
1540  /// value isn't set. In other words, for this call to have an effect,
1541  /// at least one value must be non-empty. Additionally, these can't be
1542  /// reset to empty values.
1543  ///
1544  /// \sa GetColorConfigFallbacks()
1545  /// \ref Usd_ColorConfigurationAPI "Color Configuration API"
1546  USD_API
1547  static void
1548  SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration,
1549  const TfToken &colorManagementSystem);
1550 
1551  /// @}
1552 
1553  // --------------------------------------------------------------------- //
1554  /// \anchor Usd_interpolation
1555  /// \name Attribute Value Interpolation
1556  /// Controls the interpolation behavior when retrieving attribute
1557  /// values. The default behavior is linear interpolation.
1558  /// See \ref Usd_AttributeInterpolation for more details.
1559  /// @{
1560  // --------------------------------------------------------------------- //
1561 
1562  /// Sets the interpolation type used during value resolution
1563  /// for all attributes on this stage. Changing this will cause a
1564  /// UsdNotice::StageContentsChanged notice to be sent, as values at
1565  /// times where no samples are authored may have changed.
1566  USD_API
1567  void SetInterpolationType(UsdInterpolationType interpolationType);
1568 
1569  /// Returns the interpolation type used during value resolution
1570  /// for all attributes on this stage.
1571  USD_API
1573 
1574  /// @}
1575 
1576  // --------------------------------------------------------------------- //
1577  /// \anchor Usd_instancing
1578  /// \name Instancing
1579  /// See \ref Usd_Page_ScenegraphInstancing for more details.
1580  /// @{
1581  // --------------------------------------------------------------------- //
1582 
1583  /// Returns all master prims.
1584  USD_API
1585  std::vector<UsdPrim> GetMasters() const;
1586 
1587  /// @}
1588 
1589 private:
1590  struct _IncludePayloadsPredicate;
1591 
1592  // --------------------------------------------------------------------- //
1593  // Stage Construction & Initialization
1594  // --------------------------------------------------------------------- //
1595 
1596  UsdStage(const SdfLayerRefPtr& rootLayer,
1597  const SdfLayerRefPtr& sessionLayer,
1598  const ArResolverContext& pathResolverContext,
1600  InitialLoadSet load);
1601 
1602  // Helper for Open() overloads -- searches and publishes to bound caches.
1603  template <class... Args>
1604  static UsdStageRefPtr _OpenImpl(InitialLoadSet load, Args const &... args);
1605 
1606  // Releases resources used by this stage.
1607  void _Close();
1608 
1609  // Common ref ptr initialization, called by public, static constructors.
1610  //
1611  // This method will either return a valid refptr (if the stage is correctly
1612  // initialized) or it will return a null ref pointer, deleting the
1613  // raw stage pointer in the process.
1614  static UsdStageRefPtr
1615  _InstantiateStage(const SdfLayerRefPtr &rootLayer,
1616  const SdfLayerRefPtr &sessionLayer,
1617  const ArResolverContext &pathResolverContext,
1619  InitialLoadSet load);
1620 
1621  // --------------------------------------------------------------------- //
1622  // Spec Existence & Definition Helpers
1623  // --------------------------------------------------------------------- //
1624 
1625  SdfPropertySpecHandleVector
1626  _GetPropertyStack(const UsdProperty &prop, UsdTimeCode time) const;
1627 
1628  SdfPropertySpecHandle
1629  _GetSchemaPropertySpec(const UsdPrim &prim, const TfToken &propName) const;
1630 
1631  SdfPropertySpecHandle
1632  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1633 
1634  template <class PropType>
1636  _GetSchemaPropertySpec(const UsdProperty &prop) const;
1637 
1638  SdfAttributeSpecHandle
1639  _GetSchemaAttributeSpec(const UsdAttribute &attr) const;
1640 
1641  SdfRelationshipSpecHandle
1642  _GetSchemaRelationshipSpec(const UsdRelationship &rel) const;
1643 
1644  SdfPrimSpecHandle
1645  _CreatePrimSpecForEditing(const UsdPrim& prim);
1646 
1647  template <class PropType>
1649  _CreatePropertySpecForEditing(const UsdProperty &prop);
1650 
1651  SdfPropertySpecHandle
1652  _CreatePropertySpecForEditing(const UsdProperty &prop);
1653 
1654  SdfAttributeSpecHandle
1655  _CreateAttributeSpecForEditing(const UsdAttribute &attr);
1656 
1657  SdfRelationshipSpecHandle
1658  _CreateRelationshipSpecForEditing(const UsdRelationship &rel);
1659 
1660  // Check if the given path is valid to use with the prim creation API,
1661  // like DefinePrim. If it is valid, returns (true, GetPrimAtPath(path)).
1662  // Otherwise, returns (false, UsdPrim()).
1663  std::pair<bool, UsdPrim>
1664  _IsValidPathForCreatingPrim(const SdfPath &path) const;
1665 
1666  // Validates that editing a specified prim is allowed. If editing is not
1667  // allowed, issues a coding error like "Cannot <operation> ..." and
1668  // returns false. Otherwise, returns true.
1669  bool _ValidateEditPrim(const UsdPrim &prim, const char* operation) const;
1670  bool _ValidateEditPrimAtPath(const SdfPath &primPath,
1671  const char* operation) const;
1672 
1673  UsdPrim _DefinePrim(const SdfPath &path, const TfToken &typeName);
1674 
1675  bool _RemoveProperty(const SdfPath& path);
1676 
1677  UsdProperty _FlattenProperty(const UsdProperty &srcProp,
1678  const UsdPrim &dstParent,
1679  const TfToken &dstName);
1680 
1681  // --------------------------------------------------------------------- //
1682  // Value & Metadata Authoring
1683  // --------------------------------------------------------------------- //
1684 
1685  // Trait that allows us to call the correct versions of _SetValue and
1686  // _SetMetadata for types whose values need to be mapped when written to
1687  // different edit targets.
1688  template <class T>
1689  struct _IsEditTargetMappable {
1690  static const bool value =
1692  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1695  };
1696 
1697  // Set value for types that don't need to be mapped for edit targets.
1698  template <class T>
1700  _SetValue(
1701  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1702 
1703  // Set value for types that do need to be mapped for edit targets.
1704  template <class T>
1706  _SetValue(
1707  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1708 
1709  // Set value for dynamically typed VtValue. Will map the value across edit
1710  // targets if the held value type supports it.
1711  bool _SetValue(
1712  UsdTimeCode time, const UsdAttribute &attr, const VtValue &newValue);
1713 
1714  template <class T>
1715  bool _SetEditTargetMappedValue(
1716  UsdTimeCode time, const UsdAttribute &attr, const T &newValue);
1717 
1718  template <class T>
1719  bool _SetValueImpl(
1720  UsdTimeCode time, const UsdAttribute &attr, const T& value);
1721 
1722  bool _ClearValue(UsdTimeCode time, const UsdAttribute &attr);
1723 
1724  // Set metadata for types that don't need to be mapped across edit targets.
1725  template <class T>
1727  _SetMetadata(const UsdObject &object, const TfToken& key,
1728  const TfToken &keyPath, const T& value);
1729 
1730  // Set metadata for types that do need to be mapped for edit targets.
1731  template <class T>
1733  _SetMetadata(const UsdObject &object, const TfToken& key,
1734  const TfToken &keyPath, const T& value);
1735 
1736  // Set metadata for dynamically typed VtValue. Will map the value across
1737  // edit targets if the held value type supports it.
1738  USD_API
1739  bool _SetMetadata(const UsdObject &object,
1740  const TfToken& key,
1741  const TfToken &keyPath,
1742  const VtValue& value);
1743 
1744  template <class T>
1745  bool _SetEditTargetMappedMetadata(
1746  const UsdObject &obj, const TfToken& fieldName,
1747  const TfToken &keyPath, const T &newValue);
1748 
1749  template <class T>
1750  bool _SetMetadataImpl(
1751  const UsdObject &obj, const TfToken& fieldName,
1752  const TfToken &keyPath, const T &value);
1753 
1754  bool _ClearMetadata(const UsdObject &obj, const TfToken& fieldName,
1755  const TfToken &keyPath=TfToken());
1756 
1757  // --------------------------------------------------------------------- //
1758  // Misc Internal Helpers
1759  // --------------------------------------------------------------------- //
1760 
1761  // Pcp helpers.
1762  PcpCache const *_GetPcpCache() const { return _cache.get(); }
1763  PcpCache *_GetPcpCache() { return _cache.get(); }
1764 
1765  // Returns the PrimIndex, using the read-only PcpCache API. We expect prims
1766  // to be composed during initial stage composition, so this method should
1767  // not be used in that context.
1768  const PcpPrimIndex* _GetPcpPrimIndex(const SdfPath& primPath) const;
1769 
1770  // Helper to report pcp errors.
1771  void _ReportPcpErrors(const PcpErrorVector &errors,
1772  const std::string &context) const;
1773  void _ReportErrors(const PcpErrorVector &errors,
1774  const std::vector<std::string>& otherErrors,
1775  const std::string &context) const;
1776 
1777  // --------------------------------------------------------------------- //
1778  // Scenegraph Composition & Change Processing
1779  // --------------------------------------------------------------------- //
1780 
1781  // Compose the prim indexes in the subtrees rooted at the paths in
1782  // \p primIndexPaths. If \p instanceChanges is given, returns
1783  // changes to masters and instances due to the discovery of new instances
1784  // during composition.
1785  void _ComposePrimIndexesInParallel(
1786  const std::vector<SdfPath>& primIndexPaths,
1787  const std::string& context,
1788  Usd_InstanceChanges* instanceChanges = nullptr);
1789 
1790  // Recompose the subtree rooted at \p prim: compose its type, flags, and
1791  // list of children, then invoke _ComposeSubtree on all its children.
1792  void _ComposeSubtree(
1795  const SdfPath &primIndexPath = SdfPath());
1796  void _ComposeSubtreeImpl(
1798  UsdStagePopulationMask const *mask,
1799  const SdfPath &primIndexPath = SdfPath());
1800  void _ComposeSubtreeInParallel(Usd_PrimDataPtr prim);
1801  void _ComposeSubtreesInParallel(
1802  const std::vector<Usd_PrimDataPtr> &prims,
1803  const std::vector<SdfPath> *primIndexPaths = nullptr);
1804 
1805  // Compose subtree rooted at \p prim under \p parent. This function
1806  // ensures that the appropriate prim index is specified for \p prim if
1807  // \p parent is in a master.
1808  void _ComposeChildSubtree(Usd_PrimDataPtr prim,
1809  Usd_PrimDataConstPtr parent,
1810  UsdStagePopulationMask const *mask);
1811 
1812  // Compose \p prim's list of children and make any modifications necessary
1813  // to its _children member and the stage's _primMap, including possibly
1814  // instantiating new prims, or destroying existing subtrees of prims. The
1815  // any newly created prims *do not* have their prim index, type, flags, or
1816  // children composed.
1817  //
1818  // Compose only \p prim's direct children if recurse=false. Otherwise
1819  // recompose every descendent of \p prim. Callers that pass recurse=false
1820  // should invoke _ComposeSubtree on any newly created prims to ensure caches
1821  // are correctly populated.
1822  void _ComposeChildren(Usd_PrimDataPtr prim,
1823  UsdStagePopulationMask const *mask, bool recurse);
1824 
1825  // Instantiate a prim instance. There must not already be an instance
1826  // at \p primPath.
1827  Usd_PrimDataPtr _InstantiatePrim(const SdfPath &primPath);
1828 
1829  // Instantiate a master prim and sets its parent to pseudoroot.
1830  // There must not already be a master at \p primPath.
1831  Usd_PrimDataPtr _InstantiateMasterPrim(const SdfPath &primPath);
1832 
1833  // For \p prim and all of its descendants, remove from _primMap and empty
1834  // their _children vectors.
1835  void _DestroyPrim(Usd_PrimDataPtr prim);
1836 
1837  // Destroy the prim subtrees rooted at each path in \p paths. \p paths may
1838  // not contain any path that is a descendent of another path in \p paths.
1839  void _DestroyPrimsInParallel(const std::vector<SdfPath>& paths);
1840 
1841  // Invoke _DestroyPrim() on all of \p prim's direct children.
1842  void _DestroyDescendents(Usd_PrimDataPtr prim);
1843 
1844  // Returns true if the object at the given path is a descendant of
1845  // an instance prim, i.e. a prim beneath an instance prim, or a property
1846  // of a prim beneath an instance prim.
1847  bool _IsObjectDescendantOfInstance(const SdfPath& path) const;
1848 
1849  // If the given prim is an instance, returns the corresponding
1850  // master prim. Otherwise, returns an invalid prim.
1851  Usd_PrimDataConstPtr _GetMasterForInstance(Usd_PrimDataConstPtr p) const;
1852 
1853  // Returns the path of the Usd prim using the prim index at the given path.
1854  SdfPath _GetPrimPathUsingPrimIndexAtPath(const SdfPath& primIndexPath) const;
1855 
1856  // Update stage contents in response to changes in scene description.
1857  void _HandleLayersDidChange(const SdfNotice::LayersDidChangeSentPerLayer &);
1858 
1859  // Remove scene description for the prim at \p fullPath in the current edit
1860  // target.
1861  bool _RemovePrim(const SdfPath& fullPath);
1862 
1863  SdfPrimSpecHandle _GetPrimSpec(const SdfPath& fullPath);
1864 
1865  // Find and return the defining spec type for the property spec at the given
1866  // path, or SdfSpecTypeUnknown if none exists. The defining spec type is
1867  // either the builtin definition's spec type, if the indicated property is
1868  // builtin, otherwise it's the strongest authored spec's type if one exists,
1869  // otherwise it's SdfSpecTypeUnknown.
1870  SdfSpecType _GetDefiningSpecType(Usd_PrimDataConstPtr primData,
1871  const TfToken &propName) const;
1872 
1873  // Helper to apply Pcp changes and recompose the scenegraph accordingly,
1874  // given an optional initial set of paths to recompose.
1875  void _Recompose(const PcpChanges &changes);
1876  template <class T>
1877  void _Recompose(const PcpChanges &changes, T *pathsToRecompose);
1878  template <class T>
1879  void _RecomposePrims(const PcpChanges &changes, T *pathsToRecompose);
1880 
1881  // Helper for _Recompose to find the subtrees that need to be
1882  // fully recomposed and to recompose the name children of the
1883  // parents of these subtrees. Note that [start, finish) must be a
1884  // sorted range of paths with no descendent paths.
1885  template <class Iter>
1886  void _ComputeSubtreesToRecompose(Iter start, Iter finish,
1887  std::vector<Usd_PrimDataPtr>* recompose);
1888 
1889  // return true if the path is valid for load/unload operations.
1890  // This method will emit errors when invalid paths are encountered.
1891  bool _IsValidForLoad(const SdfPath& path) const;
1892  bool _IsValidForUnload(const SdfPath& path) const;
1893 
1894  // Discover all payloads in a given subtree, adding the path of each
1895  // discovered prim index to the \p primIndexPaths set. If specified,
1896  // the corresponding UsdPrim path will be added to the \p usdPrimPaths
1897  // set. The root path will be considered for inclusion in the result set.
1898  //
1899  // Note that some payloads may not be discoverable in until an ancestral
1900  // payload has been included. UsdStage::LoadAndUnload takes this into
1901  // account.
1902  void _DiscoverPayloads(const SdfPath& rootPath,
1904  SdfPathSet* primIndexPaths,
1905  bool unloadedOnly = false,
1906  SdfPathSet* usdPrimPaths = nullptr) const;
1907 
1908  // ===================================================================== //
1909  // VALUE RESOLUTION //
1910  // ===================================================================== //
1911  // --------------------------------------------------------------------- //
1912  // Specialized Value Resolution
1913  // --------------------------------------------------------------------- //
1914 
1915  // Helpers for resolving values for metadata fields requiring
1916  // special behaviors.
1917  static SdfSpecifier _GetSpecifier(Usd_PrimDataConstPtr primData);
1918  static TfToken _GetKind(Usd_PrimDataConstPtr primData);
1919  static bool _IsActive(Usd_PrimDataConstPtr primData);
1920 
1921  // Custom is true if it is true anywhere in the stack.
1922  bool _IsCustom(const UsdProperty &prop) const;
1923 
1924  // Variability is determined by the weakest opinion in the stack.
1925  SdfVariability _GetVariability(const UsdProperty &prop) const;
1926 
1927  // Helper functions for resolving asset paths during value resolution.
1928  void _MakeResolvedAssetPaths(UsdTimeCode time, const UsdAttribute &attr,
1929  SdfAssetPath *assetPaths,
1930  size_t numAssetPaths,
1931  bool anchorAssetPathsOnly = false) const;
1932 
1933  void _MakeResolvedAssetPathsValue(UsdTimeCode time, const UsdAttribute &attr,
1934  VtValue *value,
1935  bool anchorAssetPathsOnly = false) const;
1936 
1937  void _MakeResolvedTimeCodes(UsdTimeCode time, const UsdAttribute &attr,
1938  SdfTimeCode *timeCodes,
1939  size_t numTimeCodes) const;
1940 
1941  void _MakeResolvedAttributeValue(UsdTimeCode time, const UsdAttribute &attr,
1942  VtValue *value) const;
1943 
1944  // --------------------------------------------------------------------- //
1945  // Metadata Resolution
1946  // --------------------------------------------------------------------- //
1947 
1948 public:
1949  // Trait that allows us to call the correct version of _GetMetadata for
1950  // types that require type specific value resolution as opposed to just
1951  // strongest opinion. These types also use type specific resolution
1952  // in _GetValue.
1953  template <class T>
1955  static const bool value =
1957  std::is_same<T, VtArray<SdfAssetPath>>::value ||
1959  std::is_same<T, VtArray<SdfTimeCode>>::value ||
1962  };
1963 
1964 private:
1965  // Get metadata for types that do not have type specific value resolution.
1966  template <class T>
1968  _GetMetadata(const UsdObject &obj,
1969  const TfToken& fieldName,
1970  const TfToken &keyPath,
1971  bool useFallbacks,
1972  T* result) const;
1973 
1974  // Get metadata for types that do have type specific value resolution.
1975  template <class T>
1977  _GetMetadata(const UsdObject &obj,
1978  const TfToken& fieldName,
1979  const TfToken &keyPath,
1980  bool useFallbacks,
1981  T* result) const;
1982 
1983  // Get metadata as a dynamically typed VtValue. Will perform type specific
1984  // value resolution if the returned held type requires it.
1985  bool _GetMetadata(const UsdObject &obj,
1986  const TfToken& fieldName,
1987  const TfToken &keyPath,
1988  bool useFallbacks,
1989  VtValue* result) const;
1990 
1991  // Gets a metadata value using only strongest value resolution. It is
1992  // assumed that result is holding a value that does not require type
1993  // specific value resolution.
1994  USD_API
1995  bool _GetStrongestResolvedMetadata(const UsdObject &obj,
1996  const TfToken& fieldName,
1997  const TfToken &keyPath,
1998  bool useFallbacks,
1999  SdfAbstractDataValue* result) const;
2000 
2001  // Gets a metadata value with the type specific value resolution for the
2002  // type applied. This is only implemented for types that
2003  // _HasTypeSpecificResolution.
2004  template <class T>
2005  USD_API
2006  bool _GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2007  const TfToken& fieldName,
2008  const TfToken &keyPath,
2009  bool useFallbacks,
2010  T* result) const;
2011 
2012  template <class Composer>
2013  void _GetAttrTypeImpl(const UsdAttribute &attr,
2014  const TfToken &fieldName,
2015  bool useFallbacks,
2016  Composer *composer) const;
2017 
2018  template <class Composer>
2019  void _GetAttrVariabilityImpl(const UsdAttribute &attr,
2020  bool useFallbacks,
2021  Composer *composer) const;
2022 
2023  template <class Composer>
2024  void _GetPropCustomImpl(const UsdProperty &prop,
2025  bool useFallbacks,
2026  Composer *composer) const;
2027 
2028  template <class Composer>
2029  bool _GetSpecialPropMetadataImpl(const UsdObject &obj,
2030  const TfToken &fieldName,
2031  const TfToken &keyPath,
2032  bool useFallbacks,
2033  Composer *composer) const;
2034  template <class Composer>
2035  bool _GetMetadataImpl(const UsdObject &obj,
2036  const TfToken& fieldName,
2037  const TfToken& keyPath,
2038  bool includeFallbacks,
2039  Composer *composer) const;
2040 
2041  template <class Composer>
2042  bool _GetGeneralMetadataImpl(const UsdObject &obj,
2043  const TfToken& fieldName,
2044  const TfToken& keyPath,
2045  bool includeFallbacks,
2046  Composer *composer) const;
2047 
2048  // NOTE: The "authoredOnly" flag is not yet in use, but when we have
2049  // support for prim-based metadata fallbacks, they should be ignored when
2050  // this flag is set to true.
2051  bool _HasMetadata(const UsdObject &obj, const TfToken& fieldName,
2052  const TfToken &keyPath, bool useFallbacks) const;
2053 
2055  _ListMetadataFields(const UsdObject &obj, bool useFallbacks) const;
2056 
2057  void _GetAllMetadata(const UsdObject &obj,
2058  bool useFallbacks,
2060  bool anchorAssetPathsOnly = false) const;
2061 
2062  // --------------------------------------------------------------------- //
2063  // Default & TimeSample Resolution
2064  // --------------------------------------------------------------------- //
2065 
2066  void _GetResolveInfo(const UsdAttribute &attr,
2067  UsdResolveInfo *resolveInfo,
2068  const UsdTimeCode *time = nullptr) const;
2069 
2070  template <class T> struct _ExtraResolveInfo;
2071 
2072  template <class T>
2073  void _GetResolveInfo(const UsdAttribute &attr,
2074  UsdResolveInfo *resolveInfo,
2075  const UsdTimeCode *time = nullptr,
2076  _ExtraResolveInfo<T> *extraInfo = nullptr) const;
2077 
2078  template <class T> struct _ResolveInfoResolver;
2079  struct _PropertyStackResolver;
2080 
2081  template <class Resolver>
2082  void _GetResolvedValueImpl(const UsdProperty &prop,
2083  Resolver *resolver,
2084  const UsdTimeCode *time = nullptr) const;
2085 
2086  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2087  VtValue* result) const;
2088 
2089  template <class T>
2090  bool _GetValue(UsdTimeCode time, const UsdAttribute &attr,
2091  T* result) const;
2092 
2093  template <class T>
2094  bool _GetValueImpl(UsdTimeCode time, const UsdAttribute &attr,
2095  Usd_InterpolatorBase* interpolator,
2096  T* value) const;
2097 
2099  _GetLayerWithStrongestValue(
2100  UsdTimeCode time, const UsdAttribute &attr) const;
2101 
2102 
2103 
2104  USD_API
2105  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2106  UsdTimeCode time, const UsdAttribute &attr,
2107  VtValue* result) const;
2108 
2109  template <class T>
2110  USD_API
2111  bool _GetValueFromResolveInfo(const UsdResolveInfo &info,
2112  UsdTimeCode time, const UsdAttribute &attr,
2113  T* result) const;
2114 
2115  template <class T>
2116  bool _GetValueFromResolveInfoImpl(const UsdResolveInfo &info,
2117  UsdTimeCode time, const UsdAttribute &attr,
2118  Usd_InterpolatorBase* interpolator,
2119  T* value) const;
2120 
2121  // --------------------------------------------------------------------- //
2122  // Specialized Time Sample I/O
2123  // --------------------------------------------------------------------- //
2124 
2125  /// Gets the set of time samples authored for a given attribute
2126  /// within the \p interval. The interval may have any combination
2127  /// of open/infinite and closed/finite endpoints; it may not have
2128  /// open/finite endpoints, however, this restriction may be lifted
2129  /// in the future.
2130  /// Returns false on an error.
2131  bool _GetTimeSamplesInInterval(const UsdAttribute &attr,
2132  const GfInterval& interval,
2133  std::vector<double>* times) const;
2134 
2135  bool _GetTimeSamplesInIntervalFromResolveInfo(
2136  const UsdResolveInfo &info,
2137  const UsdAttribute &attr,
2138  const GfInterval& interval,
2139  std::vector<double>* times) const;
2140 
2141  size_t _GetNumTimeSamples(const UsdAttribute &attr) const;
2142 
2143  size_t _GetNumTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2144  const UsdAttribute &attr) const;
2145 
2146  /// Gets the bracketing times around a desiredTime. Only false on error
2147  /// or if no value exists (default or timeSamples). See
2148  /// UsdAttribute::GetBracketingTimeSamples for details.
2149  bool _GetBracketingTimeSamples(const UsdAttribute &attr,
2150  double desiredTime,
2151  bool authoredOnly,
2152  double* lower,
2153  double* upper,
2154  bool* hasSamples) const;
2155 
2156  bool _GetBracketingTimeSamplesFromResolveInfo(const UsdResolveInfo &info,
2157  const UsdAttribute &attr,
2158  double desiredTime,
2159  bool authoredOnly,
2160  double* lower,
2161  double* upper,
2162  bool* hasSamples) const;
2163 
2164  bool _ValueMightBeTimeVarying(const UsdAttribute &attr) const;
2165 
2166  bool _ValueMightBeTimeVaryingFromResolveInfo(const UsdResolveInfo &info,
2167  const UsdAttribute &attr) const;
2168 
2169  void _RegisterPerLayerNotices();
2170 
2171 private:
2172 
2173  // The 'pseudo root' prim.
2174  Usd_PrimDataPtr _pseudoRoot;
2175 
2176  // The stage's root layer.
2177  SdfLayerRefPtr _rootLayer;
2178 
2179  // Every UsdStage has an implicit, in-memory session layer.
2180  // This is to allow for runtime overrides such as variant selections.
2181  SdfLayerRefPtr _sessionLayer;
2182 
2183  // The stage's EditTarget.
2184  UsdEditTarget _editTarget;
2185 
2186  std::unique_ptr<PcpCache> _cache;
2187  std::unique_ptr<Usd_ClipCache> _clipCache;
2188  std::unique_ptr<Usd_InstanceCache> _instanceCache;
2189 
2190  TfHashMap<TfToken, TfToken, TfHash> _invalidPrimTypeToFallbackMap;
2191 
2192  // A map from Path to Prim, for fast random access.
2193  typedef TfHashMap<
2195  PathToNodeMap _primMap;
2196  mutable hboost::optional<tbb::spin_rw_mutex> _primMapMutex;
2197 
2198  // The interpolation type used for all attributes on the stage.
2199  UsdInterpolationType _interpolationType;
2200 
2201  typedef std::vector<
2202  std::pair<SdfLayerHandle, TfNotice::Key> > _LayerAndNoticeKeyVec;
2203  _LayerAndNoticeKeyVec _layersAndNoticeKeys;
2204  size_t _lastChangeSerialNumber;
2205 
2206  hboost::optional<WorkArenaDispatcher> _dispatcher;
2207 
2208  // To provide useful aggregation of malloc stats, we bill everything
2209  // for this stage - from all access points - to this tag.
2210  char const *_mallocTagID;
2211 
2212  // The state used when instantiating the stage.
2213  const InitialLoadSet _initialLoadSet;
2214 
2215  // The population mask that applies to this stage.
2216  UsdStagePopulationMask _populationMask;
2217 
2218  // The load rules that apply to this stage.
2219  UsdStageLoadRules _loadRules;
2220 
2221  bool _isClosingStage;
2222  bool _isWritingFallbackPrimTypes;
2223 
2224  friend class UsdAPISchemaBase;
2225  friend class UsdAttribute;
2226  friend class UsdAttributeQuery;
2227  friend class UsdEditTarget;
2228  friend class UsdInherits;
2229  friend class UsdObject;
2230  friend class UsdPrim;
2231  friend class UsdProperty;
2232  friend class UsdRelationship;
2233  friend class UsdSpecializes;
2234  friend class UsdVariantSet;
2235  friend class UsdVariantSets;
2236  friend class Usd_FlattenAccess;
2237  friend class Usd_PcpCacheAccess;
2238  friend class Usd_PrimData;
2239  friend class Usd_StageOpenRequest;
2240  template <class T> friend struct Usd_AttrGetValueHelper;
2242  template <class RefsOrPayloadsEditorType, class RefsOrPayloadsProxyType>
2243  friend struct Usd_ListEditImpl;
2244 };
2245 
2246 // UsdObject's typed metadata query relies on this specialization being
2247 // externally visible and exporting the primary template does not
2248 // automatically export this specialization.
2249 template <>
2250 USD_API
2251 bool
2252 UsdStage::_GetTypeSpecificResolvedMetadata(const UsdObject &obj,
2253  const TfToken& fieldName,
2254  const TfToken &keyPath,
2255  bool useFallbacks,
2256  SdfTimeSampleMap* result) const;
2257 
2258 template<typename T>
2259 bool
2261 {
2262  VtValue result;
2263  if (!GetMetadata(key, &result)){
2264  return false;
2265  }
2266 
2267  if (result.IsHolding<T>()){
2268  *value = result.UncheckedGet<T>();
2269  return true;
2270  } else {
2271  TF_CODING_ERROR("Requested type %s for stage metadatum %s does not"
2272  " match retrieved type %s",
2273  ArchGetDemangled<T>().c_str(),
2274  key.GetText(),
2275  result.GetTypeName().c_str());
2276  return false;
2277  }
2278 }
2279 
2280 template<typename T>
2281 bool
2282 UsdStage::SetMetadata(const TfToken& key, const T& value) const
2283 {
2284  VtValue in(value);
2285  return SetMetadata(key, in);
2286 }
2287 
2288 template<typename T>
2289 bool
2290 UsdStage::GetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2291  T* value) const
2292 {
2293  VtValue result;
2294  if (!GetMetadataByDictKey(key, keyPath, &result)){
2295  return false;
2296  }
2297 
2298  if (result.IsHolding<T>()){
2299  *value = result.UncheckedGet<T>();
2300  return true;
2301  } else {
2302  TF_CODING_ERROR("Requested type %s for stage metadatum %s[%s] does not"
2303  " match retrieved type %s",
2304  ArchGetDemangled<T>().c_str(),
2305  key.GetText(),
2306  keyPath.GetText(),
2307  result.GetTypeName().c_str());
2308  return false;
2309  }
2310 }
2311 
2312 template<typename T>
2313 bool
2314 UsdStage::SetMetadataByDictKey(const TfToken& key, const TfToken &keyPath,
2315  const T& value) const
2316 {
2317  VtValue in(value);
2318  return SetMetadataByDictKey(key, keyPath, in);
2319 }
2320 
2321 // Get metadata for types that do not have type specific value resolution.
2322 template <class T>
2323 typename std::enable_if<
2325 UsdStage::_GetMetadata(const UsdObject &obj,
2326  const TfToken& fieldName,
2327  const TfToken &keyPath,
2328  bool useFallbacks,
2329  T* result) const
2330 {
2331  // Since these types don't have type specific value resolution, we can just
2332  // get the strongest metadata value and be done.
2333  SdfAbstractDataTypedValue<T> out(result);
2334  return _GetStrongestResolvedMetadata(
2335  obj, fieldName, keyPath, useFallbacks, &out);
2336 }
2337 
2338 // Get metadata for types that do have type specific value resolution.
2339 template <class T>
2340 typename std::enable_if<
2342 UsdStage::_GetMetadata(const UsdObject &obj,
2343  const TfToken& fieldName,
2344  const TfToken &keyPath,
2345  bool useFallbacks,
2346  T* result) const
2347 {
2348  // Call the templated type specifice resolved metadata implementation that
2349  // will only be implemented for types that support it.
2350  return _GetTypeSpecificResolvedMetadata(
2351  obj, fieldName, keyPath, useFallbacks, result);
2352 }
2353 
2354 
2355 // Set metadata for types that don't need to be mapped across edit targets.
2356 template <class T>
2358 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2359  const TfToken &keyPath, const T& value)
2360 {
2361  // Since we know that we don't need to map the value for edit targets,
2362  // we can just type erase the value and set the metadata as is.
2364  return _SetMetadataImpl<SdfAbstractDataConstValue>(
2365  object, key, keyPath, in);
2366 }
2367 
2368 // Set metadata for types that do need to be mapped for edit targets.
2369 template <class T>
2371 UsdStage::_SetMetadata(const UsdObject &object, const TfToken& key,
2372  const TfToken &keyPath, const T& value)
2373 {
2374  return _SetEditTargetMappedMetadata(object, key, keyPath, value);
2375 }
2376 
2377 
2379 
2380 #endif //PXR_USD_USD_STAGE_H
2381 
Definition: layer.h:93
T const & UncheckedGet() const
Definition: value.h:1101
USD_API void ExpandPopulationMask(std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
GT_API const UT_StringHolder filename
USD_API void MuteAndUnmuteLayers(const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers)
virtual USD_API ~UsdStage()
static SDF_API const SdfPath & AbsoluteRootPath()
USD_API double GetFramesPerSecond() const
#define USD_API
Definition: api.h:40
USD_API bool HasDefaultPrim() const
USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const
USD_API void SetInterpolationType(UsdInterpolationType interpolationType)
hboost::math::policies::policy< hboost::math::policies::domain_error< hboost::math::policies::ignore_error >, hboost::math::policies::pole_error< hboost::math::policies::ignore_error >, hboost::math::policies::overflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::underflow_error< hboost::math::policies::ignore_error >, hboost::math::policies::denorm_error< hboost::math::policies::ignore_error >, hboost::math::policies::rounding_error< hboost::math::policies::ignore_error >, hboost::math::policies::evaluation_error< hboost::math::policies::ignore_error >, hboost::math::policies::indeterminate_result_error< hboost::math::policies::ignore_error > > policy
Definition: SYS_MathCbrt.h:35
USD_API void Save()
USD_API ArResolverContext GetPathResolverContext() const
USD_API double GetStartTimeCode() const
static USD_API UsdStageRefPtr CreateInMemory(InitialLoadSet load=LoadAll)
const Args & args
Definition: printf.h:628
USD_API bool HasMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
GT_API const UT_StringHolder time
USD_API std::vector< UsdPrim > GetMasters() const
Returns all master prims.
bool GetMetadata(const TfToken &key, T *value) const
Definition: stage.h:2260
USD_API UsdPrimRange Traverse()
USD_API bool Export(const std::string &filename, bool addSourceFileComment=true, const SdfLayer::FileFormatArguments &args=SdfLayer::FileFormatArguments()) const
SDF_DECLARE_HANDLES(SdfLayer)
std::map< std::string, std::string > FileFormatArguments
Definition: layer.h:119
USD_API UsdPrim CreateClassPrim(const SdfPath &rootPrimPath)
#define TF_CODING_ERROR
USD_API bool ClearMetadata(const TfToken &key) const
USD_API UsdRelationship GetRelationshipAtPath(const SdfPath &path) const
USD_API SdfPathSet GetLoadSet()
USD_API void Unload(const SdfPath &path=SdfPath::AbsoluteRootPath())
Definition: cache.h:91
Load a prim plus all its descendants.
Definition: common.h:118
USD_API bool IsLayerMuted(const std::string &layerIdentifier) const
USD_API void SetDefaultPrim(const UsdPrim &prim)
GLhandleARB obj
Definition: glew.h:6236
USD_API void WriteFallbackPrimTypes()
GLenum GLint GLuint mask
Definition: glew.h:1845
InitialLoadSet
Definition: stage.h:156
USD_API void MuteLayer(const std::string &layerIdentifier)
friend struct Usd_ListEditImpl
Definition: stage.h:2243
USD_API SdfPathSet FindLoadable(const SdfPath &rootPath=SdfPath::AbsoluteRootPath())
static USD_API void SetGlobalVariantFallbacks(const PcpVariantFallbackMap &fallbacks)
bool SetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, const T &value) const
Definition: stage.h:2314
hboost::intrusive_ptr< Usd_PrimData > Usd_PrimDataIPtr
USD_API const UsdEditTarget & GetEditTarget() const
Return the stage's EditTarget.
USD_API double GetEndTimeCode() const
USD_API SdfLayerRefPtr Flatten(bool addSourceFileComment=true) const
USD_API UsdPrim GetDefaultPrim() const
USD_API void SetColorConfiguration(const SdfAssetPath &colorConfig) const
USD_API TfToken GetColorManagementSystem() const
Definition: token.h:87
std::map< class TfToken, VtValue, TfDictionaryLessThan > UsdMetadataValueMap
Definition: common.h:81
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Definition: stage.h:2290
GLuint in
Definition: glew.h:11510
USD_API UsdEditTarget GetEditTargetForLocalLayer(size_t i)
GLenum GLint GLint GLint GLint GLuint dstName
Definition: glew.h:3901
USD_API SdfLayerHandleVector GetLayerStack(bool includeSessionLayers=true) const
USD_API void LoadAndUnload(const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
GLuint object
Definition: glew.h:8986
USD_API SdfLayerHandle GetSessionLayer() const
Return this stage's root session layer.
Definition: prim.h:132
USD_API bool HasAuthoredMetadataDictKey(const TfToken &key, const TfToken &keyPath) const
SdfSpecifier
Definition: types.h:123
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
USD_API bool HasAuthoredMetadata(const TfToken &key) const
std::vector< PcpErrorBasePtr > PcpErrorVector
Definition: errors.h:79
Definition: path.h:288
static USD_API UsdStageRefPtr CreateNew(const std::string &identifier, InitialLoadSet load=LoadAll)
USD_API UsdProperty GetPropertyAtPath(const SdfPath &path) const
USD_API bool RemovePrim(const SdfPath &path)
USD_API void SetColorManagementSystem(const TfToken &cms) const
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
char const * GetText() const
Definition: token.h:196
friend struct Usd_AttrGetValueHelper
Definition: stage.h:2240
static USD_API UsdStageRefPtr Open(const std::string &filePath, InitialLoadSet load=LoadAll)
bool SetMetadata(const TfToken &key, const T &value) const
Definition: stage.h:2282
GLuint start
Definition: glew.h:1253
USD_API bool HasAuthoredTimeCodeRange() const
USD_API void SetLoadRules(UsdStageLoadRules const &rules)
USD_API void SetEditTarget(const UsdEditTarget &editTarget)
USD_API bool HasMetadata(const TfToken &key) const
USD_API void SetFramesPerSecond(double framesPerSecond) const
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:207
SdfVariability
Definition: types.h:179
GLsizei const GLchar *const * path
Definition: glew.h:6461
USD_API bool HasLocalLayer(const SdfLayerHandle &layer) const
USD_API void UnmuteLayer(const std::string &layerIdentifier)
USD_API std::string ResolveIdentifierToEditTarget(std::string const &identifier) const
USD_API void SetEndTimeCode(double)
GLfloat GLfloat p
Definition: glew.h:16321
USD_API void Reload()
GLsizei const GLchar *const * string
Definition: glew.h:1844
USD_API UsdPrimRange TraverseAll()
USD_API void SetTimeCodesPerSecond(double timeCodesPerSecond) const
UsdLoadPolicy
Definition: common.h:116
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
USD_API void ClearDefaultPrim()
USD_API SdfLayerHandle GetRootLayer() const
Return this stage's root layer.
SdfSpecType
Definition: types.h:91
USD_API UsdInterpolationType GetInterpolationType() const
friend class Usd_FlattenAccess
Definition: stage.h:2236
static USD_API bool IsSupportedFile(const std::string &filePath)
friend class Usd_PcpCacheAccess
Definition: stage.h:2237
USD_API UsdObject GetObjectAtPath(const SdfPath &path) const
bool IsHolding() const
Definition: value.h:1073
UsdStageLoadRules const & GetLoadRules() const
Definition: stage.h:640
Load all loadable prims.
Definition: stage.h:158
friend struct Usd_AttrGetUntypedValueHelper
Definition: stage.h:2241
USD_API UsdPrim Load(const SdfPath &path=SdfPath::AbsoluteRootPath(), UsdLoadPolicy policy=UsdLoadWithDescendants)
GLint GLboolean GLint layer
Definition: glew.h:3601
static USD_API PcpVariantFallbackMap GetGlobalVariantFallbacks()
Get the global variant fallback preferences used in new UsdStages.
VT_API std::string GetTypeName() const
Return the type name of the held typeid.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API SdfAssetPath GetColorConfiguration() const
USD_API const std::vector< std::string > & GetMutedLayers() const
Returns a vector of all layers that have been muted on this stage.
USD_API UsdPrim GetPseudoRoot() const
friend class Usd_StageOpenRequest
Definition: stage.h:2239
UsdInterpolationType
Definition: interpolation.h:46
GLuint64EXT * result
Definition: glew.h:14007
USD_API UsdPrim DefinePrim(const SdfPath &path, const TfToken &typeName=TfToken())
UsdStagePopulationMask GetPopulationMask() const
Return this stage's population mask.
Definition: stage.h:657
USD_API UsdPrim OverridePrim(const SdfPath &path)
static USD_API void GetColorConfigFallbacks(SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
static USD_API UsdStageRefPtr OpenMasked(const std::string &filePath, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll)
USD_API double GetTimeCodesPerSecond() const
std::map< double, VtValue > SdfTimeSampleMap
A map from sample times to sample values.
Definition: types.h:276
USD_API void SetPopulationMask(UsdStagePopulationMask const &mask)
Set this stage's population mask and recompose the stage.
USD_API void SetStartTimeCode(double)
USD_API bool ClearMetadataByDictKey(const TfToken &key, const TfToken &keyPath) const
GLsizei const GLfloat * value
Definition: glew.h:1849
USD_API bool ExportToString(std::string *result, bool addSourceFileComment=true) const
Definition: value.h:174
USD_API void SaveSessionLayers()
static USD_API void SetColorConfigFallbacks(const SdfAssetPath &colorConfiguration, const TfToken &colorManagementSystem)
std::map< std::string, std::vector< std::string > > PcpVariantFallbackMap
Definition: types.h:188
USD_API SdfLayerHandleVector GetUsedLayers(bool includeClipLayers=true) const
USD_API UsdAttribute GetAttributeAtPath(const SdfPath &path) const
GLenum const void * paths
Definition: glew.h:13589
Load no loadable prims.
Definition: stage.h:159