usdrt::UsdLuxLightAPI

Defined in usdrt/scenegraph/usd/usdLux/lightAPI.h

class UsdLuxLightAPI : public usdrt::UsdAPISchemaBase 

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.

Public Functions

inline explicit UsdLuxLightAPI(const UsdPrim &prim = UsdPrim()): 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.

inline explicit UsdLuxLightAPI(const UsdSchemaBase &schemaObj): Construct a UsdLuxLightAPI on the prim held by schemaObj . Should be preferred over UsdLuxLightAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdLuxLightAPI(): Destructor.

inline UsdAttribute GetCollectionLightLinkIncludeRootAttr() const


Declaration	`uniform bool collection:lightLink:includeRoot = 1`
C++ Type	bool
Usd Type	SdfValueTypeNames->Bool
Variability	SdfVariabilityUniform

inline UsdAttribute CreateCollectionLightLinkIncludeRootAttr() const: See GetCollectionLightLinkIncludeRootAttr(), 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.

inline UsdAttribute GetCollectionShadowLinkIncludeRootAttr() const


Declaration	`uniform bool collection:shadowLink:includeRoot = 1`
C++ Type	bool
Usd Type	SdfValueTypeNames->Bool
Variability	SdfVariabilityUniform

inline UsdAttribute CreateCollectionShadowLinkIncludeRootAttr() const: See GetCollectionShadowLinkIncludeRootAttr(), 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.

inline 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.


Declaration	`uniform token light:shaderId = ""`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform

See also

GetShaderId

See also

GetShaderIdAttrForRenderContext

See also

SdrRegistry::GetShaderNodeByIdentifier

See also

SdrRegistry::GetShaderNodeByIdentifierAndType

inline UsdAttribute CreateShaderIdAttr() 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.

inline 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

inline UsdAttribute CreateMaterialSyncModeAttr() 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.

inline UsdAttribute GetIntensityAttr() const

Scales the power of the light linearly.


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

inline UsdAttribute CreateIntensityAttr() 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.

inline 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

inline UsdAttribute CreateExposureAttr() 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.

inline 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

inline UsdAttribute CreateDiffuseAttr() 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.

inline 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

inline UsdAttribute CreateSpecularAttr() 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.

inline 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

inline UsdAttribute CreateNormalizeAttr() 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.

inline 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

inline UsdAttribute CreateColorAttr() 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.

inline UsdAttribute GetEnableColorTemperatureAttr() const

Enables using colorTemperature.


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

inline UsdAttribute CreateEnableColorTemperatureAttr() 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.

inline 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

inline UsdAttribute CreateColorTemperatureAttr() 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.

inline UsdRelationship GetFiltersRel() const: Relationship to the light filters that apply to this light.

inline UsdRelationship CreateFiltersRel() const: See GetFiltersRel(), and also Create vs Get Property Methods for when to use Get vs Create.

UsdPrim GetPrim() const: Return this schema object’s held prim.

SdfPath GetPath() const: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

Returns: True if the help prim is valid, and the schema object is compatible with its held prim.

Public Static Functions

static inline UsdLuxLightAPI Apply(const UsdPrim &prim)

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.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

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.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::SingleApplyAPI 

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

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

inline const TfToken _GetType() const

Helper for subclasses to get this schema’s type token.

Note

This diverges from Usd and returns a TfToken, since we don’t implements TfType.

Returns: The token representing the schema’s TfType.