Light Prims#

Utility functions to define, manipulate, and read UsdLux Light Prims.

Defining UsdLux Lights#

When creating some USD light types it’s sometimes ambiguous as to what attributes should be set. These light definition helper functions provide an argument set that make these optional arguments clear.

Accessing UsdLux Light Attributes#

In USD 21.02 many UsdLux Light attributes changed. Input attributes for UsdLuxLight and UsdLuxLightFilter schemas are now connectable and have been renamed to include the inputs: prefix.

The getLightAttr() function provides the “correct” light attribute depending on which attributes are authored, favoring the newer inputs: attributes. This is to help with existing USD files containing lights that were authored with older light schema that didn’t include inputs: attributes.

UsdLux Light CHANGELOG note for 21.02

Functions#

pxr::UsdLuxDomeLight usdex::core::defineDomeLight(pxr::UsdPrim parent, const std::string &name, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt, const pxr::TfToken &textureFormat=pxr::UsdLuxTokens->automatic)

Creates a dome light with an optional texture.

pxr::UsdLuxDomeLight usdex::core::defineDomeLight(pxr::UsdStagePtr stage, const pxr::SdfPath &path, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt, const pxr::TfToken &textureFormat=pxr::UsdLuxTokens->automatic)

Creates a dome light with an optional texture.

pxr::UsdLuxRectLight usdex::core::defineRectLight(pxr::UsdStagePtr stage, const pxr::SdfPath &path, float width, float height, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt)

Creates a rectangular (rect) light with an optional texture.

pxr::UsdLuxRectLight usdex::core::defineRectLight(pxr::UsdPrim parent, const std::string &name, float width, float height, float intensity=1.0f, std::optional< std::string_view > texturePath=std::nullopt)

Creates a rectangular (rect) light with an optional texture.

pxr::UsdAttribute usdex::core::getLightAttr(const pxr::UsdAttribute &defaultAttr)

Get the "correct" light attribute for a light that could have any combination of authored old and new UsdLux schema attributes.

bool usdex::core::isLight(const pxr::UsdPrim &prim)

Determines if a UsdPrim has a UsdLuxLightAPI schema applied.

Functions#

pxr::UsdLuxDomeLight usdex::core::defineDomeLight(
pxr::UsdPrim parent,
const std::string &name,
float intensity = 1.0f,
std::optional<std::string_view> texturePath = std::nullopt,
const pxr::TfToken &textureFormat = pxr::UsdLuxTokens->automatic,
)#

Creates a dome light with an optional texture.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the light

  • name – Name of the light

  • intensity – The intensity value of the dome light

  • texturePath – The path to the texture file to use on the dome light.

  • textureFormat – How the texture should be mapped on the dome light.

Returns:

The light if created successfully.

pxr::UsdLuxDomeLight usdex::core::defineDomeLight(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
float intensity = 1.0f,
std::optional<std::string_view> texturePath = std::nullopt,
const pxr::TfToken &textureFormat = pxr::UsdLuxTokens->automatic,
)#

Creates a dome light with an optional texture.

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

Texture Format values:

  • automatic - Tries to determine the layout from the file itself.

  • 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, for better sampling at the edges.

  • cubeMapVerticalCross - Set to “automatic” by default.

Note

The DomeLight schema requires the dome’s top pole to be aligned with the world’s +Y axis. In USD 23.11 a new UsdLuxDomeLight_1 schema was added which gives control over the pole axis. However, it is not widely supported yet, so we still prefer to author the original DomeLight schema and expect consuming application and renderers to account for the +Y pole axis.

Parameters:

  • stage – The stage in which the dome light should be authored

  • path – The path which the dome light prim should be written to

  • intensity – The intensity value of the dome light

  • texturePath – The path to the texture file to use on the dome light.

  • textureFormat – How the texture should be mapped on the dome light.

Returns:

The light if created successfully.

pxr::UsdLuxRectLight usdex::core::defineRectLight(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
float width,
float height,
float intensity = 1.0f,
std::optional<std::string_view> texturePath = std::nullopt,
)#

Creates a rectangular (rect) light with an optional texture.

A rect light represents light emitted from one side of a rectangle.

Parameters:

  • stage – The stage in which the rectangular light should be authored

  • path – The path which the rectangular light prim should be written to

  • width – The width of the rectangular light, in the local X axis.

  • height – The height of the rectangular light, in the local Y axis.

  • intensity – The intensity value of the rectangular light.

  • texturePath – The path to the texture file to use on the rectangular light.

Returns:

The light if created successfully.

pxr::UsdLuxRectLight usdex::core::defineRectLight(
pxr::UsdPrim parent,
const std::string &name,
float width,
float height,
float intensity = 1.0f,
std::optional<std::string_view> texturePath = std::nullopt,
)#

Creates a rectangular (rect) light with an optional texture.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the light

  • name – Name of the light

  • width – The width of the rectangular light, in the local X axis.

  • height – The height of the rectangular light, in the local Y axis.

  • intensity – The intensity value of the rectangular light.

  • texturePath – The path to the texture file to use on the rectangular light.

Returns:

The light if created successfully.

pxr::UsdAttribute usdex::core::getLightAttr(
const pxr::UsdAttribute &defaultAttr,
)#

Get the “correct” light attribute for a light that could have any combination of authored old and new UsdLux schema attributes.

The new attribute names have “inputs:” prepended to the names to make them connectable.

  • Light has only “intensity” authored - return “intensity” attribute

  • Light has only “inputs:intensity” authored - return “inputs:intensity” attribute

  • Light has both “inputs:intensity” and “intensity” authored - return “inputs:intensity”

See Light Prims for more details.

Parameters:

defaultAttr – The attribute to read from the light schema: eg. UsdLuxRectLight::GetHeightAttr()

Returns:

The attribute from which the light value should be read

bool usdex::core::isLight(const pxr::UsdPrim &prim)#

Determines if a UsdPrim has a UsdLuxLightAPI schema applied.

Parameters:

prim – The prim to check for an applied UsdLuxLightAPI schema

Returns:

True if the prim has a UsdLuxLightAPI schema applied

On this page