HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
lightAPI.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDLUX_GENERATED_LIGHTAPI_H
8 #define USDLUX_GENERATED_LIGHTAPI_H
9 
10 /// \file usdLux/lightAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdLux/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdLux/tokens.h"
18 
20 #include "pxr/usd/usdShade/input.h"
21 #include "pxr/usd/usdShade/output.h"
22 
23 #include "pxr/base/vt/value.h"
24 
25 #include "pxr/base/gf/vec3d.h"
26 #include "pxr/base/gf/vec3f.h"
27 #include "pxr/base/gf/matrix4d.h"
28 
29 #include "pxr/base/tf/token.h"
30 #include "pxr/base/tf/type.h"
31 
33 
34 class SdfAssetPath;
35 
36 // -------------------------------------------------------------------------- //
37 // LIGHTAPI //
38 // -------------------------------------------------------------------------- //
39 
40 /// \class UsdLuxLightAPI
41 ///
42 /// API schema that imparts the quality of being a light onto a prim.
43 ///
44 /// A light is any prim that has this schema applied to it. This is true
45 /// regardless of whether LightAPI is included as a built-in API of the prim
46 /// type (e.g. RectLight or DistantLight) or is applied directly to a Gprim
47 /// that should be treated as a light.
48 ///
49 /// <b>Quantities and Units</b>
50 ///
51 /// Most renderers consuming OpenUSD today are RGB renderers, rather than
52 /// spectral. Units in RGB renderers are tricky to define as each of the red,
53 /// green and blue channels transported by the renderer represents the
54 /// convolution of a spectral exposure distribution, e.g. CIE Illuminant D65,
55 /// with a sensor response function, e.g. CIE 1931 𝓍̅. Thus the main quantity
56 /// in an RGB renderer is neither radiance nor luminance, but "integrated
57 /// radiance" or "tristimulus weight".
58 ///
59 /// The emission of a default light with `intensity` 1 and `color` [1, 1, 1] is
60 /// an Illuminant D spectral distribution with chromaticity matching the
61 /// rendering color space white point, normalized such that a ray normally
62 /// incident upon the sensor with EV0 exposure settings will generate a pixel
63 /// value of [1, 1, 1] in the rendering color space.
64 ///
65 /// Given the above definition, that means that the luminance of said default
66 /// light will be 1 *nit (cd∕m²)* and its emission spectral radiance
67 /// distribution is easily computed by appropriate normalization.
68 ///
69 /// For brevity, the term *emission* will be used in the documentation to mean
70 /// "emitted spectral radiance" or "emitted integrated radiance/tristimulus
71 /// weight", as appropriate.
72 ///
73 /// The method of "uplifting" an RGB color to a spectral distribution is
74 /// unspecified other than that it should round-trip under the rendering
75 /// illuminant to the limits of numerical accuracy.
76 ///
77 /// Note that some color spaces, most notably ACES, define their white points
78 /// by chromaticity coordinates that do not exactly line up to any value of a
79 /// standard illuminant. Because we do not define the method of uplift beyond
80 /// the round-tripping requirement, we discourage the use of such color spaces
81 /// as the rendering color space, and instead encourage the use of color spaces
82 /// whose white point has a well-defined spectral representation, such as D65.
83 ///
84 /// <b>Linking</b>
85 ///
86 /// Lights can be linked to geometry. Linking controls which geometry
87 /// a light illuminates, and which geometry casts shadows from the light.
88 ///
89 /// Linking is specified as collections (UsdCollectionAPI) which can
90 /// be accessed via GetLightLinkCollection() and GetShadowLinkCollection().
91 /// Note that these collections have their includeRoot set to true,
92 /// so that lights will illuminate and cast shadows from all objects
93 /// by default. To illuminate only a specific set of objects, there
94 /// are two options. One option is to modify the collection paths
95 /// to explicitly exclude everything else, assuming it is known;
96 /// the other option is to set includeRoot to false and explicitly
97 /// include the desired objects. These are complementary approaches
98 /// that may each be preferable depending on the scenario and how
99 /// to best express the intent of the light setup.
100 ///
101 ///
102 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
103 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens.
104 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded
105 /// as the value.
106 ///
108 {
109 public:
110  /// Compile time constant representing what kind of schema this class is.
111  ///
112  /// \sa UsdSchemaKind
114 
115  /// Construct a UsdLuxLightAPI on UsdPrim \p prim .
116  /// Equivalent to UsdLuxLightAPI::Get(prim.GetStage(), prim.GetPath())
117  /// for a \em valid \p prim, but will not immediately throw an error for
118  /// an invalid \p prim
119  explicit UsdLuxLightAPI(const UsdPrim& prim=UsdPrim())
120  : UsdAPISchemaBase(prim)
121  {
122  }
123 
124  /// Construct a UsdLuxLightAPI on the prim held by \p schemaObj .
125  /// Should be preferred over UsdLuxLightAPI(schemaObj.GetPrim()),
126  /// as it preserves SchemaBase state.
127  explicit UsdLuxLightAPI(const UsdSchemaBase& schemaObj)
128  : UsdAPISchemaBase(schemaObj)
129  {
130  }
131 
132  /// Destructor.
133  USDLUX_API
134  virtual ~UsdLuxLightAPI();
135 
136  /// Return a vector of names of all pre-declared attributes for this schema
137  /// class and all its ancestor classes. Does not include attributes that
138  /// may be authored by custom/extended methods of the schemas involved.
139  USDLUX_API
140  static const TfTokenVector &
141  GetSchemaAttributeNames(bool includeInherited=true);
142 
143  /// Return a UsdLuxLightAPI holding the prim adhering to this
144  /// schema at \p path on \p stage. If no prim exists at \p path on
145  /// \p stage, or if the prim at that path does not adhere to this schema,
146  /// return an invalid schema object. This is shorthand for the following:
147  ///
148  /// \code
149  /// UsdLuxLightAPI(stage->GetPrimAtPath(path));
150  /// \endcode
151  ///
152  USDLUX_API
153  static UsdLuxLightAPI
154  Get(const UsdStagePtr &stage, const SdfPath &path);
155 
156 
157  /// Returns true if this <b>single-apply</b> API schema can be applied to
158  /// the given \p prim. If this schema can not be a applied to the prim,
159  /// this returns false and, if provided, populates \p whyNot with the
160  /// reason it can not be applied.
161  ///
162  /// Note that if CanApply returns false, that does not necessarily imply
163  /// that calling Apply will fail. Callers are expected to call CanApply
164  /// before calling Apply if they want to ensure that it is valid to
165  /// apply a schema.
166  ///
167  /// \sa UsdPrim::GetAppliedSchemas()
168  /// \sa UsdPrim::HasAPI()
169  /// \sa UsdPrim::CanApplyAPI()
170  /// \sa UsdPrim::ApplyAPI()
171  /// \sa UsdPrim::RemoveAPI()
172  ///
173  USDLUX_API
174  static bool
175  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
176 
177  /// Applies this <b>single-apply</b> API schema to the given \p prim.
178  /// This information is stored by adding "LightAPI" to the
179  /// token-valued, listOp metadata \em apiSchemas on the prim.
180  ///
181  /// \return A valid UsdLuxLightAPI object is returned upon success.
182  /// An invalid (or empty) UsdLuxLightAPI object is returned upon
183  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
184  /// resulting in failure.
185  ///
186  /// \sa UsdPrim::GetAppliedSchemas()
187  /// \sa UsdPrim::HasAPI()
188  /// \sa UsdPrim::CanApplyAPI()
189  /// \sa UsdPrim::ApplyAPI()
190  /// \sa UsdPrim::RemoveAPI()
191  ///
192  USDLUX_API
193  static UsdLuxLightAPI
194  Apply(const UsdPrim &prim);
195 
196 protected:
197  /// Returns the kind of schema this class belongs to.
198  ///
199  /// \sa UsdSchemaKind
200  USDLUX_API
201  UsdSchemaKind _GetSchemaKind() const override;
202 
203 private:
204  // needs to invoke _GetStaticTfType.
205  friend class UsdSchemaRegistry;
206  USDLUX_API
207  static const TfType &_GetStaticTfType();
208 
209  static bool _IsTypedSchema();
210 
211  // override SchemaBase virtuals.
212  USDLUX_API
213  const TfType &_GetTfType() const override;
214 
215 public:
216  // --------------------------------------------------------------------- //
217  // SHADERID
218  // --------------------------------------------------------------------- //
219  /// Default ID for the light's shader.
220  /// This defines the shader ID for this light when a render context specific
221  /// shader ID is not available.
222  ///
223  /// The default shaderId for the intrinsic UsdLux lights (RectLight,
224  /// DistantLight, etc.) are set to default to the light's type name. For
225  /// each intrinsic UsdLux light, we will always register an SdrShaderNode in
226  /// the SdrRegistry, with the identifier matching the type name and the
227  /// source type "USD", that corresponds to the light's inputs.
228  /// \see GetShaderId
229  /// \see GetShaderIdAttrForRenderContext
230  /// \see SdrRegistry::GetShaderNodeByIdentifier
231  /// \see SdrRegistry::GetShaderNodeByIdentifierAndType
232  ///
233  ///
234  /// | ||
235  /// | -- | -- |
236  /// | Declaration | `uniform token light:shaderId = ""` |
237  /// | C++ Type | TfToken |
238  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
239  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
240  USDLUX_API
242 
243  /// See GetShaderIdAttr(), and also
244  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
245  /// If specified, author \p defaultValue as the attribute's default,
246  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
247  /// the default for \p writeSparsely is \c false.
248  USDLUX_API
249  UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
250 
251 public:
252  // --------------------------------------------------------------------- //
253  // MATERIALSYNCMODE
254  // --------------------------------------------------------------------- //
255  ///
256  /// For a LightAPI applied to geometry that has a bound Material,
257  /// which is entirely or partly emissive, this specifies the relationship
258  /// of the Material response to the lighting response.
259  /// Valid values are:
260  /// - materialGlowTintsLight: All primary and secondary rays see the
261  /// emissive/glow response as dictated by the bound Material while the
262  /// base color seen by light rays (which is then modulated by all of the
263  /// other LightAPI controls) is the multiplication of the color feeding
264  /// the emission/glow input of the Material (i.e. its surface or volume
265  /// shader) with the scalar or pattern input to *inputs:color*.
266  /// This allows the light's color to tint the geometry's glow color while
267  /// preserving access to intensity and other light controls as ways to
268  /// further modulate the illumination.
269  /// - independent: All primary and secondary rays see the emissive/glow
270  /// response as dictated by the bound Material, while the base color seen
271  /// by light rays is determined solely by *inputs:color*. Note that for
272  /// partially emissive geometry (in which some parts are reflective
273  /// rather than emissive), a suitable pattern must be connected to the
274  /// light's color input, or else the light will radiate uniformly from
275  /// the geometry.
276  /// - noMaterialResponse: The geometry behaves as if there is no Material
277  /// bound at all, i.e. there is no diffuse, specular, or transmissive
278  /// response. The base color of light rays is entirely controlled by the
279  /// *inputs:color*. This is the standard mode for "canonical" lights in
280  /// UsdLux and indicates to renderers that a Material will either never
281  /// be bound or can always be ignored.
282  ///
283  ///
284  /// | ||
285  /// | -- | -- |
286  /// | Declaration | `uniform token light:materialSyncMode = "noMaterialResponse"` |
287  /// | C++ Type | TfToken |
288  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
289  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
290  /// | \ref UsdLuxTokens "Allowed Values" | materialGlowTintsLight, independent, noMaterialResponse |
291  USDLUX_API
293 
294  /// See GetMaterialSyncModeAttr(), and also
295  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
296  /// If specified, author \p defaultValue as the attribute's default,
297  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
298  /// the default for \p writeSparsely is \c false.
299  USDLUX_API
300  UsdAttribute CreateMaterialSyncModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
301 
302 public:
303  // --------------------------------------------------------------------- //
304  // INTENSITY
305  // --------------------------------------------------------------------- //
306  /// Scales the brightness of the light linearly.
307  ///
308  /// Expresses the "base", unmultiplied luminance emitted (L) of the light,
309  /// in nits (cd∕m²):
310  ///
311  /// <center><b>
312  /// L<sub>Scalar</sub> = intensity
313  /// </b></center>
314  ///
315  /// Normatively, the lights' emission is in units of spectral radiance
316  /// normalized such that a directly visible light with `intensity` 1 and
317  /// `exposure` 0 normally incident upon the sensor plane will generate a
318  /// pixel value of [1, 1, 1] in an RGB renderer, and thus have a luminance
319  /// of 1 nit. A light with `intensity` 2 and `exposure` 0 would therefore
320  /// have a luminance of 2 nits.
321  ///
322  ///
323  /// | ||
324  /// | -- | -- |
325  /// | Declaration | `float inputs:intensity = 1` |
326  /// | C++ Type | float |
327  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
328  USDLUX_API
330 
331  /// See GetIntensityAttr(), and also
332  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
333  /// If specified, author \p defaultValue as the attribute's default,
334  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
335  /// the default for \p writeSparsely is \c false.
336  USDLUX_API
337  UsdAttribute CreateIntensityAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
338 
339 public:
340  // --------------------------------------------------------------------- //
341  // EXPOSURE
342  // --------------------------------------------------------------------- //
343  /// Scales the brightness of the light exponentially as a power
344  /// of 2 (similar to an F-stop control over exposure). The result
345  /// is multiplied against the intensity:
346  ///
347  /// <center><b>
348  /// L<sub>Scalar</sub> = L<sub>Scalar</sub> ⋅ 2<sup>exposure</sup>
349  /// </b></center>
350  ///
351  /// Normatively, the lights' emission is in units of spectral radiance
352  /// normalized such that a directly visible light with `intensity` 1 and
353  /// `exposure` 0 normally incident upon the sensor plane will generate a
354  /// pixel value of [1, 1, 1] in an RGB renderer, and thus have a luminance
355  /// of 1 nit (cd∕m²). A light with `intensity` 1 and `exposure` 2 would
356  /// therefore have a luminance of 4 nits.
357  ///
358  ///
359  /// | ||
360  /// | -- | -- |
361  /// | Declaration | `float inputs:exposure = 0` |
362  /// | C++ Type | float |
363  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
364  USDLUX_API
366 
367  /// See GetExposureAttr(), 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 CreateExposureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
374 
375 public:
376  // --------------------------------------------------------------------- //
377  // DIFFUSE
378  // --------------------------------------------------------------------- //
379  /// A multiplier for the effect of this light on the diffuse
380  /// response of materials. This is a non-physical control.
381  ///
382  /// | ||
383  /// | -- | -- |
384  /// | Declaration | `float inputs:diffuse = 1` |
385  /// | C++ Type | float |
386  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
387  USDLUX_API
389 
390  /// See GetDiffuseAttr(), and also
391  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
392  /// If specified, author \p defaultValue as the attribute's default,
393  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
394  /// the default for \p writeSparsely is \c false.
395  USDLUX_API
396  UsdAttribute CreateDiffuseAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
397 
398 public:
399  // --------------------------------------------------------------------- //
400  // SPECULAR
401  // --------------------------------------------------------------------- //
402  /// A multiplier for the effect of this light on the specular
403  /// response of materials. This is a non-physical control.
404  ///
405  /// | ||
406  /// | -- | -- |
407  /// | Declaration | `float inputs:specular = 1` |
408  /// | C++ Type | float |
409  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
410  USDLUX_API
412 
413  /// See GetSpecularAttr(), and also
414  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
415  /// If specified, author \p defaultValue as the attribute's default,
416  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
417  /// the default for \p writeSparsely is \c false.
418  USDLUX_API
419  UsdAttribute CreateSpecularAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
420 
421 public:
422  // --------------------------------------------------------------------- //
423  // NORMALIZE
424  // --------------------------------------------------------------------- //
425  /// Normalizes the emission such that the power of the light
426  /// remains constant while altering the size of the light, by dividing the
427  /// luminance by the world-space surface area of the light.
428  ///
429  /// This makes it easier to independently adjust the brightness and size
430  /// of the light, by causing the total illumination provided by a light to
431  /// not vary with the area or angular size of the light.
432  ///
433  /// Mathematically, this means that the luminance of the light will be
434  /// divided by a factor representing the "size" of the light:
435  ///
436  /// <center><b>
437  /// L<sub>Scalar</sub> = L<sub>Scalar</sub> / sizeFactor
438  /// </b></center>
439  ///
440  /// ...where `sizeFactor` = 1 if `normalize` is off, and is calculated
441  /// depending on the family of the light as described below if `normalize`
442  /// is on.
443  ///
444  /// ### DomeLight / PortalLight:
445  ///
446  /// For a dome light (and its associated PortalLight), this attribute is
447  /// ignored:
448  ///
449  /// <center><b>
450  /// sizeFactor<sub>dome</sub> = 1
451  /// </b></center>
452  ///
453  /// ### Area Lights:
454  ///
455  /// For an area light, the `sizeFactor` is the surface area (in world
456  /// space) of the shape of the light, including any scaling applied to the
457  /// light by its transform stack. This includes the boundable light types
458  /// which have a calculable surface area:
459  ///
460  /// - MeshLightAPI
461  /// - DiskLight
462  /// - RectLight
463  /// - SphereLight
464  /// - CylinderLight
465  ///
466  /// <center><b>
467  /// sizeFactor<sub>area</sub> = worldSpaceSurfaceArea(light)
468  /// </b></center>
469  ///
470  /// ### DistantLight:
471  ///
472  /// For distant lights, we first define 𝛳<sub>max</sub> as:
473  ///
474  /// <center><b>
475  /// 𝛳<sub>max</sub> = clamp(toRadians(distantLightAngle) / 2, 0, 𝜋)
476  /// </b></center>
477  ///
478  /// Then we use the following formula:
479  ///
480  /// * <i>if 𝛳<sub>max</sub> = 0:</i>
481  /// <center><b>
482  /// sizeFactor<sub>distant</sub> = 1
483  /// </b></center>
484  ///
485  /// * <i>if 0 < 𝛳<sub>max</sub> ≤ 𝜋 / 2:</i>
486  /// <center><b>
487  /// sizeFactor<sub>distant</sub> = sin²𝛳<sub>max</sub> ⋅ 𝜋
488  /// </b></center>
489  ///
490  /// * <i>if 𝜋 / 2 < 𝛳<sub>max</sub> ≤ 𝜋:</i>
491  /// <center><b>
492  /// sizeFactor<sub>distant</sub> =
493  /// (2 - sin²𝛳<sub>max</sub>) ⋅ 𝜋
494  /// </b></center>
495  ///
496  /// This formula is used because it satisfies the following two properties:
497  ///
498  /// 1. When normalize is enabled, the received illuminance from this light
499  /// on a surface normal to the light's primary direction is held constant
500  /// when angle changes, and the "intensity" property becomes a measure of
501  /// the illuminance, expressed in lux, for a light with 0 exposure.
502  ///
503  /// 2. If we assume that our distant light is an approximation for a "very
504  /// far" sphere light (like the sun), then (for
505  /// *0 < 𝛳<sub>max</sub> ≤ 𝜋/2*) this definition agrees with the
506  /// definition used for area lights - i.e., the total power of this distant
507  /// sphere light is constant when the "size" (i.e., angle) changes, and our
508  /// sizeFactor is proportional to the total surface area of this sphere.
509  ///
510  /// ### Other Lights
511  ///
512  /// The above taxonomy describes behavior for all built-in light types.
513  /// (Note that the above is based on schema *family* - i.e., `DomeLight_1`
514  /// follows the rules for a `DomeLight`, and ignores `normalize`).
515  ///
516  /// Lights from other third-party plugins / schemas must document their
517  /// expected behavior with regards to normalize. However, some general
518  /// guidelines are:
519  ///
520  /// - Lights that either inherit from or are strongly associated with one of
521  /// the built-in types should follow the behavior of the built-in type
522  /// they inherit/resemble; i.e., a renderer-specific "MyRendererRectLight"
523  /// should have its size factor be its world-space surface area.
524  /// - Lights that are boundable and have a calculable surface area should
525  /// follow the rules for an Area Light, and have their sizeFactor be their
526  /// world-space surface area.
527  /// - Lights that are non-boundable and/or have no way to concretely or even
528  /// "intuitively" associate them with a "size" will ignore this attribute
529  /// (and always set sizeFactor = 1).
530  ///
531  /// Lights that don't clearly meet any of the above criteria may either
532  /// ignore the normalize attribute or try to implement support using
533  /// whatever heuristic seems to make sense. For instance,
534  /// MyMandelbulbLight might use a sizeFactor equal to the world-space
535  /// surface area of a sphere which "roughly" bounds it.
536  ///
537  ///
538  /// | ||
539  /// | -- | -- |
540  /// | Declaration | `bool inputs:normalize = 0` |
541  /// | C++ Type | bool |
542  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
543  USDLUX_API
545 
546  /// See GetNormalizeAttr(), and also
547  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
548  /// If specified, author \p defaultValue as the attribute's default,
549  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
550  /// the default for \p writeSparsely is \c false.
551  USDLUX_API
552  UsdAttribute CreateNormalizeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
553 
554 public:
555  // --------------------------------------------------------------------- //
556  // COLOR
557  // --------------------------------------------------------------------- //
558  /// The color of emitted light, in the rendering color space.
559  ///
560  /// This color is just multiplied with the emission:
561  ///
562  /// <center><b>
563  /// L<sub>Color</sub> = L<sub>Scalar</sub> ⋅ color
564  /// </b></center>
565  ///
566  /// In the case of a spectral renderer, this color should be uplifted such
567  /// that it round-trips to within the limit of numerical accuracy under the
568  /// rendering illuminant. We recommend the use of a rendering color space
569  /// well defined in terms of a Illuminant D illuminant (ideally a D
570  /// illuminant whose white point has a well-defined spectral representation,
571  /// such as D65), to avoid unspecified uplift. See: \ref usdLux_quantities
572  ///
573  ///
574  /// | ||
575  /// | -- | -- |
576  /// | Declaration | `color3f inputs:color = (1, 1, 1)` |
577  /// | C++ Type | GfVec3f |
578  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Color3f |
579  USDLUX_API
580  UsdAttribute GetColorAttr() const;
581 
582  /// See GetColorAttr(), and also
583  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
584  /// If specified, author \p defaultValue as the attribute's default,
585  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
586  /// the default for \p writeSparsely is \c false.
587  USDLUX_API
588  UsdAttribute CreateColorAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
589 
590 public:
591  // --------------------------------------------------------------------- //
592  // ENABLECOLORTEMPERATURE
593  // --------------------------------------------------------------------- //
594  /// Enables using colorTemperature.
595  ///
596  /// | ||
597  /// | -- | -- |
598  /// | Declaration | `bool inputs:enableColorTemperature = 0` |
599  /// | C++ Type | bool |
600  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
601  USDLUX_API
603 
604  /// See GetEnableColorTemperatureAttr(), and also
605  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
606  /// If specified, author \p defaultValue as the attribute's default,
607  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
608  /// the default for \p writeSparsely is \c false.
609  USDLUX_API
610  UsdAttribute CreateEnableColorTemperatureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
611 
612 public:
613  // --------------------------------------------------------------------- //
614  // COLORTEMPERATURE
615  // --------------------------------------------------------------------- //
616  /// Color temperature, in degrees Kelvin, representing the
617  /// white point. The default is a common white point, D65. Lower
618  /// values are warmer and higher values are cooler. The valid range
619  /// is from 1000 to 10000. Only takes effect when
620  /// enableColorTemperature is set to true. When active, the
621  /// computed result multiplies against the color attribute.
622  /// See UsdLuxBlackbodyTemperatureAsRgb().
623  ///
624  /// This is always calculated as an RGB color using a D65 white point,
625  /// regardless of the rendering color space, normalized such that the
626  /// default value of 6500 will always result in white, and then should be
627  /// transformed to the rendering color space.
628  ///
629  /// Spectral renderers should do the same and then uplift the resulting
630  /// color after multiplying with the `color` attribute. We recommend the
631  /// use of a rendering color space well defined in terms of a Illuminant D
632  /// illuminant, to avoid unspecified uplift. See: \ref usdLux_quantities
633  ///
634  ///
635  /// | ||
636  /// | -- | -- |
637  /// | Declaration | `float inputs:colorTemperature = 6500` |
638  /// | C++ Type | float |
639  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
640  USDLUX_API
642 
643  /// See GetColorTemperatureAttr(), and also
644  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
645  /// If specified, author \p defaultValue as the attribute's default,
646  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
647  /// the default for \p writeSparsely is \c false.
648  USDLUX_API
649  UsdAttribute CreateColorTemperatureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
650 
651 public:
652  // --------------------------------------------------------------------- //
653  // FILTERS
654  // --------------------------------------------------------------------- //
655  /// Relationship to the light filters that apply to this light.
656  ///
657  USDLUX_API
659 
660  /// See GetFiltersRel(), and also
661  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
662  USDLUX_API
664 
665 public:
666  // ===================================================================== //
667  // Feel free to add custom code below this line, it will be preserved by
668  // the code generator.
669  //
670  // Just remember to:
671  // - Close the class declaration with };
672  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
673  // - Close the include guard with #endif
674  // ===================================================================== //
675  // --(BEGIN CUSTOM CODE)--
676 
677  // -------------------------------------------------------------------------
678  /// \name Conversion to and from UsdShadeConnectableAPI
679  ///
680  /// @{
681 
682  /// Constructor that takes a ConnectableAPI object.
683  /// Allow implicit conversion of a UsdShadeConnectableAPI to UsdLuxLightAPI
684  USDLUX_API
685  UsdLuxLightAPI(const UsdShadeConnectableAPI &connectable);
686 
687  /// Contructs and returns a UsdShadeConnectableAPI object with this light.
688  ///
689  /// Note that most tasks can be accomplished without explicitly constructing
690  /// a UsdShadeConnectable API, since connection-related API such as
691  /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and
692  /// UsdLuxLightAPI will auto-convert to a UsdShadeConnectableAPI when
693  /// passed to functions that want to act generically on a connectable
694  /// UsdShadeConnectableAPI object.
695  USDLUX_API
697 
698  /// @}
699 
700  // -------------------------------------------------------------------------
701  /// \name Outputs API
702  ///
703  /// Outputs represent a typed attribute on a light whose value is computed
704  /// externally.
705  ///
706  /// @{
707 
708  /// Create an output which can either have a value or can be connected.
709  /// The attribute representing the output is created in the "outputs:"
710  /// namespace. Outputs on a light cannot be connected, as their
711  /// value is assumed to be computed externally.
712  ///
713  USDLUX_API
715  const SdfValueTypeName& typeName);
716 
717  /// Return the requested output if it exists.
718  ///
719  USDLUX_API
720  UsdShadeOutput GetOutput(const TfToken &name) const;
721 
722  /// Outputs are represented by attributes in the "outputs:" namespace.
723  /// If \p onlyAuthored is true (the default), then only return authored
724  /// attributes; otherwise, this also returns un-authored builtins.
725  ///
726  USDLUX_API
727  std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored=true) const;
728 
729  /// @}
730 
731  // -------------------------------------------------------------------------
732 
733  /// \name Inputs API
734  ///
735  /// Inputs are connectable attribute with a typed value.
736  ///
737  /// Light parameters are encoded as inputs.
738  ///
739  /// @{
740 
741  /// Create an input which can either have a value or can be connected.
742  /// The attribute representing the input is created in the "inputs:"
743  /// namespace. Inputs on lights are connectable.
744  ///
745  USDLUX_API
747  const SdfValueTypeName& typeName);
748 
749  /// Return the requested input if it exists.
750  ///
751  USDLUX_API
752  UsdShadeInput GetInput(const TfToken &name) const;
753 
754  /// Inputs are represented by attributes in the "inputs:" namespace.
755  /// If \p onlyAuthored is true (the default), then only return authored
756  /// attributes; otherwise, this also returns un-authored builtins.
757  ///
758  USDLUX_API
759  std::vector<UsdShadeInput> GetInputs(bool onlyAuthored=true) const;
760 
761  /// @}
762 
763  /// Return the UsdCollectionAPI interface used for examining and
764  /// modifying the light-linking of this light. Light-linking
765  /// controls which geometry this light illuminates.
766  USDLUX_API
768 
769  /// Return the UsdCollectionAPI interface used for examining and
770  /// modifying the shadow-linking of this light. Shadow-linking
771  /// controls which geometry casts shadows from this light.
772  USDLUX_API
774 
775  /// Returns the shader ID attribute for the given \p renderContext.
776  ///
777  /// If \p renderContext is non-empty, this will try to return an attribute
778  /// named _light:shaderId_ with the namespace prefix \p renderContext. For
779  /// example, if the passed in render context is "ri" then the attribute
780  /// returned by this function would have the following signature:
781  /// | ||
782  /// | -- | -- |
783  /// | Declaration | `token ri:light:shaderId` |
784  /// | C++ Type | TfToken |
785  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
786  ///
787  /// If the render context is empty, this will return the default shader ID
788  /// attribute as returned by GetShaderIdAttr().
789  USDLUX_API
791  const TfToken &renderContext) const;
792 
793  /// Creates the shader ID attribute for the given \p renderContext.
794  ///
795  /// See GetShaderIdAttrForRenderContext(), and also
796  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
797  /// If specified, author \p defaultValue as the attribute's default,
798  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
799  /// the default for \p writeSparsely is \c false.
800  USDLUX_API
802  const TfToken &renderContext,
803  VtValue const &defaultValue = VtValue(),
804  bool writeSparsely=false) const;
805 
806  /// Return the light's shader ID for the given list of available
807  /// \p renderContexts.
808  ///
809  /// The shader ID returned by this function is the identifier to use when
810  /// looking up the shader definition for this light in the
811  /// \ref SdrRegistry "shader registry".
812  ///
813  /// The render contexts are expected to be listed in priority order, so
814  /// for each render context provided, this will try to find the shader ID
815  /// attribute specific to that render context (see
816  /// GetShaderIdAttrForRenderContext()) and will return the
817  /// value of the first one found that has a non-empty value. If no shader ID
818  /// value can be found for any of the given render contexts or
819  /// \p renderContexts is empty, then this will return the value of the
820  /// default shader ID attribute (see GetShaderIdAttr()).
821  USDLUX_API
822  TfToken GetShaderId(const TfTokenVector &renderContexts) const;
823 };
824 
826 
827 #endif
USDLUX_API UsdAttribute CreateDiffuseAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdShadeConnectableAPI ConnectableAPI() const
static const UsdSchemaKind schemaKind
Definition: lightAPI.h:113
USDLUX_API UsdAttribute CreateExposureAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdAttribute GetIntensityAttr() const
UsdLuxLightAPI(const UsdSchemaBase &schemaObj)
Definition: lightAPI.h:127
USDLUX_API UsdAttribute GetDiffuseAttr() const
USDLUX_API UsdAttribute GetExposureAttr() const
USDLUX_API UsdShadeInput CreateInput(const TfToken &name, const SdfValueTypeName &typeName)
UsdLuxLightAPI(const UsdPrim &prim=UsdPrim())
Definition: lightAPI.h:119
USDLUX_API UsdRelationship CreateFiltersRel() const
Single Apply API schema.
USDLUX_API TfToken GetShaderId(const TfTokenVector &renderContexts) const
USDLUX_API UsdAttribute GetShaderIdAttrForRenderContext(const TfToken &renderContext) const
USDLUX_API UsdShadeOutput GetOutput(const TfToken &name) const
USDLUX_API UsdShadeOutput CreateOutput(const TfToken &name, const SdfValueTypeName &typeName)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDLUX_API UsdAttribute CreateColorTemperatureAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
#define USDLUX_API
Definition: api.h:23
USDLUX_API std::vector< UsdShadeOutput > GetOutputs(bool onlyAuthored=true) const
USDLUX_API std::vector< UsdShadeInput > GetInputs(bool onlyAuthored=true) const
USDLUX_API UsdAttribute CreateEnableColorTemperatureAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdAttribute CreateColorAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
static USDLUX_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
USDLUX_API UsdAttribute GetNormalizeAttr() const
USDLUX_API UsdAttribute CreateShaderIdAttrForRenderContext(const TfToken &renderContext, VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdSchemaKind _GetSchemaKind() const override
static USDLUX_API UsdLuxLightAPI Get(const UsdStagePtr &stage, const SdfPath &path)
Definition: token.h:70
USDLUX_API UsdCollectionAPI GetShadowLinkCollectionAPI() const
USDLUX_API UsdAttribute GetColorAttr() const
USDLUX_API UsdRelationship GetFiltersRel() const
USDLUX_API UsdAttribute CreateMaterialSyncModeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdAttribute GetColorTemperatureAttr() const
USDLUX_API UsdAttribute GetMaterialSyncModeAttr() const
Definition: prim.h:116
USDLUX_API UsdCollectionAPI GetLightLinkCollectionAPI() const
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
GLuint const GLchar * name
Definition: glcorearb.h:786
USDLUX_API UsdAttribute GetEnableColorTemperatureAttr() const
Definition: path.h:273
USDLUX_API UsdAttribute GetSpecularAttr() const
UsdSchemaKind
Definition: common.h:112
virtual USDLUX_API ~UsdLuxLightAPI()
Destructor.
USDLUX_API UsdAttribute CreateNormalizeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDLUX_API UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdAttribute GetShaderIdAttr() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
USDLUX_API UsdShadeInput GetInput(const TfToken &name) const
Definition: type.h:47
USDLUX_API UsdAttribute CreateSpecularAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDLUX_API UsdAttribute CreateIntensityAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
static USDLUX_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: value.h:146
static USDLUX_API UsdLuxLightAPI Apply(const UsdPrim &prim)