UsdLux module#

Summary: The UsdLux module provides a representation for lights and related components that are common to many graphics environments.

Classes:

BoundableLightBase

Base class for intrinsic lights that are boundable.

CylinderLight

Light emitted outward from a cylinder.

DiskLight

Light emitted from one side of a circular disk.

DistantLight

Light emitted from a distant source along the -Z axis.

DomeLight

Light emitted inward from a distant external environment, such as a sky or IBL light probe.

GeometryLight

Deprecated

LightAPI

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

LightFilter

A light filter modifies the effect of a light.

LightListAPI

API schema to support discovery and publishing of lights in a scene.

ListAPI

Deprecated

MeshLightAPI

This is the preferred API schema to apply to Mesh type prims when adding light behaviors to a mesh.

NonboundableLightBase

Base class for intrinsic lights that are not boundable.

PluginLight

Light that provides properties that allow it to identify an external SdrShadingNode definition, through UsdShadeNodeDefAPI, that can be provided to render delegates without the need to provide a schema definition for the light's type.

PluginLightFilter

Light filter that provides properties that allow it to identify an external SdrShadingNode definition, through UsdShadeNodeDefAPI, that can be provided to render delegates without the need to provide a schema definition for the light filter's type.

PortalLight

A rectangular portal in the local XY plane that guides sampling of a dome light.

RectLight

Light emitted from one side of a rectangle.

ShadowAPI

Controls to refine a light's shadow behavior.

ShapingAPI

Controls for shaping a light's emission.

SphereLight

Light emitted outward from a sphere.

Tokens

VolumeLightAPI

This is the preferred API schema to apply to Volume type prims when adding light behaviors to a volume.
class pxr.UsdLux.BoundableLightBase

Base class for intrinsic lights that are boundable.

The primary purpose of this class is to provide a direct API to the functions provided by LightAPI for concrete derived light types.

Methods:

CreateColorAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateColorAttr() .

CreateColorTemperatureAttr(defaultValue, ...)

See UsdLuxLightAPI::CreateColorTemperatureAttr() .

CreateDiffuseAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateDiffuseAttr() .

CreateEnableColorTemperatureAttr(...)

See UsdLuxLightAPI::CreateEnableColorTemperatureAttr() .

CreateExposureAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateExposureAttr() .

CreateFiltersRel()

See UsdLuxLightAPI::CreateFiltersRel() .

CreateIntensityAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateIntensityAttr() .

CreateNormalizeAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateNormalizeAttr() .

CreateSpecularAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateSpecularAttr() .

Get

classmethod Get(stage, path) -> BoundableLightBase

GetColorAttr()

See UsdLuxLightAPI::GetColorAttr() .

GetColorTemperatureAttr()

See UsdLuxLightAPI::GetColorTemperatureAttr() .

GetDiffuseAttr()

See UsdLuxLightAPI::GetDiffuseAttr() .

GetEnableColorTemperatureAttr()

See UsdLuxLightAPI::GetEnableColorTemperatureAttr() .

GetExposureAttr()

See UsdLuxLightAPI::GetExposureAttr() .

GetFiltersRel()

See UsdLuxLightAPI::GetFiltersRel() .

GetIntensityAttr()

See UsdLuxLightAPI::GetIntensityAttr() .

GetNormalizeAttr()

See UsdLuxLightAPI::GetNormalizeAttr() .

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetSpecularAttr()

See UsdLuxLightAPI::GetSpecularAttr() .

LightAPI()

Contructs and returns a UsdLuxLightAPI object for this light.
CreateColorAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateColorAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateColorTemperatureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateDiffuseAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateDiffuseAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateEnableColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateEnableColorTemperatureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateExposureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateExposureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateFiltersRel() → Relationship

See UsdLuxLightAPI::CreateFiltersRel() .

CreateIntensityAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateIntensityAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateNormalizeAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateNormalizeAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateSpecularAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateSpecularAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Get()

classmethod Get(stage, path) -> BoundableLightBase

Return a UsdLuxBoundableLightBase 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:

UsdLuxBoundableLightBase(stage->GetPrimAtPath(path));
Parameters:
GetColorAttr() → Attribute

See UsdLuxLightAPI::GetColorAttr() .

GetColorTemperatureAttr() → Attribute

See UsdLuxLightAPI::GetColorTemperatureAttr() .

GetDiffuseAttr() → Attribute

See UsdLuxLightAPI::GetDiffuseAttr() .

GetEnableColorTemperatureAttr() → Attribute

See UsdLuxLightAPI::GetEnableColorTemperatureAttr() .

GetExposureAttr() → Attribute

See UsdLuxLightAPI::GetExposureAttr() .

GetFiltersRel() → Relationship

See UsdLuxLightAPI::GetFiltersRel() .

GetIntensityAttr() → Attribute

See UsdLuxLightAPI::GetIntensityAttr() .

GetNormalizeAttr() → Attribute

See UsdLuxLightAPI::GetNormalizeAttr() .

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetSpecularAttr() → Attribute

See UsdLuxLightAPI::GetSpecularAttr() .

LightAPI() → LightAPI

Contructs and returns a UsdLuxLightAPI object for this light.

class pxr.UsdLux.CylinderLight

Light emitted outward from a cylinder. The cylinder is centered at the origin and has its major axis on the X axis. The cylinder does not emit light from the flat end-caps.

Methods:

CreateLengthAttr(defaultValue, writeSparsely)

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

CreateRadiusAttr(defaultValue, writeSparsely)

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

CreateTreatAsLineAttr(defaultValue, ...)

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

Define

classmethod Define(stage, path) -> CylinderLight

Get

classmethod Get(stage, path) -> CylinderLight

GetLengthAttr()

Width of the rectangle, in the local X axis.

GetRadiusAttr()

Radius of the cylinder.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetTreatAsLineAttr()

A hint that this light can be treated as a'line'light (effectively, a zero-radius cylinder) by renderers that benefit from non-area lighting.
CreateLengthAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetLengthAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateRadiusAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetRadiusAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateTreatAsLineAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetTreatAsLineAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> CylinderLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> CylinderLight

Return a UsdLuxCylinderLight 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:

UsdLuxCylinderLight(stage->GetPrimAtPath(path));
Parameters:
GetLengthAttr() → Attribute

Width of the rectangle, in the local X axis.

Declaration

float inputs:length = 1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetRadiusAttr() → Attribute

Radius of the cylinder.

Declaration

float inputs:radius = 0.5

C++ Type

float

Usd Type

SdfValueTypeNames->Float

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetTreatAsLineAttr() → Attribute

A hint that this light can be treated as a’line’light (effectively, a zero-radius cylinder) by renderers that benefit from non-area lighting.

Renderers that only support area lights can disregard this.

Declaration

bool treatAsLine = 0

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

class pxr.UsdLux.DiskLight

Light emitted from one side of a circular disk. The disk is centered in the XY plane and emits light along the -Z axis.

Methods:

CreateRadiusAttr(defaultValue, writeSparsely)

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

Define

classmethod Define(stage, path) -> DiskLight

Get

classmethod Get(stage, path) -> DiskLight

GetRadiusAttr()

Radius of the disk.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
CreateRadiusAttr(defaultValue, writeSparsely) → Attribute

See GetRadiusAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> DiskLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> DiskLight

Return a UsdLuxDiskLight 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:

UsdLuxDiskLight(stage->GetPrimAtPath(path));
Parameters:
GetRadiusAttr() → Attribute

Radius of the disk.

Declaration

float inputs:radius = 0.5

C++ Type

float

Usd Type

SdfValueTypeNames->Float

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.DistantLight

Light emitted from a distant source along the -Z axis. Also known as a directional light.

Methods:

CreateAngleAttr(defaultValue, writeSparsely)

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

Define

classmethod Define(stage, path) -> DistantLight

Get

classmethod Get(stage, path) -> DistantLight

GetAngleAttr()

Angular size of the light in degrees.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
CreateAngleAttr(defaultValue, writeSparsely) → Attribute

See GetAngleAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> DistantLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> DistantLight

Return a UsdLuxDistantLight 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:

UsdLuxDistantLight(stage->GetPrimAtPath(path));
Parameters:
GetAngleAttr() → Attribute

Angular size of the light in degrees.

As an example, the Sun is approximately 0.53 degrees as seen from Earth. Higher values broaden the light and therefore soften shadow edges.

Declaration

float inputs:angle = 0.53

C++ Type

float

Usd Type

SdfValueTypeNames->Float

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.DomeLight

Light emitted inward from a distant external environment, such as a sky or IBL light probe. The orientation of a dome light with a latlong texture is expected to match the OpenEXR specification for latlong environment maps. From the OpenEXR documentation:

Latitude-Longitude Map:

The environment is projected onto the image using polar coordinates (latitude and longitude). A pixel’s x coordinate corresponds to its longitude, and the y coordinate corresponds to its latitude. Pixel (dataWindow.min.x, dataWindow.min.y) has latitude +pi/2 and longitude +pi; pixel (dataWindow.max.x, dataWindow.max.y) has latitude -pi/2 and longitude -pi.

In 3D space, latitudes -pi/2 and +pi/2 correspond to the negative and positive y direction. Latitude 0, longitude 0 points into positive z direction; and latitude 0, longitude pi/2 points into positive x direction.

The size of the data window should be 2*N by N pixels (width by height),

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.

Methods:

CreateGuideRadiusAttr(defaultValue, ...)

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

CreatePortalsRel()

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

CreateTextureFileAttr(defaultValue, ...)

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

CreateTextureFormatAttr(defaultValue, ...)

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

Define

classmethod Define(stage, path) -> DomeLight

Get

classmethod Get(stage, path) -> DomeLight

GetGuideRadiusAttr()

The radius of guide geometry to use to visualize the dome light.

GetPortalsRel()

Optional portals to guide light sampling.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetTextureFileAttr()

A color texture to use on the dome, such as an HDR (high dynamic range) texture intended for IBL (image based lighting).

GetTextureFormatAttr()

Specifies the parameterization of the color map file.

OrientToStageUpAxis()

Adds a transformation op, if neeeded, to orient the dome to align with the stage's up axis.
CreateGuideRadiusAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetGuideRadiusAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreatePortalsRel() → Relationship

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

CreateTextureFileAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetTextureFileAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateTextureFormatAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetTextureFormatAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> DomeLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> DomeLight

Return a UsdLuxDomeLight 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:

UsdLuxDomeLight(stage->GetPrimAtPath(path));
Parameters:
GetGuideRadiusAttr() → Attribute

The radius of guide geometry to use to visualize the dome light.

The default is 1 km for scenes whose metersPerUnit is the USD default of 0.01 (i.e., 1 world unit is 1 cm).

Declaration

float guideRadius = 100000

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetPortalsRel() → Relationship

Optional portals to guide light sampling.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetTextureFileAttr() → Attribute

A color texture to use on the dome, such as an HDR (high dynamic range) texture intended for IBL (image based lighting).

Declaration

asset inputs:texture:file

C++ Type

SdfAssetPath

Usd Type

SdfValueTypeNames->Asset

GetTextureFormatAttr() → Attribute

Specifies the parameterization of the color map file.

Valid values are:

  • automatic: Tries to determine the layout from the file itself. For example, Renderman texture files embed an explicit parameterization.

  • latlong: Latitude as X, longitude as Y.

  • mirroredBall: An image of the environment reflected in a sphere, using an implicitly orthogonal projection.

  • angular: Similar to mirroredBall but the radial dimension is mapped linearly to the angle, providing better sampling at the edges.

  • cubeMapVerticalCross: A cube map with faces laid out as a vertical cross.

Declaration

token inputs:texture:format ="automatic"

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Allowed Values

automatic, latlong, mirroredBall, angular, cubeMapVerticalCross

OrientToStageUpAxis() → None

Adds a transformation op, if neeeded, to orient the dome to align with the stage’s up axis.

Uses UsdLuxTokens->orientToStageUpAxis as the op suffix. If an op with this suffix already exists, this method assumes it is already applying the proper correction and does nothing further. If no op is required to match the stage’s up axis, no op will be created.

UsdGeomXformOp

UsdGeomGetStageUpAxis

class pxr.UsdLux.GeometryLight

Deprecated

Light emitted outward from a geometric prim (UsdGeomGprim), which is typically a mesh.

Methods:

CreateGeometryRel()

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

Define

classmethod Define(stage, path) -> GeometryLight

Get

classmethod Get(stage, path) -> GeometryLight

GetGeometryRel()

Relationship to the geometry to use as the light source.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
CreateGeometryRel() → Relationship

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

static Define()

classmethod Define(stage, path) -> GeometryLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> GeometryLight

Return a UsdLuxGeometryLight 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:

UsdLuxGeometryLight(stage->GetPrimAtPath(path));
Parameters:
GetGeometryRel() → Relationship

Relationship to the geometry to use as the light source.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.LightAPI

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.

Methods:

Apply

classmethod Apply(prim) -> LightAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

ConnectableAPI()

Contructs and returns a UsdShadeConnectableAPI object with this light.

CreateColorAttr(defaultValue, writeSparsely)

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

CreateColorTemperatureAttr(defaultValue, ...)

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

CreateDiffuseAttr(defaultValue, writeSparsely)

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

CreateEnableColorTemperatureAttr(...)

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

CreateExposureAttr(defaultValue, writeSparsely)

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

CreateFiltersRel()

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

CreateInput(name, typeName)

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

CreateIntensityAttr(defaultValue, writeSparsely)

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

CreateMaterialSyncModeAttr(defaultValue, ...)

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

CreateNormalizeAttr(defaultValue, writeSparsely)

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

CreateOutput(name, typeName)

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

CreateShaderIdAttr(defaultValue, writeSparsely)

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

CreateShaderIdAttrForRenderContext(...)

Creates the shader ID attribute for the given renderContext .

CreateSpecularAttr(defaultValue, writeSparsely)

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

Get

classmethod Get(stage, path) -> LightAPI

GetColorAttr()

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

GetColorTemperatureAttr()

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

GetDiffuseAttr()

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

GetEnableColorTemperatureAttr()

Enables using colorTemperature.

GetExposureAttr()

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

GetFiltersRel()

Relationship to the light filters that apply to this light.

GetInput(name)

Return the requested input if it exists.

GetInputs(onlyAuthored)

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

GetIntensityAttr()

Scales the power of the light linearly.

GetLightLinkCollectionAPI()

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

GetMaterialSyncModeAttr()

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.

GetNormalizeAttr()

Normalizes power by the surface area of the light.

GetOutput(name)

Return the requested output if it exists.

GetOutputs(onlyAuthored)

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

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetShaderId(renderContexts)

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

GetShaderIdAttr()

Default ID for the light's shader.

GetShaderIdAttrForRenderContext(renderContext)

Returns the shader ID attribute for the given renderContext .

GetShadowLinkCollectionAPI()

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

GetSpecularAttr()

A multiplier for the effect of this light on the specular response of materials.
static Apply()

classmethod Apply(prim) -> LightAPI

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.

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

ConnectableAPI() → ConnectableAPI

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(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateDiffuseAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateEnableColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateExposureAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateFiltersRel() → Relationship

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

CreateInput(name, typeName) → Input

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.

Parameters:
CreateIntensityAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateMaterialSyncModeAttr(
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateNormalizeAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateOutput(name, typeName) → Output

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.

Parameters:
CreateShaderIdAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShaderIdAttrForRenderContext(
renderContext,
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • renderContext (str)

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateSpecularAttr(defaultValue, writeSparsely) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Get()

classmethod Get(stage, path) -> LightAPI

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));
Parameters:
GetColorAttr() → Attribute

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

Declaration

color3f inputs:color = (1, 1, 1)

C++ Type

GfVec3f

Usd Type

SdfValueTypeNames->Color3f

GetColorTemperatureAttr() → Attribute

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() → Attribute

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() → Attribute

Enables using colorTemperature.

Declaration

bool inputs:enableColorTemperature = 0

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

GetExposureAttr() → Attribute

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() → Relationship

Relationship to the light filters that apply to this light.

GetInput(name) → Input

Return the requested input if it exists.

Parameters:

name (str)

GetInputs(onlyAuthored) → list[Input]

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.

Parameters:

onlyAuthored (bool)

GetIntensityAttr() → Attribute

Scales the power of the light linearly.

Declaration

float inputs:intensity = 1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetLightLinkCollectionAPI() → CollectionAPI

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

Light-linking controls which geometry this light illuminates.

GetMaterialSyncModeAttr() → Attribute

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() → Attribute

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(name) → Output

Return the requested output if it exists.

Parameters:

name (str)

GetOutputs(onlyAuthored) → list[Output]

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.

Parameters:

onlyAuthored (bool)

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetShaderId(renderContexts) → str

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

Parameters:

renderContexts (list[str])

GetShaderIdAttr() → Attribute

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.

GetShaderId

GetShaderIdAttrForRenderContext

SdrRegistry::GetShaderNodeByIdentifier

SdrRegistry::GetShaderNodeByIdentifierAndType

Declaration

uniform token light:shaderId =""

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

GetShaderIdAttrForRenderContext(renderContext) → Attribute

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

Parameters:

renderContext (str)

GetShadowLinkCollectionAPI() → CollectionAPI

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() → Attribute

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

class pxr.UsdLux.LightFilter

A light filter modifies the effect of a light. Lights refer to filters via relationships so that filters may be shared.

Linking

Filters can be linked to geometry. Linking controls which geometry a light-filter affects, when considering the light filters attached to a light illuminating the geometry.

Linking is specified as a collection (UsdCollectionAPI) which can be accessed via GetFilterLinkCollection().

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.

Methods:

ConnectableAPI()

Contructs and returns a UsdShadeConnectableAPI object with this light filter.

CreateInput(name, typeName)

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

CreateOutput(name, typeName)

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

CreateShaderIdAttr(defaultValue, writeSparsely)

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

CreateShaderIdAttrForRenderContext(...)

Creates the shader ID attribute for the given renderContext .

Define

classmethod Define(stage, path) -> LightFilter

Get

classmethod Get(stage, path) -> LightFilter

GetFilterLinkCollectionAPI()

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

GetInput(name)

Return the requested input if it exists.

GetInputs(onlyAuthored)

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

GetOutput(name)

Return the requested output if it exists.

GetOutputs(onlyAuthored)

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

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetShaderId(renderContexts)

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

GetShaderIdAttr()

Default ID for the light filter's shader.

GetShaderIdAttrForRenderContext(renderContext)

Returns the shader ID attribute for the given renderContext .
ConnectableAPI() → ConnectableAPI

Contructs and returns a UsdShadeConnectableAPI object with this light filter.

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 UsdLuxLightFilter will auto-convert to a UsdShadeConnectableAPI when passed to functions that want to act generically on a connectable UsdShadeConnectableAPI object.

CreateInput(name, typeName) → Input

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 light filters are connectable.

Parameters:
CreateOutput(name, typeName) → Output

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 filter cannot be connected, as their value is assumed to be computed externally.

Parameters:
CreateShaderIdAttr(
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShaderIdAttrForRenderContext(
renderContext,
defaultValue,
writeSparsely,
) → Attribute

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 .

Parameters:

  • renderContext (str)

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> LightFilter

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> LightFilter

Return a UsdLuxLightFilter 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:

UsdLuxLightFilter(stage->GetPrimAtPath(path));
Parameters:
GetFilterLinkCollectionAPI() → CollectionAPI

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

Linking controls which geometry this light filter affects.

GetInput(name) → Input

Return the requested input if it exists.

Parameters:

name (str)

GetInputs(onlyAuthored) → list[Input]

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.

Parameters:

onlyAuthored (bool)

GetOutput(name) → Output

Return the requested output if it exists.

Parameters:

name (str)

GetOutputs(onlyAuthored) → list[Output]

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.

Parameters:

onlyAuthored (bool)

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetShaderId(renderContexts) → str

Return the light filter’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 filter 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() ).

Parameters:

renderContexts (list[str])

GetShaderIdAttr() → Attribute

Default ID for the light filter’s shader.

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

GetShaderId

GetShaderIdAttrForRenderContext

SdrRegistry::GetShaderNodeByIdentifier

SdrRegistry::GetShaderNodeByIdentifierAndType

Declaration

uniform token lightFilter:shaderId =""

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

GetShaderIdAttrForRenderContext(
renderContext,
) → Attribute

Returns the shader ID attribute for the given renderContext .

If renderContext is non-empty, this will try to return an attribute named lightFilter: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:lightFilter: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() .

Parameters:

renderContext (str)

class pxr.UsdLux.LightListAPI

API schema to support discovery and publishing of lights in a scene.

Discovering Lights via Traversal#

To motivate this API, consider what is required to discover all lights in a scene. We must load all payloads and traverse all prims:

01  // Load everything on the stage so we can find all lights,
02  // including those inside payloads
03  stage->Load();
04
05  // Traverse all prims, checking if they have an applied UsdLuxLightAPI
06  // (Note: ignoring instancing and a few other things for simplicity)
07  SdfPathVector lights;
08  for (UsdPrim prim: stage->Traverse()) {
09      if (prim.HasAPI<UsdLuxLightAPI>()) {
10          lights.push_back(i->GetPath());
11      }
12  }

This traversal suitably elaborated to handle certain details is the first and simplest thing UsdLuxLightListAPI provides. UsdLuxLightListAPI::ComputeLightList() performs this traversal and returns all lights in the scene:

01  UsdLuxLightListAPI listAPI(stage->GetPseudoRoot());
02  SdfPathVector lights = listAPI.ComputeLightList();

Publishing a Cached Light List#

Consider a USD client that needs to quickly discover lights but wants to defer loading payloads and traversing the entire scene where possible, and is willing to do up-front computation and caching to achieve that.

UsdLuxLightListAPI provides a way to cache the computed light list, by publishing the list of lights onto prims in the model hierarchy. Consider a big set that contains lights:

01  def Xform "BigSetWithLights" (
02      kind = "assembly"
03      payload = @BigSetWithLights.usd@   // Heavy payload
04  ) {
05      // Pre-computed, cached list of lights inside payload
06      rel lightList = [
07          <./Lights/light_1>,
08          <./Lights/light_2>,
09          \.\.\.
10      ]
11      token lightList:cacheBehavior = "consumeAndContinue";
12  }

The lightList relationship encodes a set of lights, and the lightList:cacheBehavior property provides fine-grained control over how to use that cache. (See details below.)

The cache can be created by first invoking ComputeLightList(ComputeModeIgnoreCache) to pre-compute the list and then storing the result with UsdLuxLightListAPI::StoreLightList() .

To enable efficient retrieval of the cache, it should be stored on a model hierarchy prim. Furthermore, note that while you can use a UsdLuxLightListAPI bound to the pseudo-root prim to query the lights (as in the example above) because it will perform a traversal over descendants, you cannot store the cache back to the pseduo-root prim.

To consult the cached list, we invoke ComputeLightList(ComputeModeConsultModelHierarchyCache):

01  // Find and load all lights, using lightList cache where available
02  UsdLuxLightListAPI list(stage->GetPseudoRoot());
03  SdfPathSet lights = list.ComputeLightList(
04      UsdLuxLightListAPI::ComputeModeConsultModelHierarchyCache);
05  stage.LoadAndUnload(lights, SdfPathSet());

In this mode, ComputeLightList() will traverse the model hierarchy, accumulating cached light lists.

Controlling Cache Behavior#

The lightList:cacheBehavior property gives additional fine-grained control over cache behavior:

  • The fallback value,”ignore”, indicates that the lightList should be disregarded. This provides a way to invalidate cache entries. Note that unless”ignore”is specified, a lightList with an empty list of targets is considered a cache indicating that no lights are present.

  • The value”consumeAndContinue”indicates that the cache should be consulted to contribute lights to the scene, and that recursion should continue down the model hierarchy in case additional lights are added as descedants. This is the default value established when StoreLightList() is invoked. This behavior allows the lights within a large model, such as the BigSetWithLights example above, to be published outside the payload, while also allowing referencing and layering to add additional lights over that set.

  • The value”consumeAndHalt”provides a way to terminate recursive traversal of the scene for light discovery. The cache will be consulted but no descendant prims will be examined.

Instancing#

Where instances are present, UsdLuxLightListAPI::ComputeLightList() will return the instance-unique paths to any lights discovered within those instances. Lights within a UsdGeomPointInstancer will not be returned, however, since they cannot be referred to solely via paths.

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.

Classes:

ComputeMode

Runtime control over whether to consult stored lightList caches.

Methods:

Apply

classmethod Apply(prim) -> LightListAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

ComputeLightList(mode)

Computes and returns the list of lights and light filters in the stage, optionally consulting a cached result.

CreateLightListCacheBehaviorAttr(...)

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

CreateLightListRel()

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

Get

classmethod Get(stage, path) -> LightListAPI

GetLightListCacheBehaviorAttr()

Controls how the lightList should be interpreted.

GetLightListRel()

Relationship to lights in the scene.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

InvalidateLightList()

Mark any stored lightlist as invalid, by setting the lightList:cacheBehavior attribute to ignore.

StoreLightList(arg1)

Store the given paths as the lightlist for this prim.

Attributes:

ComputeModeConsultModelHierarchyCache

ComputeModeIgnoreCache

class ComputeMode

Runtime control over whether to consult stored lightList caches.

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()
allValues = (UsdLux.LightListAPI.ComputeModeConsultModelHierarchyCache, UsdLux.LightListAPI.ComputeModeIgnoreCache)
static Apply()

classmethod Apply(prim) -> LightListAPI

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

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

A valid UsdLuxLightListAPI object is returned upon success. An invalid (or empty) UsdLuxLightListAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

ComputeLightList(mode) → SdfPathSet

Computes and returns the list of lights and light filters in the stage, optionally consulting a cached result.

In ComputeModeIgnoreCache mode, caching is ignored, and this does a prim traversal looking for prims that have a UsdLuxLightAPI or are of type UsdLuxLightFilter.

In ComputeModeConsultModelHierarchyCache, this does a traversal only of the model hierarchy. In this traversal, any lights that live as model hierarchy prims are accumulated, as well as any paths stored in lightList caches. The lightList:cacheBehavior attribute gives further control over the cache behavior; see the class overview for details.

When instances are present, ComputeLightList(ComputeModeIgnoreCache) will return the instance-uniqiue paths to any lights discovered within those instances. Lights within a UsdGeomPointInstancer will not be returned, however, since they cannot be referred to solely via paths.

Parameters:

mode (ComputeMode)

CreateLightListCacheBehaviorAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetLightListCacheBehaviorAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateLightListRel() → Relationship

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

static Get()

classmethod Get(stage, path) -> LightListAPI

Return a UsdLuxLightListAPI 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:

UsdLuxLightListAPI(stage->GetPrimAtPath(path));
Parameters:
GetLightListCacheBehaviorAttr() → Attribute

Controls how the lightList should be interpreted.

Valid values are:

  • consumeAndHalt: The lightList should be consulted, and if it exists, treated as a final authoritative statement of any lights that exist at or below this prim, halting recursive discovery of lights.

  • consumeAndContinue: The lightList should be consulted, but recursive traversal over nameChildren should continue in case additional lights are added by descendants.

  • ignore: The lightList should be entirely ignored. This provides a simple way to temporarily invalidate an existing cache. This is the fallback behavior.

Declaration

token lightList:cacheBehavior

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Allowed Values

consumeAndHalt, consumeAndContinue, ignore

GetLightListRel() → Relationship

Relationship to lights in the scene.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

InvalidateLightList() → None

Mark any stored lightlist as invalid, by setting the lightList:cacheBehavior attribute to ignore.

StoreLightList(arg1) → None

Store the given paths as the lightlist for this prim.

Paths that do not have this prim’s path as a prefix will be silently ignored. This will set the listList:cacheBehavior to”consumeAndContinue”.

Parameters:

arg1 (SdfPathSet)

ComputeModeConsultModelHierarchyCache = UsdLux.LightListAPI.ComputeModeConsultModelHierarchyCache
ComputeModeIgnoreCache = UsdLux.LightListAPI.ComputeModeIgnoreCache
class pxr.UsdLux.ListAPI

Deprecated

Use LightListAPI instead

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.

Classes:

ComputeMode

Runtime control over whether to consult stored lightList caches.

Methods:

Apply

classmethod Apply(prim) -> ListAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

ComputeLightList(mode)

Computes and returns the list of lights and light filters in the stage, optionally consulting a cached result.

CreateLightListCacheBehaviorAttr(...)

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

CreateLightListRel()

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

Get

classmethod Get(stage, path) -> ListAPI

GetLightListCacheBehaviorAttr()

Controls how the lightList should be interpreted.

GetLightListRel()

Relationship to lights in the scene.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

InvalidateLightList()

Mark any stored lightlist as invalid, by setting the lightList:cacheBehavior attribute to ignore.

StoreLightList(arg1)

Store the given paths as the lightlist for this prim.

Attributes:

ComputeModeConsultModelHierarchyCache

ComputeModeIgnoreCache

class ComputeMode

Runtime control over whether to consult stored lightList caches.

Methods:

GetValueFromName

Attributes:

allValues

static GetValueFromName()
allValues = (UsdLux.ListAPI.ComputeModeConsultModelHierarchyCache, UsdLux.ListAPI.ComputeModeIgnoreCache)
static Apply()

classmethod Apply(prim) -> ListAPI

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

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

A valid UsdLuxListAPI object is returned upon success. An invalid (or empty) UsdLuxListAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

ComputeLightList(mode) → SdfPathSet

Computes and returns the list of lights and light filters in the stage, optionally consulting a cached result.

In ComputeModeIgnoreCache mode, caching is ignored, and this does a prim traversal looking for prims that have a UsdLuxLightAPI or are of type UsdLuxLightFilter.

In ComputeModeConsultModelHierarchyCache, this does a traversal only of the model hierarchy. In this traversal, any lights that live as model hierarchy prims are accumulated, as well as any paths stored in lightList caches. The lightList:cacheBehavior attribute gives further control over the cache behavior; see the class overview for details.

When instances are present, ComputeLightList(ComputeModeIgnoreCache) will return the instance-uniqiue paths to any lights discovered within those instances. Lights within a UsdGeomPointInstancer will not be returned, however, since they cannot be referred to solely via paths.

Parameters:

mode (ComputeMode)

CreateLightListCacheBehaviorAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetLightListCacheBehaviorAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateLightListRel() → Relationship

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

static Get()

classmethod Get(stage, path) -> ListAPI

Return a UsdLuxListAPI 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:

UsdLuxListAPI(stage->GetPrimAtPath(path));
Parameters:
GetLightListCacheBehaviorAttr() → Attribute

Controls how the lightList should be interpreted.

Valid values are:

  • consumeAndHalt: The lightList should be consulted, and if it exists, treated as a final authoritative statement of any lights that exist at or below this prim, halting recursive discovery of lights.

  • consumeAndContinue: The lightList should be consulted, but recursive traversal over nameChildren should continue in case additional lights are added by descendants.

  • ignore: The lightList should be entirely ignored. This provides a simple way to temporarily invalidate an existing cache. This is the fallback behavior.

Declaration

token lightList:cacheBehavior

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Allowed Values

consumeAndHalt, consumeAndContinue, ignore

GetLightListRel() → Relationship

Relationship to lights in the scene.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

InvalidateLightList() → None

Mark any stored lightlist as invalid, by setting the lightList:cacheBehavior attribute to ignore.

StoreLightList(arg1) → None

Store the given paths as the lightlist for this prim.

Paths that do not have this prim’s path as a prefix will be silently ignored. This will set the listList:cacheBehavior to”consumeAndContinue”.

Parameters:

arg1 (SdfPathSet)

ComputeModeConsultModelHierarchyCache = UsdLux.ListAPI.ComputeModeConsultModelHierarchyCache
ComputeModeIgnoreCache = UsdLux.ListAPI.ComputeModeIgnoreCache
class pxr.UsdLux.MeshLightAPI

This is the preferred API schema to apply to Mesh type prims when adding light behaviors to a mesh. At its base, this API schema has the built-in behavior of applying LightAPI to the mesh and overriding the default materialSyncMode to allow the emission/glow of the bound material to affect the color of the light. But, it additionally serves as a hook for plugins to attach additional properties to”mesh lights”through the creation of API schemas which are authored to auto- apply to MeshLightAPI.

Auto applied API schemas

Methods:

Apply

classmethod Apply(prim) -> MeshLightAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

Get

classmethod Get(stage, path) -> MeshLightAPI

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
static Apply()

classmethod Apply(prim) -> MeshLightAPI

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

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

A valid UsdLuxMeshLightAPI object is returned upon success. An invalid (or empty) UsdLuxMeshLightAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

static Get()

classmethod Get(stage, path) -> MeshLightAPI

Return a UsdLuxMeshLightAPI 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:

UsdLuxMeshLightAPI(stage->GetPrimAtPath(path));
Parameters:
static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.NonboundableLightBase

Base class for intrinsic lights that are not boundable.

The primary purpose of this class is to provide a direct API to the functions provided by LightAPI for concrete derived light types.

Methods:

CreateColorAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateColorAttr() .

CreateColorTemperatureAttr(defaultValue, ...)

See UsdLuxLightAPI::CreateColorTemperatureAttr() .

CreateDiffuseAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateDiffuseAttr() .

CreateEnableColorTemperatureAttr(...)

See UsdLuxLightAPI::CreateEnableColorTemperatureAttr() .

CreateExposureAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateExposureAttr() .

CreateFiltersRel()

See UsdLuxLightAPI::CreateFiltersRel() .

CreateIntensityAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateIntensityAttr() .

CreateNormalizeAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateNormalizeAttr() .

CreateSpecularAttr(defaultValue, writeSparsely)

See UsdLuxLightAPI::CreateSpecularAttr() .

Get

classmethod Get(stage, path) -> NonboundableLightBase

GetColorAttr()

See UsdLuxLightAPI::GetColorAttr() .

GetColorTemperatureAttr()

See UsdLuxLightAPI::GetColorTemperatureAttr() .

GetDiffuseAttr()

See UsdLuxLightAPI::GetDiffuseAttr() .

GetEnableColorTemperatureAttr()

See UsdLuxLightAPI::GetEnableColorTemperatureAttr() .

GetExposureAttr()

See UsdLuxLightAPI::GetExposureAttr() .

GetFiltersRel()

See UsdLuxLightAPI::GetFiltersRel() .

GetIntensityAttr()

See UsdLuxLightAPI::GetIntensityAttr() .

GetNormalizeAttr()

See UsdLuxLightAPI::GetNormalizeAttr() .

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetSpecularAttr()

See UsdLuxLightAPI::GetSpecularAttr() .

LightAPI()

Contructs and returns a UsdLuxLightAPI object for this light.
CreateColorAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateColorAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateColorTemperatureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateDiffuseAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateDiffuseAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateEnableColorTemperatureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateEnableColorTemperatureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateExposureAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateExposureAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateFiltersRel() → Relationship

See UsdLuxLightAPI::CreateFiltersRel() .

CreateIntensityAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateIntensityAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateNormalizeAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateNormalizeAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateSpecularAttr(
defaultValue,
writeSparsely,
) → Attribute

See UsdLuxLightAPI::CreateSpecularAttr() .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Get()

classmethod Get(stage, path) -> NonboundableLightBase

Return a UsdLuxNonboundableLightBase 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:

UsdLuxNonboundableLightBase(stage->GetPrimAtPath(path));
Parameters:
GetColorAttr() → Attribute

See UsdLuxLightAPI::GetColorAttr() .

GetColorTemperatureAttr() → Attribute

See UsdLuxLightAPI::GetColorTemperatureAttr() .

GetDiffuseAttr() → Attribute

See UsdLuxLightAPI::GetDiffuseAttr() .

GetEnableColorTemperatureAttr() → Attribute

See UsdLuxLightAPI::GetEnableColorTemperatureAttr() .

GetExposureAttr() → Attribute

See UsdLuxLightAPI::GetExposureAttr() .

GetFiltersRel() → Relationship

See UsdLuxLightAPI::GetFiltersRel() .

GetIntensityAttr() → Attribute

See UsdLuxLightAPI::GetIntensityAttr() .

GetNormalizeAttr() → Attribute

See UsdLuxLightAPI::GetNormalizeAttr() .

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetSpecularAttr() → Attribute

See UsdLuxLightAPI::GetSpecularAttr() .

LightAPI() → LightAPI

Contructs and returns a UsdLuxLightAPI object for this light.

class pxr.UsdLux.PluginLight

Light that provides properties that allow it to identify an external SdrShadingNode definition, through UsdShadeNodeDefAPI, that can be provided to render delegates without the need to provide a schema definition for the light’s type.

Plugin Lights and Light Filters

Methods:

Define

classmethod Define(stage, path) -> PluginLight

Get

classmethod Get(stage, path) -> PluginLight

GetNodeDefAPI()

Convenience method for accessing the UsdShadeNodeDefAPI functionality for this prim.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
static Define()

classmethod Define(stage, path) -> PluginLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> PluginLight

Return a UsdLuxPluginLight 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:

UsdLuxPluginLight(stage->GetPrimAtPath(path));
Parameters:
GetNodeDefAPI() → NodeDefAPI

Convenience method for accessing the UsdShadeNodeDefAPI functionality for this prim.

One can also construct a UsdShadeNodeDefAPI directly from a UsdPrim.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.PluginLightFilter

Light filter that provides properties that allow it to identify an external SdrShadingNode definition, through UsdShadeNodeDefAPI, that can be provided to render delegates without the need to provide a schema definition for the light filter’s type.

Plugin Lights and Light Filters

Methods:

Define

classmethod Define(stage, path) -> PluginLightFilter

Get

classmethod Get(stage, path) -> PluginLightFilter

GetNodeDefAPI()

Convenience method for accessing the UsdShadeNodeDefAPI functionality for this prim.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
static Define()

classmethod Define(stage, path) -> PluginLightFilter

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> PluginLightFilter

Return a UsdLuxPluginLightFilter 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:

UsdLuxPluginLightFilter(stage->GetPrimAtPath(path));
Parameters:
GetNodeDefAPI() → NodeDefAPI

Convenience method for accessing the UsdShadeNodeDefAPI functionality for this prim.

One can also construct a UsdShadeNodeDefAPI directly from a UsdPrim.

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.PortalLight

A rectangular portal in the local XY plane that guides sampling of a dome light. Transmits light in the -Z direction. The rectangle is 1 unit in length.

Methods:

Define

classmethod Define(stage, path) -> PortalLight

Get

classmethod Get(stage, path) -> PortalLight

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
static Define()

classmethod Define(stage, path) -> PortalLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> PortalLight

Return a UsdLuxPortalLight 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:

UsdLuxPortalLight(stage->GetPrimAtPath(path));
Parameters:
static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

class pxr.UsdLux.RectLight

Light emitted from one side of a rectangle. The rectangle is centered in the XY plane and emits light along the -Z axis. The rectangle is 1 unit in length in the X and Y axis. In the default position, a texture file’s min coordinates should be at (+X, +Y) and max coordinates at (-X, -Y).

Methods:

CreateHeightAttr(defaultValue, writeSparsely)

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

CreateTextureFileAttr(defaultValue, ...)

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

CreateWidthAttr(defaultValue, writeSparsely)

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

Define

classmethod Define(stage, path) -> RectLight

Get

classmethod Get(stage, path) -> RectLight

GetHeightAttr()

Height of the rectangle, in the local Y axis.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetTextureFileAttr()

A color texture to use on the rectangle.

GetWidthAttr()

Width of the rectangle, in the local X axis.
CreateHeightAttr(defaultValue, writeSparsely) → Attribute

See GetHeightAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateTextureFileAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetTextureFileAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateWidthAttr(defaultValue, writeSparsely) → Attribute

See GetWidthAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> RectLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> RectLight

Return a UsdLuxRectLight 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:

UsdLuxRectLight(stage->GetPrimAtPath(path));
Parameters:
GetHeightAttr() → Attribute

Height of the rectangle, in the local Y axis.

Declaration

float inputs:height = 1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetTextureFileAttr() → Attribute

A color texture to use on the rectangle.

Declaration

asset inputs:texture:file

C++ Type

SdfAssetPath

Usd Type

SdfValueTypeNames->Asset

GetWidthAttr() → Attribute

Width of the rectangle, in the local X axis.

Declaration

float inputs:width = 1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

class pxr.UsdLux.ShadowAPI

Controls to refine a light’s shadow behavior. These are non-physical controls that are valuable for visual lighting work.

Methods:

Apply

classmethod Apply(prim) -> ShadowAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

ConnectableAPI()

Contructs and returns a UsdShadeConnectableAPI object with this shadow API prim.

CreateInput(name, typeName)

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

CreateOutput(name, typeName)

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

CreateShadowColorAttr(defaultValue, ...)

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

CreateShadowDistanceAttr(defaultValue, ...)

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

CreateShadowEnableAttr(defaultValue, ...)

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

CreateShadowFalloffAttr(defaultValue, ...)

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

CreateShadowFalloffGammaAttr(defaultValue, ...)

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

Get

classmethod Get(stage, path) -> ShadowAPI

GetInput(name)

Return the requested input if it exists.

GetInputs(onlyAuthored)

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

GetOutput(name)

Return the requested output if it exists.

GetOutputs(onlyAuthored)

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

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetShadowColorAttr()

The color of shadows cast by the light.

GetShadowDistanceAttr()

The maximum distance shadows are cast.

GetShadowEnableAttr()

Enables shadows to be cast by this light.

GetShadowFalloffAttr()

The near distance at which shadow falloff begins.

GetShadowFalloffGammaAttr()

A gamma (i.e., exponential) control over shadow strength with linear distance within the falloff zone.
static Apply()

classmethod Apply(prim) -> ShadowAPI

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

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

A valid UsdLuxShadowAPI object is returned upon success. An invalid (or empty) UsdLuxShadowAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

ConnectableAPI() → ConnectableAPI

Contructs and returns a UsdShadeConnectableAPI object with this shadow API prim.

Note that a valid UsdLuxShadowAPI will only return a valid UsdShadeConnectableAPI if the its prim’s Typed schema type is actually connectable.

CreateInput(name, typeName) → Input

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 shadow API are connectable.

Parameters:
CreateOutput(name, typeName) → Output

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 shadow API cannot be connected, as their value is assumed to be computed externally.

Parameters:
CreateShadowColorAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShadowColorAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShadowDistanceAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShadowDistanceAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShadowEnableAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShadowEnableAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShadowFalloffAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShadowFalloffAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShadowFalloffGammaAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShadowFalloffGammaAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Get()

classmethod Get(stage, path) -> ShadowAPI

Return a UsdLuxShadowAPI 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:

UsdLuxShadowAPI(stage->GetPrimAtPath(path));
Parameters:
GetInput(name) → Input

Return the requested input if it exists.

Parameters:

name (str)

GetInputs(onlyAuthored) → list[Input]

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.

Parameters:

onlyAuthored (bool)

GetOutput(name) → Output

Return the requested output if it exists.

Parameters:

name (str)

GetOutputs(onlyAuthored) → list[Output]

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.

Parameters:

onlyAuthored (bool)

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetShadowColorAttr() → Attribute

The color of shadows cast by the light.

This is a non-physical control. The default is to cast black shadows.

Declaration

color3f inputs:shadow:color = (0, 0, 0)

C++ Type

GfVec3f

Usd Type

SdfValueTypeNames->Color3f

GetShadowDistanceAttr() → Attribute

The maximum distance shadows are cast.

The default value (-1) indicates no limit.

Declaration

float inputs:shadow:distance = -1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShadowEnableAttr() → Attribute

Enables shadows to be cast by this light.

Declaration

bool inputs:shadow:enable = 1

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

GetShadowFalloffAttr() → Attribute

The near distance at which shadow falloff begins.

The default value (-1) indicates no falloff.

Declaration

float inputs:shadow:falloff = -1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShadowFalloffGammaAttr() → Attribute

A gamma (i.e., exponential) control over shadow strength with linear distance within the falloff zone.

This requires the use of shadowDistance and shadowFalloff.

Declaration

float inputs:shadow:falloffGamma = 1

C++ Type

float

Usd Type

SdfValueTypeNames->Float

class pxr.UsdLux.ShapingAPI

Controls for shaping a light’s emission.

Methods:

Apply

classmethod Apply(prim) -> ShapingAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

ConnectableAPI()

Contructs and returns a UsdShadeConnectableAPI object with this shaping API prim.

CreateInput(name, typeName)

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

CreateOutput(name, typeName)

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

CreateShapingConeAngleAttr(defaultValue, ...)

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

CreateShapingConeSoftnessAttr(defaultValue, ...)

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

CreateShapingFocusAttr(defaultValue, ...)

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

CreateShapingFocusTintAttr(defaultValue, ...)

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

CreateShapingIesAngleScaleAttr(defaultValue, ...)

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

CreateShapingIesFileAttr(defaultValue, ...)

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

CreateShapingIesNormalizeAttr(defaultValue, ...)

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

Get

classmethod Get(stage, path) -> ShapingAPI

GetInput(name)

Return the requested input if it exists.

GetInputs(onlyAuthored)

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

GetOutput(name)

Return the requested output if it exists.

GetOutputs(onlyAuthored)

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

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetShapingConeAngleAttr()

Angular limit off the primary axis to restrict the light spread.

GetShapingConeSoftnessAttr()

Controls the cutoff softness for cone angle.

GetShapingFocusAttr()

A control to shape the spread of light.

GetShapingFocusTintAttr()

Off-axis color tint.

GetShapingIesAngleScaleAttr()

Rescales the angular distribution of the IES profile.

GetShapingIesFileAttr()

An IES (Illumination Engineering Society) light profile describing the angular distribution of light.

GetShapingIesNormalizeAttr()

Normalizes the IES profile so that it affects the shaping of the light while preserving the overall energy output.
static Apply()

classmethod Apply(prim) -> ShapingAPI

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

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

A valid UsdLuxShapingAPI object is returned upon success. An invalid (or empty) UsdLuxShapingAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

ConnectableAPI() → ConnectableAPI

Contructs and returns a UsdShadeConnectableAPI object with this shaping API prim.

Note that a valid UsdLuxShapingAPI will only return a valid UsdShadeConnectableAPI if the its prim’s Typed schema type is actually connectable.

CreateInput(name, typeName) → Input

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 shaping API are connectable.

Parameters:
CreateOutput(name, typeName) → Output

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 shaping API cannot be connected, as their value is assumed to be computed externally.

Parameters:
CreateShapingConeAngleAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingConeAngleAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingConeSoftnessAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingConeSoftnessAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingFocusAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingFocusAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingFocusTintAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingFocusTintAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingIesAngleScaleAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingIesAngleScaleAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingIesFileAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingIesFileAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateShapingIesNormalizeAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetShapingIesNormalizeAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Get()

classmethod Get(stage, path) -> ShapingAPI

Return a UsdLuxShapingAPI 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:

UsdLuxShapingAPI(stage->GetPrimAtPath(path));
Parameters:
GetInput(name) → Input

Return the requested input if it exists.

Parameters:

name (str)

GetInputs(onlyAuthored) → list[Input]

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.

Parameters:

onlyAuthored (bool)

GetOutput(name) → Output

Return the requested output if it exists.

Parameters:

name (str)

GetOutputs(onlyAuthored) → list[Output]

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.

Parameters:

onlyAuthored (bool)

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetShapingConeAngleAttr() → Attribute

Angular limit off the primary axis to restrict the light spread.

Declaration

float inputs:shaping:cone:angle = 90

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShapingConeSoftnessAttr() → Attribute

Controls the cutoff softness for cone angle.

TODO: clarify semantics

Declaration

float inputs:shaping:cone:softness = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShapingFocusAttr() → Attribute

A control to shape the spread of light.

Higher focus values pull light towards the center and narrow the spread. Implemented as an off-axis cosine power exponent. TODO: clarify semantics

Declaration

float inputs:shaping:focus = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShapingFocusTintAttr() → Attribute

Off-axis color tint.

This tints the emission in the falloff region. The default tint is black. TODO: clarify semantics

Declaration

color3f inputs:shaping:focusTint = (0, 0, 0)

C++ Type

GfVec3f

Usd Type

SdfValueTypeNames->Color3f

GetShapingIesAngleScaleAttr() → Attribute

Rescales the angular distribution of the IES profile.

TODO: clarify semantics

Declaration

float inputs:shaping:ies:angleScale = 0

C++ Type

float

Usd Type

SdfValueTypeNames->Float

GetShapingIesFileAttr() → Attribute

An IES (Illumination Engineering Society) light profile describing the angular distribution of light.

Declaration

asset inputs:shaping:ies:file

C++ Type

SdfAssetPath

Usd Type

SdfValueTypeNames->Asset

GetShapingIesNormalizeAttr() → Attribute

Normalizes the IES profile so that it affects the shaping of the light while preserving the overall energy output.

Declaration

bool inputs:shaping:ies:normalize = 0

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

class pxr.UsdLux.SphereLight

Light emitted outward from a sphere.

Methods:

CreateRadiusAttr(defaultValue, writeSparsely)

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

CreateTreatAsPointAttr(defaultValue, ...)

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

Define

classmethod Define(stage, path) -> SphereLight

Get

classmethod Get(stage, path) -> SphereLight

GetRadiusAttr()

Radius of the sphere.

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

GetTreatAsPointAttr()

A hint that this light can be treated as a'point'light (effectively, a zero-radius sphere) by renderers that benefit from non-area lighting.
CreateRadiusAttr(defaultValue, writeSparsely) → Attribute

See GetRadiusAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

CreateTreatAsPointAttr(
defaultValue,
writeSparsely,
) → Attribute

See GetTreatAsPointAttr() , 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 .

Parameters:

  • defaultValue (VtValue)

  • writeSparsely (bool)

static Define()

classmethod Define(stage, path) -> SphereLight

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:
static Get()

classmethod Get(stage, path) -> SphereLight

Return a UsdLuxSphereLight 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:

UsdLuxSphereLight(stage->GetPrimAtPath(path));
Parameters:
GetRadiusAttr() → Attribute

Radius of the sphere.

Declaration

float inputs:radius = 0.5

C++ Type

float

Usd Type

SdfValueTypeNames->Float

static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)

GetTreatAsPointAttr() → Attribute

A hint that this light can be treated as a’point’light (effectively, a zero-radius sphere) by renderers that benefit from non-area lighting.

Renderers that only support area lights can disregard this.

Declaration

bool treatAsPoint = 0

C++ Type

bool

Usd Type

SdfValueTypeNames->Bool

class pxr.UsdLux.Tokens

Attributes:

angular

automatic

collectionFilterLinkIncludeRoot

collectionLightLinkIncludeRoot

collectionShadowLinkIncludeRoot

consumeAndContinue

consumeAndHalt

cubeMapVerticalCross

cylinderLight

diskLight

distantLight

domeLight

extent

filterLink

geometry

geometryLight

guideRadius

ignore

independent

inputsAngle

inputsColor

inputsColorTemperature

inputsDiffuse

inputsEnableColorTemperature

inputsExposure

inputsHeight

inputsIntensity

inputsLength

inputsNormalize

inputsRadius

inputsShadowColor

inputsShadowDistance

inputsShadowEnable

inputsShadowFalloff

inputsShadowFalloffGamma

inputsShapingConeAngle

inputsShapingConeSoftness

inputsShapingFocus

inputsShapingFocusTint

inputsShapingIesAngleScale

inputsShapingIesFile

inputsShapingIesNormalize

inputsSpecular

inputsTextureFile

inputsTextureFormat

inputsWidth

latlong

lightFilterShaderId

lightFilters

lightLink

lightList

lightListCacheBehavior

lightMaterialSyncMode

lightShaderId

materialGlowTintsLight

meshLight

mirroredBall

noMaterialResponse

orientToStageUpAxis

portalLight

portals

rectLight

shadowLink

sphereLight

treatAsLine

treatAsPoint

volumeLight

angular = 'angular'
automatic = 'automatic'
collectionFilterLinkIncludeRoot = 'collection:filterLink:includeRoot'
collectionLightLinkIncludeRoot = 'collection:lightLink:includeRoot'
collectionShadowLinkIncludeRoot = 'collection:shadowLink:includeRoot'
consumeAndContinue = 'consumeAndContinue'
consumeAndHalt = 'consumeAndHalt'
cubeMapVerticalCross = 'cubeMapVerticalCross'
cylinderLight = 'CylinderLight'
diskLight = 'DiskLight'
distantLight = 'DistantLight'
domeLight = 'DomeLight'
extent = 'extent'
filterLink = 'filterLink'
geometry = 'geometry'
geometryLight = 'GeometryLight'
guideRadius = 'guideRadius'
ignore = 'ignore'
independent = 'independent'
inputsAngle = 'inputs:angle'
inputsColor = 'inputs:color'
inputsColorTemperature = 'inputs:colorTemperature'
inputsDiffuse = 'inputs:diffuse'
inputsEnableColorTemperature = 'inputs:enableColorTemperature'
inputsExposure = 'inputs:exposure'
inputsHeight = 'inputs:height'
inputsIntensity = 'inputs:intensity'
inputsLength = 'inputs:length'
inputsNormalize = 'inputs:normalize'
inputsRadius = 'inputs:radius'
inputsShadowColor = 'inputs:shadow:color'
inputsShadowDistance = 'inputs:shadow:distance'
inputsShadowEnable = 'inputs:shadow:enable'
inputsShadowFalloff = 'inputs:shadow:falloff'
inputsShadowFalloffGamma = 'inputs:shadow:falloffGamma'
inputsShapingConeAngle = 'inputs:shaping:cone:angle'
inputsShapingConeSoftness = 'inputs:shaping:cone:softness'
inputsShapingFocus = 'inputs:shaping:focus'
inputsShapingFocusTint = 'inputs:shaping:focusTint'
inputsShapingIesAngleScale = 'inputs:shaping:ies:angleScale'
inputsShapingIesFile = 'inputs:shaping:ies:file'
inputsShapingIesNormalize = 'inputs:shaping:ies:normalize'
inputsSpecular = 'inputs:specular'
inputsTextureFile = 'inputs:texture:file'
inputsTextureFormat = 'inputs:texture:format'
inputsWidth = 'inputs:width'
latlong = 'latlong'
lightFilterShaderId = 'lightFilter:shaderId'
lightFilters = 'light:filters'
lightLink = 'lightLink'
lightList = 'lightList'
lightListCacheBehavior = 'lightList:cacheBehavior'
lightMaterialSyncMode = 'light:materialSyncMode'
lightShaderId = 'light:shaderId'
materialGlowTintsLight = 'materialGlowTintsLight'
meshLight = 'MeshLight'
mirroredBall = 'mirroredBall'
noMaterialResponse = 'noMaterialResponse'
orientToStageUpAxis = 'orientToStageUpAxis'
portalLight = 'PortalLight'
portals = 'portals'
rectLight = 'RectLight'
shadowLink = 'shadowLink'
sphereLight = 'SphereLight'
treatAsLine = 'treatAsLine'
treatAsPoint = 'treatAsPoint'
volumeLight = 'VolumeLight'
class pxr.UsdLux.VolumeLightAPI

This is the preferred API schema to apply to Volume type prims when adding light behaviors to a volume. At its base, this API schema has the built-in behavior of applying LightAPI to the volume and overriding the default materialSyncMode to allow the emission/glow of the bound material to affect the color of the light. But, it additionally serves as a hook for plugins to attach additional properties to”volume lights”through the creation of API schemas which are authored to auto-apply to VolumeLightAPI.

Auto applied API schemas

Methods:

Apply

classmethod Apply(prim) -> VolumeLightAPI

CanApply

classmethod CanApply(prim, whyNot) -> bool

Get

classmethod Get(stage, path) -> VolumeLightAPI

GetSchemaAttributeNames

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
static Apply()

classmethod Apply(prim) -> VolumeLightAPI

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

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

A valid UsdLuxVolumeLightAPI object is returned upon success. An invalid (or empty) UsdLuxVolumeLightAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)

static CanApply()

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

  • prim (Prim)

  • whyNot (str)

static Get()

classmethod Get(stage, path) -> VolumeLightAPI

Return a UsdLuxVolumeLightAPI 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:

UsdLuxVolumeLightAPI(stage->GetPrimAtPath(path));
Parameters:
static GetSchemaAttributeNames()

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:

includeInherited (bool)