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 USDRI_GENERATED_MATERIALAPI_H 25 #define USDRI_GENERATED_MATERIALAPI_H 26 27 /// \file usdRi/materialAPI.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/usdRi/api.h" 31 #include "pxr/usd/usd/apiSchemaBase.h" 32 #include "pxr/usd/usd/prim.h" 33 #include "pxr/usd/usd/stage.h" 34 #include "pxr/usd/usdRi/tokens.h" 35 36 #include "pxr/usd/usdShade/input.h" 37 #include "pxr/usd/usdShade/output.h" 38 #include "pxr/usd/usdShade/material.h" 39 40 41 #include "pxr/base/vt/value.h" 42 43 #include "pxr/base/gf/vec3d.h" 44 #include "pxr/base/gf/vec3f.h" 45 #include "pxr/base/gf/matrix4d.h" 46 47 #include "pxr/base/tf/token.h" 48 #include "pxr/base/tf/type.h" 49 50 PXR_NAMESPACE_OPEN_SCOPE 51 52 class SdfAssetPath; 53 54 // -------------------------------------------------------------------------- // 55 // RIMATERIALAPI // 56 // -------------------------------------------------------------------------- // 57 58 /// \class UsdRiMaterialAPI 59 /// 60 /// 61 /// \deprecated Materials should use UsdShadeMaterial instead. 62 /// This schema will be removed in a future release. 63 /// 64 /// This API provides outputs that connect a material prim to prman 65 /// shaders and RIS objects. 66 /// 67 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below 68 /// that are text/tokens, the actual token is published and defined in \ref UsdRiTokens. 69 /// So to set an attribute to the value "rightHanded", use UsdRiTokens->rightHanded 70 /// as the value. 71 /// 72 class UsdRiMaterialAPI : public UsdAPISchemaBase 73 { 74 public: 75 /// Compile time constant representing what kind of schema this class is. 76 /// 77 /// \sa UsdSchemaKind 78 static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI; 79 80 /// Construct a UsdRiMaterialAPI on UsdPrim \p prim . 81 /// Equivalent to UsdRiMaterialAPI::Get(prim.GetStage(), prim.GetPath()) 82 /// for a \em valid \p prim, but will not immediately throw an error for 83 /// an invalid \p prim 84 explicit UsdRiMaterialAPI(const UsdPrim& prim=UsdPrim()) UsdAPISchemaBase(prim)85 : UsdAPISchemaBase(prim) 86 { 87 } 88 89 /// Construct a UsdRiMaterialAPI on the prim held by \p schemaObj . 90 /// Should be preferred over UsdRiMaterialAPI(schemaObj.GetPrim()), 91 /// as it preserves SchemaBase state. UsdRiMaterialAPI(const UsdSchemaBase & schemaObj)92 explicit UsdRiMaterialAPI(const UsdSchemaBase& schemaObj) 93 : UsdAPISchemaBase(schemaObj) 94 { 95 } 96 97 /// Destructor. 98 USDRI_API 99 virtual ~UsdRiMaterialAPI(); 100 101 /// Return a vector of names of all pre-declared attributes for this schema 102 /// class and all its ancestor classes. Does not include attributes that 103 /// may be authored by custom/extended methods of the schemas involved. 104 USDRI_API 105 static const TfTokenVector & 106 GetSchemaAttributeNames(bool includeInherited=true); 107 108 /// Return a UsdRiMaterialAPI holding the prim adhering to this 109 /// schema at \p path on \p stage. If no prim exists at \p path on 110 /// \p stage, or if the prim at that path does not adhere to this schema, 111 /// return an invalid schema object. This is shorthand for the following: 112 /// 113 /// \code 114 /// UsdRiMaterialAPI(stage->GetPrimAtPath(path)); 115 /// \endcode 116 /// 117 USDRI_API 118 static UsdRiMaterialAPI 119 Get(const UsdStagePtr &stage, const SdfPath &path); 120 121 122 /// Returns true if this <b>single-apply</b> API schema can be applied to 123 /// the given \p prim. If this schema can not be a applied to the prim, 124 /// this returns false and, if provided, populates \p whyNot with the 125 /// reason it can not be applied. 126 /// 127 /// Note that if CanApply returns false, that does not necessarily imply 128 /// that calling Apply will fail. Callers are expected to call CanApply 129 /// before calling Apply if they want to ensure that it is valid to 130 /// apply a schema. 131 /// 132 /// \sa UsdPrim::GetAppliedSchemas() 133 /// \sa UsdPrim::HasAPI() 134 /// \sa UsdPrim::CanApplyAPI() 135 /// \sa UsdPrim::ApplyAPI() 136 /// \sa UsdPrim::RemoveAPI() 137 /// 138 USDRI_API 139 static bool 140 CanApply(const UsdPrim &prim, std::string *whyNot=nullptr); 141 142 /// Applies this <b>single-apply</b> API schema to the given \p prim. 143 /// This information is stored by adding "RiMaterialAPI" to the 144 /// token-valued, listOp metadata \em apiSchemas on the prim. 145 /// 146 /// \return A valid UsdRiMaterialAPI object is returned upon success. 147 /// An invalid (or empty) UsdRiMaterialAPI object is returned upon 148 /// failure. See \ref UsdPrim::ApplyAPI() for conditions 149 /// resulting in failure. 150 /// 151 /// \sa UsdPrim::GetAppliedSchemas() 152 /// \sa UsdPrim::HasAPI() 153 /// \sa UsdPrim::CanApplyAPI() 154 /// \sa UsdPrim::ApplyAPI() 155 /// \sa UsdPrim::RemoveAPI() 156 /// 157 USDRI_API 158 static UsdRiMaterialAPI 159 Apply(const UsdPrim &prim); 160 161 protected: 162 /// Returns the kind of schema this class belongs to. 163 /// 164 /// \sa UsdSchemaKind 165 USDRI_API 166 UsdSchemaKind _GetSchemaKind() const override; 167 168 private: 169 // needs to invoke _GetStaticTfType. 170 friend class UsdSchemaRegistry; 171 USDRI_API 172 static const TfType &_GetStaticTfType(); 173 174 static bool _IsTypedSchema(); 175 176 // override SchemaBase virtuals. 177 USDRI_API 178 const TfType &_GetTfType() const override; 179 180 public: 181 // --------------------------------------------------------------------- // 182 // SURFACE 183 // --------------------------------------------------------------------- // 184 /// 185 /// 186 /// | || 187 /// | -- | -- | 188 /// | Declaration | `token outputs:ri:surface` | 189 /// | C++ Type | TfToken | 190 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 191 USDRI_API 192 UsdAttribute GetSurfaceAttr() const; 193 194 /// See GetSurfaceAttr(), and also 195 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 196 /// If specified, author \p defaultValue as the attribute's default, 197 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 198 /// the default for \p writeSparsely is \c false. 199 USDRI_API 200 UsdAttribute CreateSurfaceAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 201 202 public: 203 // --------------------------------------------------------------------- // 204 // DISPLACEMENT 205 // --------------------------------------------------------------------- // 206 /// 207 /// 208 /// | || 209 /// | -- | -- | 210 /// | Declaration | `token outputs:ri:displacement` | 211 /// | C++ Type | TfToken | 212 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 213 USDRI_API 214 UsdAttribute GetDisplacementAttr() const; 215 216 /// See GetDisplacementAttr(), and also 217 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 218 /// If specified, author \p defaultValue as the attribute's default, 219 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 220 /// the default for \p writeSparsely is \c false. 221 USDRI_API 222 UsdAttribute CreateDisplacementAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 223 224 public: 225 // --------------------------------------------------------------------- // 226 // VOLUME 227 // --------------------------------------------------------------------- // 228 /// 229 /// 230 /// | || 231 /// | -- | -- | 232 /// | Declaration | `token outputs:ri:volume` | 233 /// | C++ Type | TfToken | 234 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 235 USDRI_API 236 UsdAttribute GetVolumeAttr() const; 237 238 /// See GetVolumeAttr(), and also 239 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 240 /// If specified, author \p defaultValue as the attribute's default, 241 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 242 /// the default for \p writeSparsely is \c false. 243 USDRI_API 244 UsdAttribute CreateVolumeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 245 246 public: 247 // ===================================================================== // 248 // Feel free to add custom code below this line, it will be preserved by 249 // the code generator. 250 // 251 // Just remember to: 252 // - Close the class declaration with }; 253 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 254 // - Close the include guard with #endif 255 // ===================================================================== // 256 // --(BEGIN CUSTOM CODE)-- 257 258 /// A constructor for creating a MaterialAPI object from a material prim. UsdRiMaterialAPI(const UsdShadeMaterial & material)259 explicit UsdRiMaterialAPI(const UsdShadeMaterial& material) 260 : UsdRiMaterialAPI(material.GetPrim()) 261 { 262 } 263 264 // --------------------------------------------------------------------- // 265 /// \name Outputs API 266 // --------------------------------------------------------------------- // 267 /// @{ 268 269 /// Returns the "surface" output associated with the material. 270 USDRI_API 271 UsdShadeOutput GetSurfaceOutput() const; 272 273 /// Returns the "displacement" output associated with the material. 274 USDRI_API 275 UsdShadeOutput GetDisplacementOutput() const; 276 277 /// Returns the "volume" output associated with the material. 278 USDRI_API 279 UsdShadeOutput GetVolumeOutput() const; 280 281 /// @} 282 283 // --------------------------------------------------------------------- // 284 /// \name API for setting sources of outputs 285 // --------------------------------------------------------------------- // 286 /// @{ 287 288 USDRI_API 289 bool SetSurfaceSource(const SdfPath &surfacePath) const; 290 291 USDRI_API 292 bool SetDisplacementSource(const SdfPath &displacementPath) const; 293 294 USDRI_API 295 bool SetVolumeSource(const SdfPath &volumePath) const; 296 297 /// @} 298 299 // --------------------------------------------------------------------- // 300 /// \name Shaders API 301 // --------------------------------------------------------------------- // 302 /// @{ 303 304 /// Returns a valid shader object if the "surface" output on the 305 /// material is connected to one. 306 /// 307 /// If \p ignoreBaseMaterial is true and if the "surface" shader source 308 /// is specified in the base-material of this material, then this 309 /// returns an invalid shader object. 310 USDRI_API 311 UsdShadeShader GetSurface(bool ignoreBaseMaterial=false) const; 312 313 /// Returns a valid shader object if the "displacement" output on the 314 /// material is connected to one. 315 /// 316 /// If \p ignoreBaseMaterial is true and if the "displacement" shader source 317 /// is specified in the base-material of this material, then this 318 /// returns an invalid shader object. 319 USDRI_API 320 UsdShadeShader GetDisplacement(bool ignoreBaseMaterial=false) const; 321 322 /// Returns a valid shader object if the "volume" output on the 323 /// material is connected to one. 324 /// 325 /// If \p ignoreBaseMaterial is true and if the "volume" shader source 326 /// is specified in the base-material of this material, then this 327 /// returns an invalid shader object. 328 USDRI_API 329 UsdShadeShader GetVolume(bool ignoreBaseMaterial=false) const; 330 331 /// @} 332 333 334 /// Walks the namespace subtree below the material and computes a map 335 /// containing the list of all inputs on the material and the associated 336 /// vector of consumers of their values. The consumers can be inputs on 337 /// shaders within the material or on node-graphs under it. 338 USDRI_API 339 UsdShadeNodeGraph::InterfaceInputConsumersMap 340 ComputeInterfaceInputConsumersMap( 341 bool computeTransitiveConsumers=false) const; 342 343 /// @} 344 345 private: 346 UsdShadeShader _GetSourceShaderObject(const UsdShadeOutput &output, 347 bool ignoreBaseMaterial) const; 348 349 // Helper method to get the deprecated 'bxdf' output. 350 UsdShadeOutput _GetBxdfOutput(const UsdPrim &materialPrim) const; 351 }; 352 353 PXR_NAMESPACE_CLOSE_SCOPE 354 355 #endif 356