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