This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdLuxLightAPI Class Reference

API schema that imparts the quality of being a light onto a prim. More...

#include <lightAPI.h>

+ Inheritance diagram for UsdLuxLightAPI:

Public Member Functions

 UsdLuxLightAPI (const UsdPrim &prim=UsdPrim())
 Construct a UsdLuxLightAPI on UsdPrim prim .
 
 UsdLuxLightAPI (const UsdSchemaBase &schemaObj)
 Construct a UsdLuxLightAPI on the prim held by schemaObj .
 
virtual USDLUX_API ~UsdLuxLightAPI ()
 Destructor.
 
USDLUX_API UsdAttribute GetShaderIdAttr () const
 Default ID for the light's shader.
 
USDLUX_API UsdAttribute CreateShaderIdAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetShaderIdAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetMaterialSyncModeAttr () const
 For a LightAPI applied to geometry that has a bound Material, which is entirely or partly emissive, this specifies the relationship of the Material response to the lighting response.
 
USDLUX_API UsdAttribute CreateMaterialSyncModeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetMaterialSyncModeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetIntensityAttr () const
 Scales the power of the light linearly.
 
USDLUX_API UsdAttribute CreateIntensityAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetIntensityAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetExposureAttr () const
 Scales the power of the light exponentially as a power of 2 (similar to an F-stop control over exposure).
 
USDLUX_API UsdAttribute CreateExposureAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetExposureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetDiffuseAttr () const
 A multiplier for the effect of this light on the diffuse response of materials.
 
USDLUX_API UsdAttribute CreateDiffuseAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetDiffuseAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetSpecularAttr () const
 A multiplier for the effect of this light on the specular response of materials.
 
USDLUX_API UsdAttribute CreateSpecularAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetSpecularAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetNormalizeAttr () const
 Normalizes power by the surface area of the light.
 
USDLUX_API UsdAttribute CreateNormalizeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetNormalizeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetColorAttr () const
 The color of emitted light, in energy-linear terms.
 
USDLUX_API UsdAttribute CreateColorAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetColorAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetEnableColorTemperatureAttr () const
 Enables using colorTemperature.
 
USDLUX_API UsdAttribute CreateEnableColorTemperatureAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetEnableColorTemperatureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdAttribute GetColorTemperatureAttr () const
 Color temperature, in degrees Kelvin, representing the white point.
 
USDLUX_API UsdAttribute CreateColorTemperatureAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetColorTemperatureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdRelationship GetFiltersRel () const
 Relationship to the light filters that apply to this light.
 
USDLUX_API UsdRelationship CreateFiltersRel () const
 See GetFiltersRel(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLUX_API UsdCollectionAPI GetLightLinkCollectionAPI () const
 Return the UsdCollectionAPI interface used for examining and modifying the light-linking of this light.
 
USDLUX_API UsdCollectionAPI GetShadowLinkCollectionAPI () const
 Return the UsdCollectionAPI interface used for examining and modifying the shadow-linking of this light.
 
USDLUX_API UsdAttribute GetShaderIdAttrForRenderContext (const TfToken &renderContext) const
 Returns the shader ID attribute for the given renderContext.
 
USDLUX_API UsdAttribute CreateShaderIdAttrForRenderContext (const TfToken &renderContext, VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 Creates the shader ID attribute for the given renderContext.
 
USDLUX_API TfToken GetShaderId (const TfTokenVector &renderContexts) const
 Return the light's shader ID for the given list of available renderContexts.
 
Conversion to and from UsdShadeConnectableAPI
USDLUX_API UsdLuxLightAPI (const UsdShadeConnectableAPI &connectable)
 Constructor that takes a ConnectableAPI object.
 
USDLUX_API UsdShadeConnectableAPI ConnectableAPI () const
 Contructs and returns a UsdShadeConnectableAPI object with this light.
 
Outputs API

Outputs represent a typed attribute on a light whose value is computed externally.

USDLUX_API UsdShadeOutput CreateOutput (const TfToken &name, const SdfValueTypeName &typeName)
 Create an output which can either have a value or can be connected.
 
USDLUX_API UsdShadeOutput GetOutput (const TfToken &name) const
 Return the requested output if it exists.
 
USDLUX_API std::vector< UsdShadeOutputGetOutputs (bool onlyAuthored=true) const
 Outputs are represented by attributes in the "outputs:" namespace.
 
Inputs API

Inputs are connectable attribute with a typed value.

Light parameters are encoded as inputs.

USDLUX_API UsdShadeInput CreateInput (const TfToken &name, const SdfValueTypeName &typeName)
 Create an input which can either have a value or can be connected.
 
USDLUX_API UsdShadeInput GetInput (const TfToken &name) const
 Return the requested input if it exists.
 
USDLUX_API std::vector< UsdShadeInputGetInputs (bool onlyAuthored=true) const
 Inputs are represented by attributes in the "inputs:" namespace.
 
- Public Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
 Construct a UsdAPISchemaBase on UsdPrim prim .
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
 Construct a UsdAPISchemaBase on the prim held by schemaObj .
 
virtual USD_API ~UsdAPISchemaBase ()=0
 Destructor.
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped.
 
bool IsAPISchema () const
 Returns whether this is an API schema or not.
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not.
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not.
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is.
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim.
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema.
 
virtual USD_API ~UsdSchemaBase ()
 Destructor.
 
UsdPrim GetPrim () const
 Return this schema object's held prim.
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath().
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null.
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise.
 

Static Public Member Functions

static USDLUX_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDLUX_API UsdLuxLightAPI Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdLuxLightAPI holding the prim adhering to this schema at path on stage.
 
static USDLUX_API bool CanApply (const UsdPrim &prim, std::string *whyNot=nullptr)
 Returns true if this single-apply API schema can be applied to the given prim.
 
static USDLUX_API UsdLuxLightAPI Apply (const UsdPrim &prim)
 Applies this single-apply API schema to the given prim.
 
- Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 

Protected Member Functions

USDLUX_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdAPISchemaBase
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
 UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on UsdPrim prim with the specified instanceName.
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on the prim held by schemaObj with the given instanceName.
 
const TfToken_GetInstanceName () const
 Returns the instance name of the API schema object belonging to a multiple-apply API schema.
 
USD_API bool _IsCompatible () const override
 Check whether this APISchema object is valid for the currently held
prim.
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Additional Inherited Members

- Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector _GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)
 Returns a vector of names of API schema objects belonging to a multiple-apply API schema applied to a given prim.
 

Detailed Description

API schema that imparts the quality of being a light onto a prim.

A light is any prim that has this schema applied to it. This is true regardless of whether LightAPI is included as a built-in API of the prim type (e.g. RectLight or DistantLight) or is applied directly to a Gprim that should be treated as a light.

Linking

Lights can be linked to geometry. Linking controls which geometry a light illuminates, and which geometry casts shadows from the light.

Linking is specified as collections (UsdCollectionAPI) which can be accessed via GetLightLinkCollection() and GetShadowLinkCollection(). Note that these collections have their includeRoot set to true, so that lights will illuminate and cast shadows from all objects by default. To illuminate only a specific set of objects, there are two options. One option is to modify the collection paths to explicitly exclude everything else, assuming it is known; the other option is to set includeRoot to false and explicitly include the desired objects. These are complementary approaches that may each be preferable depending on the scenario and how to best express the intent of the light setup.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdLuxTokens. So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded as the value.

Definition at line 72 of file lightAPI.h.

Constructor & Destructor Documentation

◆ UsdLuxLightAPI() [1/3]

UsdLuxLightAPI ( const UsdPrim prim = UsdPrim())
inlineexplicit

Construct a UsdLuxLightAPI on UsdPrim prim .

Equivalent to UsdLuxLightAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 84 of file lightAPI.h.

◆ UsdLuxLightAPI() [2/3]

UsdLuxLightAPI ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdLuxLightAPI on the prim held by schemaObj .

Should be preferred over UsdLuxLightAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 92 of file lightAPI.h.

◆ ~UsdLuxLightAPI()

virtual USDLUX_API ~UsdLuxLightAPI ( )
virtual

Destructor.

◆ UsdLuxLightAPI() [3/3]

USDLUX_API UsdLuxLightAPI ( const UsdShadeConnectableAPI connectable)

Constructor that takes a ConnectableAPI object.

Allow implicit conversion of a UsdShadeConnectableAPI to UsdLuxLightAPI

Member Function Documentation

◆ _GetSchemaKind()

USDLUX_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

◆ Apply()

static USDLUX_API UsdLuxLightAPI Apply ( const UsdPrim prim)
static

Applies this single-apply API schema to the given prim.

This information is stored by adding "LightAPI" to the token-valued, listOp metadata apiSchemas on the prim.

Returns
A valid UsdLuxLightAPI object is returned upon success. An invalid (or empty) UsdLuxLightAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.
See also
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()

◆ CanApply()

static USDLUX_API bool CanApply ( const UsdPrim prim,
std::string *  whyNot = nullptr 
)
static

Returns true if this single-apply API schema can be applied to the given prim.

If this schema can not be a applied to the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

See also
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()

◆ ConnectableAPI()

USDLUX_API UsdShadeConnectableAPI ConnectableAPI ( ) const

Contructs and returns a UsdShadeConnectableAPI object with this light.

Note that most tasks can be accomplished without explicitly constructing a UsdShadeConnectable API, since connection-related API such as UsdShadeConnectableAPI::ConnectToSource() are static methods, and UsdLuxLightAPI will auto-convert to a UsdShadeConnectableAPI when passed to functions that want to act generically on a connectable UsdShadeConnectableAPI object.

◆ CreateColorAttr()

USDLUX_API UsdAttribute CreateColorAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetColorAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateColorTemperatureAttr()

USDLUX_API UsdAttribute CreateColorTemperatureAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetColorTemperatureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateDiffuseAttr()

USDLUX_API UsdAttribute CreateDiffuseAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetDiffuseAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateEnableColorTemperatureAttr()

USDLUX_API UsdAttribute CreateEnableColorTemperatureAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetEnableColorTemperatureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateExposureAttr()

USDLUX_API UsdAttribute CreateExposureAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetExposureAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateFiltersRel()

USDLUX_API UsdRelationship CreateFiltersRel ( ) const

See GetFiltersRel(), and also Create vs Get Property Methods for when to use Get vs Create.

◆ CreateInput()

USDLUX_API UsdShadeInput CreateInput ( const TfToken name,
const SdfValueTypeName typeName 
)

Create an input which can either have a value or can be connected.

The attribute representing the input is created in the "inputs:" namespace. Inputs on lights are connectable.

◆ CreateIntensityAttr()

USDLUX_API UsdAttribute CreateIntensityAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetIntensityAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateMaterialSyncModeAttr()

USDLUX_API UsdAttribute CreateMaterialSyncModeAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetMaterialSyncModeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateNormalizeAttr()

USDLUX_API UsdAttribute CreateNormalizeAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetNormalizeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateOutput()

USDLUX_API UsdShadeOutput CreateOutput ( const TfToken name,
const SdfValueTypeName typeName 
)

Create an output which can either have a value or can be connected.

The attribute representing the output is created in the "outputs:" namespace. Outputs on a light cannot be connected, as their value is assumed to be computed externally.

◆ CreateShaderIdAttr()

USDLUX_API UsdAttribute CreateShaderIdAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetShaderIdAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateShaderIdAttrForRenderContext()

USDLUX_API UsdAttribute CreateShaderIdAttrForRenderContext ( const TfToken renderContext,
VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

Creates the shader ID attribute for the given renderContext.

See GetShaderIdAttrForRenderContext(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateSpecularAttr()

USDLUX_API UsdAttribute CreateSpecularAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetSpecularAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ Get()

static USDLUX_API UsdLuxLightAPI Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdLuxLightAPI holding the prim adhering to this schema at path on stage.

If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdLuxLightAPI(stage->GetPrimAtPath(path));
API schema that imparts the quality of being a light onto a prim.
Definition: lightAPI.h:73

◆ GetColorAttr()

USDLUX_API UsdAttribute GetColorAttr ( ) const

The color of emitted light, in energy-linear terms.

Declaration color3f inputs:color = (1, 1, 1)
C++ Type GfVec3f
Usd Type SdfValueTypeNames->Color3f

◆ GetColorTemperatureAttr()

USDLUX_API UsdAttribute GetColorTemperatureAttr ( ) const

Color temperature, in degrees Kelvin, representing the white point.

The default is a common white point, D65. Lower values are warmer and higher values are cooler. The valid range is from 1000 to 10000. Only takes effect when enableColorTemperature is set to true. When active, the computed result multiplies against the color attribute. See UsdLuxBlackbodyTemperatureAsRgb().

Declaration float inputs:colorTemperature = 6500
C++ Type float
Usd Type SdfValueTypeNames->Float

◆ GetDiffuseAttr()

USDLUX_API UsdAttribute GetDiffuseAttr ( ) const

A multiplier for the effect of this light on the diffuse response of materials.

This is a non-physical control.

Declaration float inputs:diffuse = 1
C++ Type float
Usd Type SdfValueTypeNames->Float

◆ GetEnableColorTemperatureAttr()

USDLUX_API UsdAttribute GetEnableColorTemperatureAttr ( ) const

Enables using colorTemperature.

Declaration bool inputs:enableColorTemperature = 0
C++ Type bool
Usd Type SdfValueTypeNames->Bool

◆ GetExposureAttr()

USDLUX_API UsdAttribute GetExposureAttr ( ) const

Scales the power of the light exponentially as a power of 2 (similar to an F-stop control over exposure).

The result is multiplied against the intensity.

Declaration float inputs:exposure = 0
C++ Type float
Usd Type SdfValueTypeNames->Float

◆ GetFiltersRel()

USDLUX_API UsdRelationship GetFiltersRel ( ) const

Relationship to the light filters that apply to this light.

◆ GetInput()

USDLUX_API UsdShadeInput GetInput ( const TfToken name) const

Return the requested input if it exists.

◆ GetInputs()

USDLUX_API std::vector< UsdShadeInput > GetInputs ( bool  onlyAuthored = true) const

Inputs are represented by attributes in the "inputs:" namespace.

If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

◆ GetIntensityAttr()

USDLUX_API UsdAttribute GetIntensityAttr ( ) const

Scales the power of the light linearly.

Declaration float inputs:intensity = 1
C++ Type float
Usd Type SdfValueTypeNames->Float

◆ GetLightLinkCollectionAPI()

USDLUX_API UsdCollectionAPI GetLightLinkCollectionAPI ( ) const

Return the UsdCollectionAPI interface used for examining and modifying the light-linking of this light.

Light-linking controls which geometry this light illuminates.

◆ GetMaterialSyncModeAttr()

USDLUX_API UsdAttribute GetMaterialSyncModeAttr ( ) const

For a LightAPI applied to geometry that has a bound Material, which is entirely or partly emissive, this specifies the relationship of the Material response to the lighting response.

Valid values are:

  • materialGlowTintsLight: All primary and secondary rays see the emissive/glow response as dictated by the bound Material while the base color seen by light rays (which is then modulated by all of the other LightAPI controls) is the multiplication of the color feeding the emission/glow input of the Material (i.e. its surface or volume shader) with the scalar or pattern input to inputs:color. This allows the light's color to tint the geometry's glow color while preserving access to intensity and other light controls as ways to further modulate the illumination.
  • independent: All primary and secondary rays see the emissive/glow response as dictated by the bound Material, while the base color seen by light rays is determined solely by inputs:color. Note that for partially emissive geometry (in which some parts are reflective rather than emissive), a suitable pattern must be connected to the light's color input, or else the light will radiate uniformly from the geometry.
  • noMaterialResponse: The geometry behaves as if there is no Material bound at all, i.e. there is no diffuse, specular, or transmissive response. The base color of light rays is entirely controlled by the inputs:color. This is the standard mode for "canonical" lights in UsdLux and indicates to renderers that a Material will either never be bound or can always be ignored.
Declaration uniform token light:materialSyncMode = "noMaterialResponse"
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform
Allowed Values materialGlowTintsLight, independent, noMaterialResponse

◆ GetNormalizeAttr()

USDLUX_API UsdAttribute GetNormalizeAttr ( ) const

Normalizes power by the surface area of the light.

This makes it easier to independently adjust the power and shape of the light, by causing the power to not vary with the area or angular size of the light.

Declaration bool inputs:normalize = 0
C++ Type bool
Usd Type SdfValueTypeNames->Bool

◆ GetOutput()

USDLUX_API UsdShadeOutput GetOutput ( const TfToken name) const

Return the requested output if it exists.

◆ GetOutputs()

USDLUX_API std::vector< UsdShadeOutput > GetOutputs ( bool  onlyAuthored = true) const

Outputs are represented by attributes in the "outputs:" namespace.

If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

◆ GetSchemaAttributeNames()

static USDLUX_API const TfTokenVector & GetSchemaAttributeNames ( bool  includeInherited = true)
static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

◆ GetShaderId()

USDLUX_API TfToken GetShaderId ( const TfTokenVector renderContexts) const

Return the light's shader ID for the given list of available renderContexts.

The shader ID returned by this function is the identifier to use when looking up the shader definition for this light in the shader registry.

The render contexts are expected to be listed in priority order, so for each render context provided, this will try to find the shader ID attribute specific to that render context (see GetShaderIdAttrForRenderContext()) and will return the value of the first one found that has a non-empty value. If no shader ID value can be found for any of the given render contexts or renderContexts is empty, then this will return the value of the default shader ID attribute (see GetShaderIdAttr()).

◆ GetShaderIdAttr()

USDLUX_API UsdAttribute GetShaderIdAttr ( ) const

Default ID for the light's shader.

This defines the shader ID for this light when a render context specific shader ID is not available.

The default shaderId for the intrinsic UsdLux lights (RectLight, DistantLight, etc.) are set to default to the light's type name. For each intrinsic UsdLux light, we will always register an SdrShaderNode in the SdrRegistry, with the identifier matching the type name and the source type "USD", that corresponds to the light's inputs.

See also
GetShaderId
GetShaderIdAttrForRenderContext
SdrRegistry::GetShaderNodeByIdentifier
SdrRegistry::GetShaderNodeByIdentifierAndType
Declaration uniform token light:shaderId = ""
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform

◆ GetShaderIdAttrForRenderContext()

USDLUX_API UsdAttribute GetShaderIdAttrForRenderContext ( const TfToken renderContext) const

Returns the shader ID attribute for the given renderContext.

If renderContext is non-empty, this will try to return an attribute named light:shaderId with the namespace prefix renderContext. For example, if the passed in render context is "ri" then the attribute returned by this function would have the following signature:

Declaration token ri:light:shaderId
C++ Type TfToken
Usd Type SdfValueTypeNames->Token

If the render context is empty, this will return the default shader ID attribute as returned by GetShaderIdAttr().

◆ GetShadowLinkCollectionAPI()

USDLUX_API UsdCollectionAPI GetShadowLinkCollectionAPI ( ) const

Return the UsdCollectionAPI interface used for examining and modifying the shadow-linking of this light.

Shadow-linking controls which geometry casts shadows from this light.

◆ GetSpecularAttr()

USDLUX_API UsdAttribute GetSpecularAttr ( ) const

A multiplier for the effect of this light on the specular response of materials.

This is a non-physical control.

Declaration float inputs:specular = 1
C++ Type float
Usd Type SdfValueTypeNames->Float

Friends And Related Function Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 170 of file lightAPI.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI
static

Compile time constant representing what kind of schema this class is.

See also
UsdSchemaKind

Definition at line 78 of file lightAPI.h.


The documentation for this class was generated from the following file: