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 brightness 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 brightness 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 the emission such that the power of the light remains constant while altering the size of the light, by dividing the luminance by the world-space 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 the rendering color space.

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< UsdShadeOutput >	GetOutputs (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< UsdShadeInput >	GetInputs (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 UsdPrimDefinition *	GetSchemaClassPrimDefinition () 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 TfTokenVector &	GetSchemaAttributeNames (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 TfTokenVector &	GetSchemaAttributeNames (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 TfTokenVector &	GetSchemaAttributeNames (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.

Quantities and Units

Most renderers consuming OpenUSD today are RGB renderers, rather than spectral. Units in RGB renderers are tricky to define as each of the red, green and blue channels transported by the renderer represents the convolution of a spectral exposure distribution, e.g. CIE Illuminant D65, with a sensor response function, e.g. CIE 1931 𝓍̅. Thus the main quantity in an RGB renderer is neither radiance nor luminance, but "integrated radiance" or "tristimulus weight".

The emission of a default light with intensity 1 and color [1, 1, 1] is an Illuminant D spectral distribution with chromaticity matching the rendering color space white point, normalized such that a ray normally incident upon the sensor with EV0 exposure settings will generate a pixel value of [1, 1, 1] in the rendering color space.

Given the above definition, that means that the luminance of said default light will be 1 nit (cd∕m²) and its emission spectral radiance distribution is easily computed by appropriate normalization.

For brevity, the term emission will be used in the documentation to mean "emitted spectral radiance" or "emitted integrated radiance/tristimulus weight", as appropriate.

The method of "uplifting" an RGB color to a spectral distribution is unspecified other than that it should round-trip under the rendering illuminant to the limits of numerical accuracy.

Note that some color spaces, most notably ACES, define their white points by chromaticity coordinates that do not exactly line up to any value of a standard illuminant. Because we do not define the method of uplift beyond the round-tripping requirement, we discourage the use of such color spaces as the rendering color space, and instead encourage the use of color spaces whose white point has a well-defined spectral representation, such as D65.

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 107 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 119 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 127 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));

UsdLuxLightAPI

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

Definition: lightAPI.h:108

◆ GetColorAttr()

USDLUX_API UsdAttribute GetColorAttr ( ) const

The color of emitted light, in the rendering color space.

This color is just multiplied with the emission:

L_Color = L_Scalar ⋅ color

In the case of a spectral renderer, this color should be uplifted such that it round-trips to within the limit of numerical accuracy under the rendering illuminant. We recommend the use of a rendering color space well defined in terms of a Illuminant D illuminant (ideally a D illuminant whose white point has a well-defined spectral representation, such as D65), to avoid unspecified uplift. See: Quantities and Units


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().

This is always calculated as an RGB color using a D65 white point, regardless of the rendering color space, normalized such that the default value of 6500 will always result in white, and then should be transformed to the rendering color space.

Spectral renderers should do the same and then uplift the resulting color after multiplying with the color attribute. We recommend the use of a rendering color space well defined in terms of a Illuminant D illuminant, to avoid unspecified uplift. See: Quantities and Units


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 brightness of the light exponentially as a power of 2 (similar to an F-stop control over exposure).

The result is multiplied against the intensity:

L_Scalar = L_Scalar ⋅ 2^exposure

Normatively, the lights' emission is in units of spectral radiance normalized such that a directly visible light with intensity 1 and exposure 0 normally incident upon the sensor plane will generate a pixel value of [1, 1, 1] in an RGB renderer, and thus have a luminance of 1 nit (cd∕m²). A light with intensity 1 and exposure 2 would therefore have a luminance of 4 nits.


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 brightness of the light linearly.

Expresses the "base", unmultiplied luminance emitted (L) of the light, in nits (cd∕m²):

L_Scalar = intensity

Normatively, the lights' emission is in units of spectral radiance normalized such that a directly visible light with intensity 1 and exposure 0 normally incident upon the sensor plane will generate a pixel value of [1, 1, 1] in an RGB renderer, and thus have a luminance of 1 nit. A light with intensity 2 and exposure 0 would therefore have a luminance of 2 nits.


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 the emission such that the power of the light remains constant while altering the size of the light, by dividing the luminance by the world-space surface area of the light.

This makes it easier to independently adjust the brightness and size of the light, by causing the total illumination provided by a light to not vary with the area or angular size of the light.

Mathematically, this means that the luminance of the light will be divided by a factor representing the "size" of the light:

L_Scalar = L_Scalar / sizeFactor

...where sizeFactor = 1 if normalize is off, and is calculated depending on the family of the light as described below if normalize is on.

DomeLight / PortalLight:

For a dome light (and its associated PortalLight), this attribute is ignored:

sizeFactor_dome = 1

Area Lights:

For an area light, the sizeFactor is the surface area (in world space) of the shape of the light, including any scaling applied to the light by its transform stack. This includes the boundable light types which have a calculable surface area:

MeshLightAPI
DiskLight
RectLight
SphereLight
CylinderLight

sizeFactor_area = worldSpaceSurfaceArea(light)

DistantLight:

For distant lights, we first define 𝛳_max as:

𝛳_max = clamp(toRadians(distantLightAngle) / 2, 0, 𝜋)

Then we use the following formula:

if 𝛳_max = 0: sizeFactor_distant = 1
if 0 < 𝛳_max ≤ 𝜋 / 2: sizeFactor_distant = sin²𝛳_max ⋅ 𝜋
if 𝜋 / 2 < 𝛳_max ≤ 𝜋: sizeFactor_distant = (2 - sin²𝛳_max) ⋅ 𝜋

This formula is used because it satisfies the following two properties:

When normalize is enabled, the received illuminance from this light on a surface normal to the light's primary direction is held constant when angle changes, and the "intensity" property becomes a measure of the illuminance, expressed in lux, for a light with 0 exposure.
If we assume that our distant light is an approximation for a "very far" sphere light (like the sun), then (for *0 < 𝛳_max ≤ 𝜋/2*) this definition agrees with the definition used for area lights - i.e., the total power of this distant sphere light is constant when the "size" (i.e., angle) changes, and our sizeFactor is proportional to the total surface area of this sphere.

Other Lights

The above taxonomy describes behavior for all built-in light types. (Note that the above is based on schema family - i.e., DomeLight_1 follows the rules for a DomeLight, and ignores normalize).

Lights from other third-party plugins / schemas must document their expected behavior with regards to normalize. However, some general guidelines are:

Lights that either inherit from or are strongly associated with one of the built-in types should follow the behavior of the built-in type they inherit/resemble; i.e., a renderer-specific "MyRendererRectLight" should have its size factor be its world-space surface area.
Lights that are boundable and have a calculable surface area should follow the rules for an Area Light, and have their sizeFactor be their world-space surface area.
Lights that are non-boundable and/or have no way to concretely or even "intuitively" associate them with a "size" will ignore this attribute (and always set sizeFactor = 1).

Lights that don't clearly meet any of the above criteria may either ignore the normalize attribute or try to implement support using whatever heuristic seems to make sense. For instance, MyMandelbulbLight might use a sizeFactor equal to the world-space surface area of a sphere which "roughly" bounds it.


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 205 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 113 of file lightAPI.h.

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

pxr/usd/usdLux/lightAPI.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ UsdLuxLightAPI() [1/3]

◆ UsdLuxLightAPI() [2/3]

◆ ~UsdLuxLightAPI()

◆ UsdLuxLightAPI() [3/3]

Member Function Documentation

◆ _GetSchemaKind()

◆ Apply()

◆ CanApply()

◆ ConnectableAPI()

◆ CreateColorAttr()

◆ CreateColorTemperatureAttr()

◆ CreateDiffuseAttr()

◆ CreateEnableColorTemperatureAttr()

◆ CreateExposureAttr()

◆ CreateFiltersRel()

◆ CreateInput()

◆ CreateIntensityAttr()

◆ CreateMaterialSyncModeAttr()

◆ CreateNormalizeAttr()

◆ CreateOutput()

◆ CreateShaderIdAttr()

◆ CreateShaderIdAttrForRenderContext()

◆ CreateSpecularAttr()

◆ Get()

◆ GetColorAttr()

◆ GetColorTemperatureAttr()

◆ GetDiffuseAttr()

◆ GetEnableColorTemperatureAttr()

◆ GetExposureAttr()

◆ GetFiltersRel()

◆ GetInput()

◆ GetInputs()

◆ GetIntensityAttr()

◆ GetLightLinkCollectionAPI()

◆ GetMaterialSyncModeAttr()

◆ GetNormalizeAttr()

DomeLight / PortalLight:

Area Lights:

DistantLight:

Other Lights

◆ GetOutput()

◆ GetOutputs()

◆ GetSchemaAttributeNames()

◆ GetShaderId()

◆ GetShaderIdAttr()

◆ GetShaderIdAttrForRenderContext()

◆ GetShadowLinkCollectionAPI()

◆ GetSpecularAttr()

Friends And Related Function Documentation

◆ UsdSchemaRegistry

Member Data Documentation

◆ schemaKind