HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
editContext.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_USD_USD_EDIT_CONTEXT_H
8 #define PXR_USD_USD_EDIT_CONTEXT_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/usd/usd/api.h"
12 #include "pxr/usd/usd/editTarget.h"
14 
15 #include <memory>
16 #include <utility>
17 
19 
20 
22 
23 /// \class UsdEditContext
24 ///
25 /// A utility class to temporarily modify a stage's current EditTarget during
26 /// an execution scope.
27 ///
28 /// This is an "RAII"-like object meant to be used as an automatic local
29 /// variable. Upon construction, it sets a given stage's EditTarget, and upon
30 /// destruction it restores the stage's EditTarget to what it was previously.
31 ///
32 /// Example usage, temporarily overriding a stage's EditTarget to direct an
33 /// edit to the stage's session layer. When the \a ctx object expires, it
34 /// restores the stage's EditTarget to whatever it was previously.
35 ///
36 /// \code
37 /// void SetVisState(const UsdPrim &prim, bool vis) {
38 /// UsdEditContext ctx(prim.GetStage(),
39 /// prim.GetStage()->GetSessionLayer());
40 /// prim.GetAttribute("visible").Set(vis);
41 /// }
42 /// \endcode
43 ///
44 /// <b>Threading Note</b>
45 ///
46 /// When one thread is mutating a \a UsdStage, it is unsafe for any other thread
47 /// to either query or mutate it. Using this class with a stage in such a way
48 /// that it modifies the stage's EditTarget constitutes a mutation.
49 ///
51 {
52  UsdEditContext(UsdEditContext const &) = delete;
53  UsdEditContext &operator=(UsdEditContext const &) = delete;
54 public:
55  /// Construct without modifying \a stage's current EditTarget. Save
56  /// \a stage's current EditTarget to restore on destruction.
57  ///
58  /// If \a stage is invalid, a coding error will be issued by the
59  /// constructor, and this class takes no action.
60  USD_API
61  explicit UsdEditContext(const UsdStagePtr &stage);
62 
63  /// Construct and save \a stage's current EditTarget to restore on
64  /// destruction, then invoke stage->SetEditTarget(editTarget).
65  ///
66  /// If \a stage is invalid, a coding error will be issued by the
67  /// constructor, and this class takes no action.
68  ///
69  /// If \a editTarget is invalid, a coding error will be issued by the
70  /// \a stage, and its EditTarget will not be modified.
71  USD_API
72  UsdEditContext(const UsdStagePtr &stage, const UsdEditTarget &editTarget);
73 
74  /// \overload
75  /// This ctor is handy to construct an edit context from the return
76  /// value of another function (Cannot return a UsdEditContext since it
77  /// needs to be noncopyable).
78  ///
79  /// If \a stage is invalid, a coding error will be issued by the
80  /// constructor, and this class takes no action.
81  ///
82  /// If \a editTarget is invalid, a coding error will be issued by the
83  /// \a stage, and its EditTarget will not be modified.
84  USD_API
85  UsdEditContext(const std::pair<UsdStagePtr, UsdEditTarget > &stageTarget);
86 
87  /// Restore the stage's original EditTarget if this context's stage is
88  /// valid. Otherwise do nothing.
89  USD_API
91 
92 private:
93  // The stage this context is bound to.
94  UsdStagePtr _stage;
95 
96  // The stage's original EditTarget.
97  UsdEditTarget _originalEditTarget;
98 };
99 
101 
102 #endif // PXR_USD_USD_EDIT_CONTEXT_H
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_PTRS(UsdStage)
#define USD_API
Definition: api.h:23
USD_API ~UsdEditContext()
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74