usdrt::UsdLuxLightAPI

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

Functions

Variables

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 operator bool() const

Boolean operator.

Returns

Return true if the contained prim is has this api schema applied using HasAPI, and false otherwise.

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.

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.