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" 30 #include "pxr/base/tf/declarePtrs.h" 31 32 #include <memory> 33 #include <utility> 34 35 PXR_NAMESPACE_OPEN_SCOPE 36 37 38 TF_DECLARE_WEAK_PTRS(UsdStage); 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 /// 67 class UsdEditContext 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 98 ~UsdEditContext(); 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 108 PXR_NAMESPACE_CLOSE_SCOPE 109 110 #endif // PXR_USD_USD_EDIT_CONTEXT_H 111