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_SDF_REFERENCE_H 25 #define PXR_USD_SDF_REFERENCE_H 26 27 /// \file sdf/reference.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/sdf/api.h" 31 #include "pxr/usd/sdf/assetPath.h" 32 #include "pxr/usd/sdf/layerOffset.h" 33 #include "pxr/usd/sdf/path.h" 34 #include "pxr/base/vt/dictionary.h" 35 #include "pxr/base/vt/value.h" 36 37 #include <boost/operators.hpp> 38 39 #include <iosfwd> 40 #include <string> 41 #include <vector> 42 43 PXR_NAMESPACE_OPEN_SCOPE 44 45 class SdfReference; 46 47 typedef std::vector<SdfReference> SdfReferenceVector; 48 49 /// \class SdfReference 50 /// 51 /// Represents a reference and all its meta data. 52 /// 53 /// A reference is expressed on a prim in a given layer and it identifies a 54 /// prim in a layer stack. All opinions in the namespace hierarchy 55 /// under the referenced prim will be composed with the opinions in the 56 /// namespace hierarchy under the referencing prim. 57 /// 58 /// The asset path specifies the layer stack being referenced. If this 59 /// asset path is non-empty, this reference is considered an 'external' 60 /// reference to the layer stack rooted at the specified layer. If this 61 /// is empty, this reference is considered an 'internal' reference to the 62 /// layer stack containing (but not necessarily rooted at) the layer where 63 /// the reference is authored. 64 /// 65 /// The prim path specifies the prim in the referenced layer stack from 66 /// which opinions will be composed. If this prim path is empty, it will 67 /// be considered a reference to the default prim specified in the root layer 68 /// of the referenced layer stack -- see SdfLayer::GetDefaultPrim. 69 /// 70 /// The meta data for a reference is its layer offset and custom data. The 71 /// layer offset is an affine transformation applied to all anim splines in 72 /// the referenced prim's namespace hierarchy, see SdfLayerOffset for details. 73 /// Custom data is for use by plugins or other non-tools supplied extensions 74 /// that need to be able to store data associated with references. 75 /// 76 class SdfReference : boost::totally_ordered<SdfReference> { 77 public: 78 /// Creates a reference with all its meta data. The default reference is an 79 /// internal reference to the default prim. See SdfAssetPath for what 80 /// characters are valid in \p assetPath. If \p assetPath contains invalid 81 /// characters, issue an error and set this reference's asset path to the 82 /// empty asset path. 83 /// 84 SDF_API SdfReference( 85 const std::string &assetPath = std::string(), 86 const SdfPath &primPath = SdfPath(), 87 const SdfLayerOffset &layerOffset = SdfLayerOffset(), 88 const VtDictionary &customData = VtDictionary()); 89 90 /// Returns the asset path to the root layer of the referenced layer 91 /// stack. This will be empty in the case of an internal reference. 92 /// GetAssetPath()93 const std::string &GetAssetPath() const { 94 return _assetPath; 95 } 96 97 /// Sets the asset path for the root layer of the referenced layer stack. 98 /// This may be set to an empty string to specify an internal reference. 99 /// See SdfAssetPath for what characters are valid in \p assetPath. If \p 100 /// assetPath contains invalid characters, issue an error and set this 101 /// reference's asset path to the empty asset path. SetAssetPath(const std::string & assetPath)102 void SetAssetPath(const std::string &assetPath) { 103 // Go through SdfAssetPath() to raise an error if \p assetPath contains 104 // illegal characters (i.e. control characters). 105 _assetPath = SdfAssetPath(assetPath).GetAssetPath(); 106 } 107 108 /// Returns the path of the referenced prim. 109 /// This will be empty if the referenced prim is the default prim specified 110 /// in the referenced layer stack. 111 /// GetPrimPath()112 const SdfPath &GetPrimPath() const { 113 return _primPath; 114 } 115 116 /// Sets the path of the referenced prim. 117 /// This may be set to an empty path to specify a reference to the default 118 /// prim in the referenced layer stack. 119 /// SetPrimPath(const SdfPath & primPath)120 void SetPrimPath(const SdfPath &primPath) { 121 _primPath = primPath; 122 } 123 124 /// Returns the layer offset associated with the reference. 125 /// GetLayerOffset()126 const SdfLayerOffset &GetLayerOffset() const { 127 return _layerOffset; 128 } 129 130 /// Sets a new layer offset. 131 /// SetLayerOffset(const SdfLayerOffset & layerOffset)132 void SetLayerOffset(const SdfLayerOffset &layerOffset) { 133 _layerOffset = layerOffset; 134 } 135 136 /// Returns the custom data associated with the reference. 137 /// GetCustomData()138 const VtDictionary &GetCustomData() const { 139 return _customData; 140 } 141 142 /// Sets the custom data associated with the reference. 143 /// SetCustomData(const VtDictionary & customData)144 void SetCustomData(const VtDictionary &customData) { 145 _customData = customData; 146 } 147 148 /// Sets a custom data entry for the reference. 149 /// 150 /// If \a value is empty, then this removes the given custom data entry. 151 /// 152 SDF_API void SetCustomData(const std::string &name, const VtValue &value); 153 154 /// Swaps the custom data dictionary for this reference. SwapCustomData(VtDictionary & customData)155 void SwapCustomData(VtDictionary &customData) { 156 _customData.swap(customData); 157 } 158 159 /// Returns \c true in the case of an internal reference. 160 /// 161 /// An internal reference is a reference with an empty asset path. 162 /// 163 SDF_API bool IsInternal() const; 164 hash_value(const SdfReference & r)165 friend inline size_t hash_value(const SdfReference &r) { 166 size_t h = 0; 167 boost::hash_combine(h, r._assetPath); 168 boost::hash_combine(h, r._primPath); 169 boost::hash_combine(h, r._layerOffset); 170 boost::hash_combine(h, r._customData); 171 return h; 172 } 173 174 /// Returns whether this reference equals \a rhs. 175 SDF_API bool operator==(const SdfReference &rhs) const; 176 177 /// Returns whether this reference is less than \a rhs. The meaning 178 /// of less than is somewhat arbitrary. 179 SDF_API bool operator<(const SdfReference &rhs) const; 180 181 /// Struct that defines equality of SdfReferences based on their 182 /// identity (the asset path and prim path). 183 /// 184 struct IdentityEqual { operatorIdentityEqual185 bool operator()(const SdfReference &lhs, const SdfReference &rhs) const { 186 return lhs._assetPath == rhs._assetPath && 187 lhs._primPath == rhs._primPath; 188 } 189 }; 190 191 /// Struct that defines a strict weak ordering of SdfReferences based on 192 /// their identity (the asset path and prim path). 193 /// 194 struct IdentityLessThan { operatorIdentityLessThan195 bool operator()(const SdfReference &lhs, const SdfReference &rhs) const { 196 return lhs._assetPath < rhs._assetPath || 197 (lhs._assetPath == rhs._assetPath && 198 lhs._primPath < rhs._primPath); 199 } 200 }; 201 202 private: 203 // The asset path to the external layer. 204 std::string _assetPath; 205 206 // The path to the referenced prim in the external layer. 207 SdfPath _primPath; 208 209 // The layer offset to transform time. 210 SdfLayerOffset _layerOffset; 211 212 // The custom data associated with the reference. 213 VtDictionary _customData; 214 }; 215 216 /// Convenience function to find the index of the reference in \a references 217 /// that has the same identity as the given reference \a referenceId. 218 /// 219 /// A reference's identity is given by its asset path and prim path alone 220 /// (i.e. the layer offset and custom data is ignored). 221 /// 222 /// If no reference with the same identity exists in \a reference, -1 is 223 /// returned. If more than one reference with the same identity exist in 224 /// \a references the index of the first one is returned. 225 /// 226 SDF_API int SdfFindReferenceByIdentity( 227 const SdfReferenceVector &references, 228 const SdfReference &referenceId); 229 230 /// Writes the string representation of \a SdfReference to \a out. 231 SDF_API std::ostream & operator<<( std::ostream &out, 232 const SdfReference &reference ); 233 234 PXR_NAMESPACE_CLOSE_SCOPE 235 236 #endif // PXR_USD_SDF_REFERENCE_H 237