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_LIGHTAPI_H 25 #define USDLUX_GENERATED_LIGHTAPI_H 26 27 /// \file usdLux/lightAPI.h 28 29 #include "pxr/pxr.h" 30 #include "pxr/usd/usdLux/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/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 // LIGHTAPI // 55 // -------------------------------------------------------------------------- // 56 57 /// \class UsdLuxLightAPI 58 /// 59 /// API schema that imparts the quality of being a light onto a prim. 60 /// 61 /// A light is any prim that has this schema applied to it. This is true 62 /// regardless of whether LightAPI is included as a built-in API of the prim 63 /// type (e.g. RectLight or DistantLight) or is applied directly to a Gprim 64 /// that should be treated as a light. 65 /// 66 /// <b>Linking</b> 67 /// 68 /// Lights can be linked to geometry. Linking controls which geometry 69 /// a light illuminates, and which geometry casts shadows from the light. 70 /// 71 /// Linking is specified as collections (UsdCollectionAPI) which can 72 /// be accessed via GetLightLinkCollection() and GetShadowLinkCollection(). 73 /// Note that these collections have their includeRoot set to true, 74 /// so that lights will illuminate and cast shadows from all objects 75 /// by default. To illuminate only a specific set of objects, there 76 /// are two options. One option is to modify the collection paths 77 /// to explicitly exclude everything else, assuming it is known; 78 /// the other option is to set includeRoot to false and explicitly 79 /// include the desired objects. These are complementary approaches 80 /// that may each be preferable depending on the scenario and how 81 /// to best express the intent of the light setup. 82 /// 83 /// 84 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below 85 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens. 86 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded 87 /// as the value. 88 /// 89 class UsdLuxLightAPI : public UsdAPISchemaBase 90 { 91 public: 92 /// Compile time constant representing what kind of schema this class is. 93 /// 94 /// \sa UsdSchemaKind 95 static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI; 96 97 /// Construct a UsdLuxLightAPI on UsdPrim \p prim . 98 /// Equivalent to UsdLuxLightAPI::Get(prim.GetStage(), prim.GetPath()) 99 /// for a \em valid \p prim, but will not immediately throw an error for 100 /// an invalid \p prim 101 explicit UsdLuxLightAPI(const UsdPrim& prim=UsdPrim()) UsdAPISchemaBase(prim)102 : UsdAPISchemaBase(prim) 103 { 104 } 105 106 /// Construct a UsdLuxLightAPI on the prim held by \p schemaObj . 107 /// Should be preferred over UsdLuxLightAPI(schemaObj.GetPrim()), 108 /// as it preserves SchemaBase state. UsdLuxLightAPI(const UsdSchemaBase & schemaObj)109 explicit UsdLuxLightAPI(const UsdSchemaBase& schemaObj) 110 : UsdAPISchemaBase(schemaObj) 111 { 112 } 113 114 /// Destructor. 115 USDLUX_API 116 virtual ~UsdLuxLightAPI(); 117 118 /// Return a vector of names of all pre-declared attributes for this schema 119 /// class and all its ancestor classes. Does not include attributes that 120 /// may be authored by custom/extended methods of the schemas involved. 121 USDLUX_API 122 static const TfTokenVector & 123 GetSchemaAttributeNames(bool includeInherited=true); 124 125 /// Return a UsdLuxLightAPI holding the prim adhering to this 126 /// schema at \p path on \p stage. If no prim exists at \p path on 127 /// \p stage, or if the prim at that path does not adhere to this schema, 128 /// return an invalid schema object. This is shorthand for the following: 129 /// 130 /// \code 131 /// UsdLuxLightAPI(stage->GetPrimAtPath(path)); 132 /// \endcode 133 /// 134 USDLUX_API 135 static UsdLuxLightAPI 136 Get(const UsdStagePtr &stage, const SdfPath &path); 137 138 139 /// Returns true if this <b>single-apply</b> API schema can be applied to 140 /// the given \p prim. If this schema can not be a applied to the prim, 141 /// this returns false and, if provided, populates \p whyNot with the 142 /// reason it can not be applied. 143 /// 144 /// Note that if CanApply returns false, that does not necessarily imply 145 /// that calling Apply will fail. Callers are expected to call CanApply 146 /// before calling Apply if they want to ensure that it is valid to 147 /// apply a schema. 148 /// 149 /// \sa UsdPrim::GetAppliedSchemas() 150 /// \sa UsdPrim::HasAPI() 151 /// \sa UsdPrim::CanApplyAPI() 152 /// \sa UsdPrim::ApplyAPI() 153 /// \sa UsdPrim::RemoveAPI() 154 /// 155 USDLUX_API 156 static bool 157 CanApply(const UsdPrim &prim, std::string *whyNot=nullptr); 158 159 /// Applies this <b>single-apply</b> API schema to the given \p prim. 160 /// This information is stored by adding "LightAPI" to the 161 /// token-valued, listOp metadata \em apiSchemas on the prim. 162 /// 163 /// \return A valid UsdLuxLightAPI object is returned upon success. 164 /// An invalid (or empty) UsdLuxLightAPI object is returned upon 165 /// failure. See \ref UsdPrim::ApplyAPI() for conditions 166 /// resulting in failure. 167 /// 168 /// \sa UsdPrim::GetAppliedSchemas() 169 /// \sa UsdPrim::HasAPI() 170 /// \sa UsdPrim::CanApplyAPI() 171 /// \sa UsdPrim::ApplyAPI() 172 /// \sa UsdPrim::RemoveAPI() 173 /// 174 USDLUX_API 175 static UsdLuxLightAPI 176 Apply(const UsdPrim &prim); 177 178 protected: 179 /// Returns the kind of schema this class belongs to. 180 /// 181 /// \sa UsdSchemaKind 182 USDLUX_API 183 UsdSchemaKind _GetSchemaKind() const override; 184 185 private: 186 // needs to invoke _GetStaticTfType. 187 friend class UsdSchemaRegistry; 188 USDLUX_API 189 static const TfType &_GetStaticTfType(); 190 191 static bool _IsTypedSchema(); 192 193 // override SchemaBase virtuals. 194 USDLUX_API 195 const TfType &_GetTfType() const override; 196 197 public: 198 // --------------------------------------------------------------------- // 199 // SHADERID 200 // --------------------------------------------------------------------- // 201 /// Default ID for the light's shader. 202 /// This defines the shader ID for this light when a render context specific 203 /// shader ID is not available. 204 /// 205 /// The default shaderId for the intrinsic UsdLux lights (RectLight, 206 /// DistantLight, etc.) are set to default to the light's type name. For 207 /// each intrinsic UsdLux light, we will always register an SdrShaderNode in 208 /// the SdrRegistry, with the identifier matching the type name and the 209 /// source type "USD", that corresponds to the light's inputs. 210 /// \see GetShaderId 211 /// \see GetShaderIdAttrForRenderContext 212 /// \see SdrRegistry::GetShaderNodeByIdentifier 213 /// \see SdrRegistry::GetShaderNodeByIdentifierAndType 214 /// 215 /// 216 /// | || 217 /// | -- | -- | 218 /// | Declaration | `uniform token light:shaderId = ""` | 219 /// | C++ Type | TfToken | 220 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 221 /// | \ref SdfVariability "Variability" | SdfVariabilityUniform | 222 USDLUX_API 223 UsdAttribute GetShaderIdAttr() const; 224 225 /// See GetShaderIdAttr(), and also 226 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 227 /// If specified, author \p defaultValue as the attribute's default, 228 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 229 /// the default for \p writeSparsely is \c false. 230 USDLUX_API 231 UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 232 233 public: 234 // --------------------------------------------------------------------- // 235 // MATERIALSYNCMODE 236 // --------------------------------------------------------------------- // 237 /// For a LightAPI applied to geometry that has a bound Material, 238 /// which is entirely or partly emissive, this specifies the relationship 239 /// of the Material response to the lighting response. 240 /// Valid values are: 241 /// - materialGlowTintsLight: All primary and secondary rays see the 242 /// emissive/glow response as dictated by the bound Material while the 243 /// base color seen by light rays (which is then modulated by all of the 244 /// other LightAPI controls) is the multiplication of the color feeding 245 /// the emission/glow input of the Material (i.e. its surface or volume 246 /// shader) with the scalar or pattern input to *inputs:color*. 247 /// This allows the light's color to tint the geometry's glow color while 248 /// preserving access to intensity and other light controls as ways to 249 /// further modulate the illumination. 250 /// - independent: All primary and secondary rays see the emissive/glow 251 /// response as dictated by the bound Material, while the base color seen 252 /// by light rays is determined solely by *inputs:color*. Note that for 253 /// partially emissive geometry (in which some parts are reflective 254 /// rather than emissive), a suitable pattern must be connected to the 255 /// light's color input, or else the light will radiate uniformly from 256 /// the geometry. 257 /// - noMaterialResponse: The geometry behaves as if there is no Material 258 /// bound at all, i.e. there is no diffuse, specular, or transmissive 259 /// response. The base color of light rays is entirely controlled by the 260 /// *inputs:color*. This is the standard mode for "canonical" lights in 261 /// UsdLux and indicates to renderers that a Material will either never 262 /// be bound or can always be ignored. 263 /// 264 /// 265 /// | || 266 /// | -- | -- | 267 /// | Declaration | `uniform token light:materialSyncMode = "noMaterialResponse"` | 268 /// | C++ Type | TfToken | 269 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 270 /// | \ref SdfVariability "Variability" | SdfVariabilityUniform | 271 /// | \ref UsdLuxTokens "Allowed Values" | materialGlowTintsLight, independent, noMaterialResponse | 272 USDLUX_API 273 UsdAttribute GetMaterialSyncModeAttr() const; 274 275 /// See GetMaterialSyncModeAttr(), and also 276 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 277 /// If specified, author \p defaultValue as the attribute's default, 278 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 279 /// the default for \p writeSparsely is \c false. 280 USDLUX_API 281 UsdAttribute CreateMaterialSyncModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 282 283 public: 284 // --------------------------------------------------------------------- // 285 // INTENSITY 286 // --------------------------------------------------------------------- // 287 /// Scales the power of the light linearly. 288 /// 289 /// | || 290 /// | -- | -- | 291 /// | Declaration | `float inputs:intensity = 1` | 292 /// | C++ Type | float | 293 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float | 294 USDLUX_API 295 UsdAttribute GetIntensityAttr() const; 296 297 /// See GetIntensityAttr(), and also 298 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 299 /// If specified, author \p defaultValue as the attribute's default, 300 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 301 /// the default for \p writeSparsely is \c false. 302 USDLUX_API 303 UsdAttribute CreateIntensityAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 304 305 public: 306 // --------------------------------------------------------------------- // 307 // EXPOSURE 308 // --------------------------------------------------------------------- // 309 /// Scales the power of the light exponentially as a power 310 /// of 2 (similar to an F-stop control over exposure). The result 311 /// is multiplied against the intensity. 312 /// 313 /// | || 314 /// | -- | -- | 315 /// | Declaration | `float inputs:exposure = 0` | 316 /// | C++ Type | float | 317 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float | 318 USDLUX_API 319 UsdAttribute GetExposureAttr() const; 320 321 /// See GetExposureAttr(), and also 322 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 323 /// If specified, author \p defaultValue as the attribute's default, 324 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 325 /// the default for \p writeSparsely is \c false. 326 USDLUX_API 327 UsdAttribute CreateExposureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 328 329 public: 330 // --------------------------------------------------------------------- // 331 // DIFFUSE 332 // --------------------------------------------------------------------- // 333 /// A multiplier for the effect of this light on the diffuse 334 /// response of materials. This is a non-physical control. 335 /// 336 /// | || 337 /// | -- | -- | 338 /// | Declaration | `float inputs:diffuse = 1` | 339 /// | C++ Type | float | 340 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float | 341 USDLUX_API 342 UsdAttribute GetDiffuseAttr() const; 343 344 /// See GetDiffuseAttr(), and also 345 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 346 /// If specified, author \p defaultValue as the attribute's default, 347 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 348 /// the default for \p writeSparsely is \c false. 349 USDLUX_API 350 UsdAttribute CreateDiffuseAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 351 352 public: 353 // --------------------------------------------------------------------- // 354 // SPECULAR 355 // --------------------------------------------------------------------- // 356 /// A multiplier for the effect of this light on the specular 357 /// response of materials. This is a non-physical control. 358 /// 359 /// | || 360 /// | -- | -- | 361 /// | Declaration | `float inputs:specular = 1` | 362 /// | C++ Type | float | 363 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float | 364 USDLUX_API 365 UsdAttribute GetSpecularAttr() const; 366 367 /// See GetSpecularAttr(), and also 368 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 369 /// If specified, author \p defaultValue as the attribute's default, 370 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 371 /// the default for \p writeSparsely is \c false. 372 USDLUX_API 373 UsdAttribute CreateSpecularAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 374 375 public: 376 // --------------------------------------------------------------------- // 377 // NORMALIZE 378 // --------------------------------------------------------------------- // 379 /// Normalizes power by the surface area of the light. 380 /// This makes it easier to independently adjust the power and shape 381 /// of the light, by causing the power to not vary with the area or 382 /// angular size of the light. 383 /// 384 /// | || 385 /// | -- | -- | 386 /// | Declaration | `bool inputs:normalize = 0` | 387 /// | C++ Type | bool | 388 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool | 389 USDLUX_API 390 UsdAttribute GetNormalizeAttr() const; 391 392 /// See GetNormalizeAttr(), and also 393 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 394 /// If specified, author \p defaultValue as the attribute's default, 395 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 396 /// the default for \p writeSparsely is \c false. 397 USDLUX_API 398 UsdAttribute CreateNormalizeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 399 400 public: 401 // --------------------------------------------------------------------- // 402 // COLOR 403 // --------------------------------------------------------------------- // 404 /// The color of emitted light, in energy-linear terms. 405 /// 406 /// | || 407 /// | -- | -- | 408 /// | Declaration | `color3f inputs:color = (1, 1, 1)` | 409 /// | C++ Type | GfVec3f | 410 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Color3f | 411 USDLUX_API 412 UsdAttribute GetColorAttr() const; 413 414 /// See GetColorAttr(), and also 415 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 416 /// If specified, author \p defaultValue as the attribute's default, 417 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 418 /// the default for \p writeSparsely is \c false. 419 USDLUX_API 420 UsdAttribute CreateColorAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 421 422 public: 423 // --------------------------------------------------------------------- // 424 // ENABLECOLORTEMPERATURE 425 // --------------------------------------------------------------------- // 426 /// Enables using colorTemperature. 427 /// 428 /// | || 429 /// | -- | -- | 430 /// | Declaration | `bool inputs:enableColorTemperature = 0` | 431 /// | C++ Type | bool | 432 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool | 433 USDLUX_API 434 UsdAttribute GetEnableColorTemperatureAttr() const; 435 436 /// See GetEnableColorTemperatureAttr(), and also 437 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 438 /// If specified, author \p defaultValue as the attribute's default, 439 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 440 /// the default for \p writeSparsely is \c false. 441 USDLUX_API 442 UsdAttribute CreateEnableColorTemperatureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 443 444 public: 445 // --------------------------------------------------------------------- // 446 // COLORTEMPERATURE 447 // --------------------------------------------------------------------- // 448 /// Color temperature, in degrees Kelvin, representing the 449 /// white point. The default is a common white point, D65. Lower 450 /// values are warmer and higher values are cooler. The valid range 451 /// is from 1000 to 10000. Only takes effect when 452 /// enableColorTemperature is set to true. When active, the 453 /// computed result multiplies against the color attribute. 454 /// See UsdLuxBlackbodyTemperatureAsRgb(). 455 /// 456 /// | || 457 /// | -- | -- | 458 /// | Declaration | `float inputs:colorTemperature = 6500` | 459 /// | C++ Type | float | 460 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float | 461 USDLUX_API 462 UsdAttribute GetColorTemperatureAttr() const; 463 464 /// See GetColorTemperatureAttr(), and also 465 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 466 /// If specified, author \p defaultValue as the attribute's default, 467 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 468 /// the default for \p writeSparsely is \c false. 469 USDLUX_API 470 UsdAttribute CreateColorTemperatureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const; 471 472 public: 473 // --------------------------------------------------------------------- // 474 // FILTERS 475 // --------------------------------------------------------------------- // 476 /// Relationship to the light filters that apply to this light. 477 /// 478 USDLUX_API 479 UsdRelationship GetFiltersRel() const; 480 481 /// See GetFiltersRel(), and also 482 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create 483 USDLUX_API 484 UsdRelationship CreateFiltersRel() const; 485 486 public: 487 // ===================================================================== // 488 // Feel free to add custom code below this line, it will be preserved by 489 // the code generator. 490 // 491 // Just remember to: 492 // - Close the class declaration with }; 493 // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE 494 // - Close the include guard with #endif 495 // ===================================================================== // 496 // --(BEGIN CUSTOM CODE)-- 497 498 // ------------------------------------------------------------------------- 499 /// \name Conversion to and from UsdShadeConnectableAPI 500 /// 501 /// @{ 502 503 /// Constructor that takes a ConnectableAPI object. 504 /// Allow implicit conversion of a UsdShadeConnectableAPI to UsdLuxLightAPI 505 USDLUX_API 506 UsdLuxLightAPI(const UsdShadeConnectableAPI &connectable); 507 508 /// Contructs and returns a UsdShadeConnectableAPI object with this light. 509 /// 510 /// Note that most tasks can be accomplished without explicitly constructing 511 /// a UsdShadeConnectable API, since connection-related API such as 512 /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and 513 /// UsdLuxLightAPI will auto-convert to a UsdShadeConnectableAPI when 514 /// passed to functions that want to act generically on a connectable 515 /// UsdShadeConnectableAPI object. 516 USDLUX_API 517 UsdShadeConnectableAPI ConnectableAPI() const; 518 519 /// @} 520 521 // ------------------------------------------------------------------------- 522 /// \name Outputs API 523 /// 524 /// Outputs represent a typed attribute on a light whose value is computed 525 /// externally. 526 /// 527 /// @{ 528 529 /// Create an output which can either have a value or can be connected. 530 /// The attribute representing the output is created in the "outputs:" 531 /// namespace. Outputs on a light cannot be connected, as their 532 /// value is assumed to be computed externally. 533 /// 534 USDLUX_API 535 UsdShadeOutput CreateOutput(const TfToken& name, 536 const SdfValueTypeName& typeName); 537 538 /// Return the requested output if it exists. 539 /// 540 USDLUX_API 541 UsdShadeOutput GetOutput(const TfToken &name) const; 542 543 /// Outputs are represented by attributes in the "outputs:" namespace. 544 /// If \p onlyAuthored is true (the default), then only return authored 545 /// attributes; otherwise, this also returns un-authored builtins. 546 /// 547 USDLUX_API 548 std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored=true) const; 549 550 /// @} 551 552 // ------------------------------------------------------------------------- 553 554 /// \name Inputs API 555 /// 556 /// Inputs are connectable attribute with a typed value. 557 /// 558 /// Light parameters are encoded as inputs. 559 /// 560 /// @{ 561 562 /// Create an input which can either have a value or can be connected. 563 /// The attribute representing the input is created in the "inputs:" 564 /// namespace. Inputs on lights are connectable. 565 /// 566 USDLUX_API 567 UsdShadeInput CreateInput(const TfToken& name, 568 const SdfValueTypeName& typeName); 569 570 /// Return the requested input if it exists. 571 /// 572 USDLUX_API 573 UsdShadeInput GetInput(const TfToken &name) const; 574 575 /// Inputs are represented by attributes in the "inputs:" namespace. 576 /// If \p onlyAuthored is true (the default), then only return authored 577 /// attributes; otherwise, this also returns un-authored builtins. 578 /// 579 USDLUX_API 580 std::vector<UsdShadeInput> GetInputs(bool onlyAuthored=true) const; 581 582 /// @} 583 584 /// Return the UsdCollectionAPI interface used for examining and 585 /// modifying the light-linking of this light. Light-linking 586 /// controls which geometry this light illuminates. 587 USDLUX_API 588 UsdCollectionAPI GetLightLinkCollectionAPI() const; 589 590 /// Return the UsdCollectionAPI interface used for examining and 591 /// modifying the shadow-linking of this light. Shadow-linking 592 /// controls which geometry casts shadows from this light. 593 USDLUX_API 594 UsdCollectionAPI GetShadowLinkCollectionAPI() const; 595 596 /// Returns the shader ID attribute for the given \p renderContext. 597 /// 598 /// If \p renderContext is non-empty, this will try to return an attribute 599 /// named _light:shaderId_ with the namespace prefix \p renderContext. For 600 /// example, if the passed in render context is "ri" then the attribute 601 /// returned by this function would have the following signature: 602 /// | || 603 /// | -- | -- | 604 /// | Declaration | `token ri:light:shaderId` | 605 /// | C++ Type | TfToken | 606 /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token | 607 /// 608 /// If the render context is empty, this will return the default shader ID 609 /// attribute as returned by GetShaderIdAttr(). 610 USDLUX_API 611 UsdAttribute GetShaderIdAttrForRenderContext( 612 const TfToken &renderContext) const; 613 614 /// Creates the shader ID attribute for the given \p renderContext. 615 /// 616 /// See GetShaderIdAttrForRenderContext(), and also 617 /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create. 618 /// If specified, author \p defaultValue as the attribute's default, 619 /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true - 620 /// the default for \p writeSparsely is \c false. 621 USDLUX_API 622 UsdAttribute CreateShaderIdAttrForRenderContext( 623 const TfToken &renderContext, 624 VtValue const &defaultValue = VtValue(), 625 bool writeSparsely=false) const; 626 627 /// Return the light's shader ID for the given list of available 628 /// \p renderContexts. 629 /// 630 /// The shader ID returned by this function is the identifier to use when 631 /// looking up the shader definition for this light in the 632 /// \ref SdrRegistry "shader registry". 633 /// 634 /// The render contexts are expected to be listed in priority order, so 635 /// for each render context provided, this will try to find the shader ID 636 /// attribute specific to that render context (see 637 /// GetShaderIdAttrForRenderContext()) and will return the 638 /// value of the first one found that has a non-empty value. If no shader ID 639 /// value can be found for any of the given render contexts or 640 /// \p renderContexts is empty, then this will return the value of the 641 /// default shader ID attribute (see GetShaderIdAttr()). 642 USDLUX_API 643 TfToken GetShaderId(const TfTokenVector &renderContexts) const; 644 }; 645 646 PXR_NAMESPACE_CLOSE_SCOPE 647 648 #endif 649