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 USDLUX_GENERATED_LIGHTFILTER_H 25 #define USDLUX_GENERATED_LIGHTFILTER_H 26 27 /// \file usdLux/lightFilter.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/usdLux/api.h" 31 #include "pxr/usd/usdGeom/xformable.h" 32 #include "pxr/usd/usd/prim.h" 33 #include "pxr/usd/usd/stage.h" 34 #include "pxr/usd/usdLux/tokens.h" 35 36 #include "pxr/usd/usd/collectionAPI.h" 37 #include "pxr/usd/usdShade/input.h" 38 #include "pxr/usd/usdShade/output.h" 39 40 #include "pxr/base/vt/value.h" 41 42 #include "pxr/base/gf/vec3d.h" 43 #include "pxr/base/gf/vec3f.h" 44 #include "pxr/base/gf/matrix4d.h" 45 46 #include "pxr/base/tf/token.h" 47 #include "pxr/base/tf/type.h" 48 49 PXR_NAMESPACE_OPEN_SCOPE 50 51 class SdfAssetPath; 52 53 // -------------------------------------------------------------------------- // 54 // LIGHTFILTER // 55 // -------------------------------------------------------------------------- // 56 57 /// \class UsdLuxLightFilter 58 /// 59 /// A light filter modifies the effect of a light. 60 /// Lights refer to filters via relationships so that filters may be 61 /// shared. 62 /// 63 /// <b>Linking</b> 64 /// 65 /// Filters can be linked to geometry. Linking controls which geometry 66 /// a light-filter affects, when considering the light filters attached 67 /// to a light illuminating the geometry. 68 /// 69 /// Linking is specified as a collection (UsdCollectionAPI) which can 70 /// be accessed via GetFilterLinkCollection(). 71 /// 72 /// 73 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below 74 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens. 75 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded 76 /// as the value. 77 /// 78 class UsdLuxLightFilter : public UsdGeomXformable 79 { 80 public: 81 /// Compile time constant representing what kind of schema this class is. 82 /// 83 /// \sa UsdSchemaKind 84 static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped; 85 86 /// Construct a UsdLuxLightFilter on UsdPrim \p prim . 87 /// Equivalent to UsdLuxLightFilter::Get(prim.GetStage(), prim.GetPath()) 88 /// for a \em valid \p prim, but will not immediately throw an error for 89 /// an invalid \p prim 90 explicit UsdLuxLightFilter(const UsdPrim& prim=UsdPrim()) UsdGeomXformable(prim)91 : UsdGeomXformable(prim) 92 { 93 } 94 95 /// Construct a UsdLuxLightFilter on the prim held by \p schemaObj . 96 /// Should be preferred over UsdLuxLightFilter(schemaObj.GetPrim()), 97 /// as it preserves SchemaBase state. UsdLuxLightFilter(const UsdSchemaBase & schemaObj)98 explicit UsdLuxLightFilter(const UsdSchemaBase& schemaObj) 99 : UsdGeomXformable(schemaObj) 100 { 101 } 102 103 /// Destructor. 104 USDLUX_API 105 virtual ~UsdLuxLightFilter(); 106 107 /// Return a vector of names of all pre-declared attributes for this schema 108 /// class and all its ancestor classes. Does not include attributes that 109 /// may be authored by custom/extended methods of the schemas involved. 110 USDLUX_API 111 static const TfTokenVector & 112 GetSchemaAttributeNames(bool includeInherited=true); 113 114 /// Return a UsdLuxLightFilter holding the prim adhering to this 115 /// schema at \p path on \p stage. If no prim exists at \p path on 116 /// \p stage, or if the prim at that path does not adhere to this schema, 117 /// return an invalid schema object. This is shorthand for the following: 118 /// 119 /// \code 120 /// UsdLuxLightFilter(stage->GetPrimAtPath(path)); 121 /// \endcode 122 /// 123 USDLUX_API 124 static UsdLuxLightFilter 125 Get(const UsdStagePtr &stage, const SdfPath &path); 126 127 /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path 128 /// is defined (according to UsdPrim::IsDefined()) on this stage. 129 /// 130 /// If a prim adhering to this schema at \p path is already defined on this 131 /// stage, return that prim. Otherwise author an \a SdfPrimSpec with 132 /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for 133 /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s 134 /// with \p specifier == \a SdfSpecifierDef and empty typeName at the 135 /// current EditTarget for any nonexistent, or existing but not \a Defined 136 /// ancestors. 137 /// 138 /// The given \a path must be an absolute prim path that does not contain 139 /// any variant selections. 140 /// 141 /// If it is impossible to author any of the necessary PrimSpecs, (for 142 /// example, in case \a path cannot map to the current UsdEditTarget's 143 /// namespace) issue an error and return an invalid \a UsdPrim. 144 /// 145 /// Note that this method may return a defined prim whose typeName does not 146 /// specify this schema class, in case a stronger typeName opinion overrides 147 /// the opinion at the current EditTarget. 148 /// 149 USDLUX_API 150 static UsdLuxLightFilter 151 Define(const UsdStagePtr &stage, const SdfPath &path); 152 153 protected: 154 /// Returns the kind of schema this class belongs to. 155 /// 156 /// \sa UsdSchemaKind 157 USDLUX_API 158 UsdSchemaKind _GetSchemaKind() const override; 159 160 private: 161 // needs to invoke _GetStaticTfType. 162 friend class UsdSchemaRegistry; 163 USDLUX_API 164 static const TfType &_GetStaticTfType(); 165 166 static bool _IsTypedSchema(); 167 168 // override SchemaBase virtuals. 169 USDLUX_API 170 const TfType &_GetTfType() const override; 171 172 public: 173 // --------------------------------------------------------------------- // 174 // SHADERID 175 // --------------------------------------------------------------------- // 176 /// Default ID for the light filter's shader. 177 /// This defines the shader ID for this light filter when a render context 178 /// specific shader ID is not available. 179 /// 180 /// \see GetShaderId 181 /// \see GetShaderIdAttrForRenderContext 182 /// \see SdrRegistry::GetShaderNodeByIdentifier 183 /// \see SdrRegistry::GetShaderNodeByIdentifierAndType 184 /// 185 /// 186 /// | || 187 /// | -- | -- | 188 /// | Declaration | `uniform token lightFilter:shaderId = ""` | 189 /// | C++ Type | TfToken | 190 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 191 /// | \ref SdfVariability "Variability" | SdfVariabilityUniform | 192 USDLUX_API 193 UsdAttribute GetShaderIdAttr() const; 194 195 /// See GetShaderIdAttr(), and also 196 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 197 /// If specified, author \p defaultValue as the attribute's default, 198 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 199 /// the default for \p writeSparsely is \c false. 200 USDLUX_API 201 UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 202 203 public: 204 // ===================================================================== // 205 // Feel free to add custom code below this line, it will be preserved by 206 // the code generator. 207 // 208 // Just remember to: 209 // - Close the class declaration with }; 210 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 211 // - Close the include guard with #endif 212 // ===================================================================== // 213 // --(BEGIN CUSTOM CODE)-- 214 215 // ------------------------------------------------------------------------- 216 /// \name Conversion to and from UsdShadeConnectableAPI 217 /// 218 /// @{ 219 220 /// Constructor that takes a ConnectableAPI object. 221 /// Allow implicit conversion of UsdShadeConnectableAPI to 222 /// UsdLuxLightFilter. 223 USDLUX_API 224 UsdLuxLightFilter(const UsdShadeConnectableAPI &connectable); 225 226 /// Contructs and returns a UsdShadeConnectableAPI object with this light 227 /// filter. 228 /// 229 /// Note that most tasks can be accomplished without explicitly constructing 230 /// a UsdShadeConnectable API, since connection-related API such as 231 /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and 232 /// UsdLuxLightFilter will auto-convert to a UsdShadeConnectableAPI when 233 /// passed to functions that want to act generically on a connectable 234 /// UsdShadeConnectableAPI object. 235 USDLUX_API 236 UsdShadeConnectableAPI ConnectableAPI() const; 237 238 /// @} 239 240 // ------------------------------------------------------------------------- 241 /// \name Outputs API 242 /// 243 /// Outputs represent a typed attribute on a light filter whose value is 244 /// computed externally. 245 /// 246 /// @{ 247 248 /// Create an output which can either have a value or can be connected. 249 /// The attribute representing the output is created in the "outputs:" 250 /// namespace. Outputs on a light filter cannot be connected, as their 251 /// value is assumed to be computed externally. 252 /// 253 USDLUX_API 254 UsdShadeOutput CreateOutput(const TfToken& name, 255 const SdfValueTypeName& typeName); 256 257 /// Return the requested output if it exists. 258 /// 259 USDLUX_API 260 UsdShadeOutput GetOutput(const TfToken &name) const; 261 262 /// Outputs are represented by attributes in the "outputs:" namespace. 263 /// If \p onlyAuthored is true (the default), then only return authored 264 /// attributes; otherwise, this also returns un-authored builtins. 265 /// 266 USDLUX_API 267 std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored=true) const; 268 269 /// @} 270 271 // ------------------------------------------------------------------------- 272 273 /// \name Inputs API 274 /// 275 /// Inputs are connectable attribute with a typed value. 276 /// 277 /// Light filter parameters are encoded as inputs. 278 /// 279 /// @{ 280 281 /// Create an input which can either have a value or can be connected. 282 /// The attribute representing the input is created in the "inputs:" 283 /// namespace. Inputs on light filters are connectable. 284 /// 285 USDLUX_API 286 UsdShadeInput CreateInput(const TfToken& name, 287 const SdfValueTypeName& typeName); 288 289 /// Return the requested input if it exists. 290 /// 291 USDLUX_API 292 UsdShadeInput GetInput(const TfToken &name) const; 293 294 /// Inputs are represented by attributes in the "inputs:" namespace. 295 /// If \p onlyAuthored is true (the default), then only return authored 296 /// attributes; otherwise, this also returns un-authored builtins. 297 /// 298 USDLUX_API 299 std::vector<UsdShadeInput> GetInputs(bool onlyAuthored=true) const; 300 301 /// @} 302 303 /// Return the UsdCollectionAPI interface used for examining and 304 /// modifying the filter-linking of this light filter. Linking 305 /// controls which geometry this light filter affects. 306 USDLUX_API 307 UsdCollectionAPI GetFilterLinkCollectionAPI() const; 308 309 /// Returns the shader ID attribute for the given \p renderContext. 310 /// 311 /// If \p renderContext is non-empty, this will try to return an attribute 312 /// named _lightFilter:shaderId_ with the namespace prefix \p renderContext. 313 /// For example, if the passed in render context is "ri" then the attribute 314 /// returned by this function would have the following signature: 315 /// | || 316 /// | -- | -- | 317 /// | Declaration | `token ri:lightFilter:shaderId` | 318 /// | C++ Type | TfToken | 319 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 320 /// 321 /// If the render context is empty, this will return the default shader ID 322 /// attribute as returned by GetShaderIdAttr(). 323 USDLUX_API 324 UsdAttribute GetShaderIdAttrForRenderContext( 325 const TfToken &renderContext) const; 326 327 /// Creates the shader ID attribute for the given \p renderContext. 328 /// 329 /// See GetShaderIdAttrForRenderContext(), and also 330 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 331 /// If specified, author \p defaultValue as the attribute's default, 332 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 333 /// the default for \p writeSparsely is \c false. 334 USDLUX_API 335 UsdAttribute CreateShaderIdAttrForRenderContext( 336 const TfToken &renderContext, 337 VtValue const &defaultValue = VtValue(), 338 bool writeSparsely=false) const; 339 340 /// Return the light filter's shader ID for the given list of available 341 /// \p renderContexts. 342 /// 343 /// The shader ID returned by this function is the identifier to use when 344 /// looking up the shader definition for this light filter in the 345 /// \ref SdrRegistry "shader registry". 346 /// 347 /// The render contexts are expected to be listed in priority order, so 348 /// for each render context provided, this will try to find the shader ID 349 /// attribute specific to that render context (see 350 /// GetShaderIdAttrForRenderContext()) and will return the 351 /// value of the first one found that has a non-empty value. If no shader ID 352 /// value can be found for any of the given render contexts or 353 /// \p renderContexts is empty, then this will return the value of the 354 /// default shader ID attribute (see GetShaderIdAttr()). 355 USDLUX_API 356 TfToken GetShaderId(const TfTokenVector &renderContexts) const; 357 358 }; 359 360 PXR_NAMESPACE_CLOSE_SCOPE 361 362 #endif 363