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 USDVOL_GENERATED_VOLUME_H 25 #define USDVOL_GENERATED_VOLUME_H 26 27 /// \file usdVol/volume.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/usdVol/api.h" 31 #include "pxr/usd/usdGeom/gprim.h" 32 #include "pxr/usd/usd/prim.h" 33 #include "pxr/usd/usd/stage.h" 34 35 #include "pxr/base/vt/value.h" 36 37 #include "pxr/base/gf/vec3d.h" 38 #include "pxr/base/gf/vec3f.h" 39 #include "pxr/base/gf/matrix4d.h" 40 41 #include "pxr/base/tf/token.h" 42 #include "pxr/base/tf/type.h" 43 44 PXR_NAMESPACE_OPEN_SCOPE 45 46 class SdfAssetPath; 47 48 // -------------------------------------------------------------------------- // 49 // VOLUME // 50 // -------------------------------------------------------------------------- // 51 52 /// \class UsdVolVolume 53 /// 54 /// A renderable volume primitive. A volume is made up of any number 55 /// of FieldBase primitives bound together in this volume. Each 56 /// FieldBase primitive is specified as a relationship with a 57 /// namespace prefix of "field". 58 /// 59 /// The relationship name is used by the renderer to associate 60 /// individual fields with the named input parameters on the volume 61 /// shader. Using this indirect approach to connecting fields to 62 /// shader parameters (rather than using the field prim's name) 63 /// allows a single field to be reused for different shader inputs, or 64 /// to be used as different shader parameters when rendering different 65 /// Volumes. This means that the name of the field prim is not 66 /// relevant to its contribution to the volume prims which refer to 67 /// it. Nor does the field prim's location in the scene graph have 68 /// any relevance, and Volumes may refer to fields anywhere in the 69 /// scene graph. **However**, unless Field prims need to be shared 70 /// by multiple Volumes, a Volume's Field prims should be located 71 /// under the Volume in namespace, for enhanced organization. 72 /// 73 class UsdVolVolume : public UsdGeomGprim 74 { 75 public: 76 /// Compile time constant representing what kind of schema this class is. 77 /// 78 /// \sa UsdSchemaKind 79 static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped; 80 81 /// Construct a UsdVolVolume on UsdPrim \p prim . 82 /// Equivalent to UsdVolVolume::Get(prim.GetStage(), prim.GetPath()) 83 /// for a \em valid \p prim, but will not immediately throw an error for 84 /// an invalid \p prim 85 explicit UsdVolVolume(const UsdPrim& prim=UsdPrim()) UsdGeomGprim(prim)86 : UsdGeomGprim(prim) 87 { 88 } 89 90 /// Construct a UsdVolVolume on the prim held by \p schemaObj . 91 /// Should be preferred over UsdVolVolume(schemaObj.GetPrim()), 92 /// as it preserves SchemaBase state. UsdVolVolume(const UsdSchemaBase & schemaObj)93 explicit UsdVolVolume(const UsdSchemaBase& schemaObj) 94 : UsdGeomGprim(schemaObj) 95 { 96 } 97 98 /// Destructor. 99 USDVOL_API 100 virtual ~UsdVolVolume(); 101 102 /// Return a vector of names of all pre-declared attributes for this schema 103 /// class and all its ancestor classes. Does not include attributes that 104 /// may be authored by custom/extended methods of the schemas involved. 105 USDVOL_API 106 static const TfTokenVector & 107 GetSchemaAttributeNames(bool includeInherited=true); 108 109 /// Return a UsdVolVolume holding the prim adhering to this 110 /// schema at \p path on \p stage. If no prim exists at \p path on 111 /// \p stage, or if the prim at that path does not adhere to this schema, 112 /// return an invalid schema object. This is shorthand for the following: 113 /// 114 /// \code 115 /// UsdVolVolume(stage->GetPrimAtPath(path)); 116 /// \endcode 117 /// 118 USDVOL_API 119 static UsdVolVolume 120 Get(const UsdStagePtr &stage, const SdfPath &path); 121 122 /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path 123 /// is defined (according to UsdPrim::IsDefined()) on this stage. 124 /// 125 /// If a prim adhering to this schema at \p path is already defined on this 126 /// stage, return that prim. Otherwise author an \a SdfPrimSpec with 127 /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for 128 /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s 129 /// with \p specifier == \a SdfSpecifierDef and empty typeName at the 130 /// current EditTarget for any nonexistent, or existing but not \a Defined 131 /// ancestors. 132 /// 133 /// The given \a path must be an absolute prim path that does not contain 134 /// any variant selections. 135 /// 136 /// If it is impossible to author any of the necessary PrimSpecs, (for 137 /// example, in case \a path cannot map to the current UsdEditTarget's 138 /// namespace) issue an error and return an invalid \a UsdPrim. 139 /// 140 /// Note that this method may return a defined prim whose typeName does not 141 /// specify this schema class, in case a stronger typeName opinion overrides 142 /// the opinion at the current EditTarget. 143 /// 144 USDVOL_API 145 static UsdVolVolume 146 Define(const UsdStagePtr &stage, const SdfPath &path); 147 148 protected: 149 /// Returns the kind of schema this class belongs to. 150 /// 151 /// \sa UsdSchemaKind 152 USDVOL_API 153 UsdSchemaKind _GetSchemaKind() const override; 154 155 private: 156 // needs to invoke _GetStaticTfType. 157 friend class UsdSchemaRegistry; 158 USDVOL_API 159 static const TfType &_GetStaticTfType(); 160 161 static bool _IsTypedSchema(); 162 163 // override SchemaBase virtuals. 164 USDVOL_API 165 const TfType &_GetTfType() const override; 166 167 public: 168 // ===================================================================== // 169 // Feel free to add custom code below this line, it will be preserved by 170 // the code generator. 171 // 172 // Just remember to: 173 // - Close the class declaration with }; 174 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 175 // - Close the include guard with #endif 176 // ===================================================================== // 177 // --(BEGIN CUSTOM CODE)-- 178 179 // --------------------------------------------------------------------- // 180 /// \name Field Attachment and Inspection 181 /// @{ 182 // --------------------------------------------------------------------- // 183 184 typedef std::map<TfToken, SdfPath> FieldMap; 185 186 /// Return a map of field relationship names to the fields themselves, 187 /// represented as prim paths. This map provides all the information 188 /// that should be needed to tie fields to shader parameters and render 189 /// this volume. 190 /// 191 /// The field relationship names that server as the map keys will have 192 /// the field namespace stripped from them. 193 USDVOL_API 194 FieldMap GetFieldPaths() const; 195 196 /// Checks if there is an existing field relationship with a given name. 197 /// This query will return \c true even for a field relationship that 198 /// has been blocked and therefore will not contribute to the map 199 /// returned by GetFieldRelationships() 200 /// 201 /// The name lookup automatically applies the field relationship 202 /// namespacing, if it isn't specified in the name token. 203 USDVOL_API 204 bool HasFieldRelationship(const TfToken &name) const; 205 206 /// Checks if there is an existing field relationship with a given name, 207 /// and if so, returns the path to the Field prim it targets, or else 208 /// the empty path. 209 /// 210 /// The name lookup automatically applies the field relationship 211 /// namespacing, if it isn't specified in the name token. 212 USDVOL_API 213 SdfPath GetFieldPath(const TfToken &name) const; 214 215 /// Creates a relationship on this volume that targets the specified field. 216 /// If an existing relationship exists with the same name, it is replaced 217 /// (since only one target is allowed for each named relationship). 218 /// 219 /// Returns \c true if the relationship was successfully created and set - 220 /// it is legal to call this method for a field relationship that already 221 /// "exists", i.e. already posesses scene description, as this is the 222 /// only method we provide for setting a field relatioonship's value, to help 223 /// enforce that field relationships can have only a single (or no) target. 224 /// 225 /// \param fieldPath - can be a prim path, or the path of another 226 /// relationship, to effect \ref usd_relationship_forwarding 227 /// 228 /// The name lookup automatically applies the field relationship 229 /// namespacing, if it isn't specified in the name token. 230 USDVOL_API 231 bool CreateFieldRelationship(const TfToken &name, 232 const SdfPath &fieldPath) const; 233 234 /// Blocks an existing field relationship on this volume, ensuring it 235 /// will not be enumerated by GetFieldPaths(). 236 /// 237 /// Returns true if the relationship existed, false if it did not. In other 238 /// words the return value indicates whether the volume prim was changed. 239 /// 240 /// The name lookup automatically applies the field relationship 241 /// namespacing, if it isn't specified in the name token. 242 USDVOL_API 243 bool BlockFieldRelationship(const TfToken &name) const; 244 245 private: 246 /// Return \p name prepended with the field namespace, if it isn't 247 /// already prefixed. 248 /// 249 /// Does not validate name as a legal relationship identifier. 250 static TfToken _MakeNamespaced(const TfToken& name); 251 }; 252 253 PXR_NAMESPACE_CLOSE_SCOPE 254 255 #endif 256