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 Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_EDIT_CONTEXT_H
25 #define PXR_USD_USD_EDIT_CONTEXT_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/usd/editTarget.h"
31 
32 #include <memory>
33 #include <utility>
34 
36 
37 
39 
40 /// \class UsdEditContext
41 ///
42 /// A utility class to temporarily modify a stage's current EditTarget during
43 /// an execution scope.
44 ///
45 /// This is an "RAII"-like object meant to be used as an automatic local
46 /// variable. Upon construction, it sets a given stage's EditTarget, and upon
47 /// destruction it restores the stage's EditTarget to what it was previously.
48 ///
49 /// Example usage, temporarily overriding a stage's EditTarget to direct an
50 /// edit to the stage's session layer. When the \a ctx object expires, it
51 /// restores the stage's EditTarget to whatever it was previously.
52 ///
53 /// \code
54 /// void SetVisState(const UsdPrim &prim, bool vis) {
55 /// UsdEditContext ctx(prim.GetStage(),
56 /// prim.GetStage()->GetSessionLayer());
57 /// prim.GetAttribute("visible").Set(vis);
58 /// }
59 /// \endcode
60 ///
61 /// <b>Threading Note</b>
62 ///
63 /// When one thread is mutating a \a UsdStage, it is unsafe for any other thread
64 /// to either query or mutate it. Using this class with a stage in such a way
65 /// that it modifies the stage's EditTarget constitutes a mutation.
66 ///
68 {
69  UsdEditContext(UsdEditContext const &) = delete;
70  UsdEditContext &operator=(UsdEditContext const &) = delete;
71 public:
72  /// Construct without modifying \a stage's current EditTarget. Save
73  /// \a stage's current EditTarget to restore on destruction.
74  USD_API
75  explicit UsdEditContext(const UsdStagePtr &stage);
76 
77  /// Construct and save \a stage's current EditTarget to restore on
78  /// destruction, then invoke stage->SetEditTarget(editTarget).
79  ///
80  /// If \a editTarget is invalid, a coding error will be issued by the
81  /// \a stage, and its EditTarget will not be modified.
82  USD_API
83  UsdEditContext(const UsdStagePtr &stage, const UsdEditTarget &editTarget);
84 
85  /// \overload
86  /// This ctor is handy to construct an edit context from the return
87  /// value of another function (Cannot return a UsdEditContext since it
88  /// needs to be noncopyable).
89  ///
90  /// If \a editTarget is invalid, a coding error will be issued by the
91  /// \a stage, and its EditTarget will not be modified.
92  USD_API
93  UsdEditContext(const std::pair<UsdStagePtr, UsdEditTarget > &stageTarget);
94 
95  /// Restore the stage's original EditTarget if this context's stage is
96  /// valid. Otherwise do nothing.
97  USD_API
99 
100 private:
101  // The stage this context is bound to.
102  UsdStagePtr _stage;
103 
104  // The stage's original EditTarget.
105  UsdEditTarget _originalEditTarget;
106 };
107 
109 
110 #endif // PXR_USD_USD_EDIT_CONTEXT_H
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_PTRS(UsdStage)
#define USD_API
Definition: api.h:40
USD_API ~UsdEditContext()
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91