1 // 2 // Copyright 2019 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_PAYLOADS_H 25 #define PXR_USD_USD_PAYLOADS_H 26 27 #include "pxr/pxr.h" 28 #include "pxr/usd/usd/api.h" 29 #include "pxr/usd/usd/common.h" 30 #include "pxr/usd/usd/prim.h" 31 32 #include "pxr/usd/sdf/declareHandles.h" 33 #include "pxr/usd/sdf/path.h" 34 #include "pxr/usd/sdf/payload.h" 35 36 PXR_NAMESPACE_OPEN_SCOPE 37 38 /// \class UsdPayloads 39 /// 40 /// UsdPayloads provides an interface to authoring and introspecting payloads. 41 /// Payloads behave the same as Usd references except that payloads can be 42 /// optionally loaded. 43 class UsdPayloads { 44 friend class UsdPrim; 45 UsdPayloads(const UsdPrim & prim)46 explicit UsdPayloads(const UsdPrim& prim) : _prim(prim) {} 47 48 public: 49 /// Adds a payload to the payload listOp at the current EditTarget, in the 50 /// position specified by \p position. 51 /// \sa \ref Usd_Failing_References "Why adding references may fail" for 52 /// explanation of expectations on \p payload and what return values and 53 /// errors to expect, and \ref Usd_OM_ListOps for details on list editing 54 /// and composition of listOps. 55 USD_API 56 bool AddPayload(const SdfPayload& payload, 57 UsdListPosition position=UsdListPositionBackOfPrependList); 58 59 /// \overload 60 USD_API 61 bool AddPayload(const std::string &identifier, 62 const SdfPath &primPath, 63 const SdfLayerOffset &layerOffset = SdfLayerOffset(), 64 UsdListPosition position=UsdListPositionBackOfPrependList); 65 66 /// \overload 67 /// \sa \ref Usd_DefaultPrim_References "Payloads Without Prim Paths" 68 USD_API 69 bool AddPayload(const std::string &identifier, 70 const SdfLayerOffset &layerOffset = SdfLayerOffset(), 71 UsdListPosition position=UsdListPositionBackOfPrependList); 72 73 /// Add an internal payload to the specified prim. 74 /// \sa \ref Usd_Internal_References "Internal Payloads" 75 USD_API 76 bool AddInternalPayload(const SdfPath &primPath, 77 const SdfLayerOffset &layerOffset = SdfLayerOffset(), 78 UsdListPosition position=UsdListPositionBackOfPrependList); 79 80 /// Removes the specified payload from the payloads listOp at the 81 /// current EditTarget. This does not necessarily eliminate the payload 82 /// completely, as it may be added or set in another layer in the same 83 /// LayerStack as the current EditTarget. 84 /// \sa \ref Usd_OM_ListOps 85 USD_API 86 bool RemovePayload(const SdfPayload& ref); 87 88 /// Removes the authored payload listOp edits at the current EditTarget. 89 /// The same caveats for Remove() apply to Clear(). In fact, Clear() may 90 /// actually increase the number of composed payloads, if the listOp being 91 /// cleared contained the "remove" operator. 92 /// \sa \ref Usd_OM_ListOps 93 USD_API 94 bool ClearPayloads(); 95 96 /// Explicitly set the payloads, potentially blocking weaker opinions that 97 /// add or remove items. 98 /// \sa \ref Usd_Failing_References "Why adding payloads may fail" for 99 /// explanation of expectations on \p items and what return values and 100 /// errors to expect, and \ref Usd_OM_ListOps for details on list editing 101 /// and composition of listOps. 102 USD_API 103 bool SetPayloads(const SdfPayloadVector& items); 104 105 /// Return the prim this object is bound to. GetPrim()106 const UsdPrim &GetPrim() const { return _prim; } 107 108 /// \overload GetPrim()109 UsdPrim GetPrim() { return _prim; } 110 111 explicit operator bool() { return bool(_prim); } 112 113 private: 114 UsdPrim _prim; 115 }; 116 117 PXR_NAMESPACE_CLOSE_SCOPE 118 119 #endif // PXR_USD_USD_PAYLOADS_H 120