All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdLux : USD Lighting Schema


UsdLux provides a representation for lights and related components that are common to many graphics environments and therefore suitable for interchange.

The goal of UsdLux is to serve as a basis for:

  • passing lighting setups from a creation environment to a renderer
  • best-effort portability of setups across environments, to the degree that they share capabilities

The UsdLux core includes:

This core can be extended to add more types of lights, filters, or other features.

For a comprehensive list of the types see the full class hierarchy.

Design Notes and Usage Guide


By convention, lights with a primary axis emit along -Z. Area lights are centered in the XY plane and are 1 unit in diameter.

UsdLux objects are UsdGeomXformable, so they use its set of transform operators, and inherit transforms hierarchically. It is recommended that only translation and rotations be used with lights, to avoid introducing difficulties for light sampling and integration. Lights have explicit attributes to adjust their size.

UsdLux includes both a light that uses arbitrary user-supplied geometry, as well as lights for specific shapes: spheres, rectangles, disks, and cylinders. The specific shapes exist because they can support superior, analytic sampling methods.

UsdLux is designed primarily for physically-based cinematic lighting with area lights. Accordingly, it does not include zero-area point or line lights. However, some backends benefit from a point or line approximation. This intent can be indicated using the treatAsPoint and treatAsLine attributes on UsdSphereLight and UsdCylinderLight. These attributes are hints that avoid the need for backends to use heuristics (such as an arbitrary epsilon threshold) to determine the approximation. These hints can be set at the time of creation (or export) where the most information about the visual intent exists.

To support efficient sampling, these specialized types place restrictions on their local-to-world transform. For example, a sphere may only be scaled uniformly. Because arbitrary transforms may be inherited from parent prims, it is necessary to explicitly compute the "effective" transform for such lights using UsdLuxLight::ComputeEffectiveTransform().

To clarify geometric semantics and aid pipeline integration, UsdLux includes code to compute guide geometry for interactive viewport visualization. This code is used in usdview.

UsdLux does not provide support for expressing live transform constraints, such as to attach lights to moving geometry. This is consistent with USD's policy of storing the computed result of rigging, not the rigging itself.

Properties & Behavior

Colors specified in attributes are in energy-linear terms, and obey the USD convention for indicating their color space via colorConfiguration and colorSpace metadata. See UsdStage::SetColorConfiguration() for discussion of colorspace management in USD.

UsdLux presumes a physically-based lighting model where falloff with distance is a consequence of reduced visible solid angle. Environments that do not measure the visible solid angle are expected to provide an approximation, such as inverse-square falloff. Further artistic control over attenuation can be modelled as light filters.

More complex behaviors are provided via a set of API classes. These behaviors are common and well-defined but may not be supported in all rendering environments. These API classes provide functions to specify the relevant semantic behavior:

  • UsdLuxListAPI provides a "light list" relationship to enumerate locations of known lights in the scene. It can be useful to enumerate lights without requiring full scene traversal. For example, some systems require lights to be declared before the rest of the scene. UsdLuxListAPI provides a way to compute this result ahead of time and store the result in a well-defined place. Pipeline integration of UsdLux can use this API to discover and publish lights at an appropriate time – such as export from any system where lights may be created.
  • UsdCollectionAPI provides relationships to represent subsets of geometry to consider for illumination. These provide hierarchical inclusion and exclusion – for example, to illuminate a building but not a window within. UsdLux supports a concept of fractional illumination, allowing partial contribution from a light to a particular object, for rendering systems that support this.
  • UsdLuxShadowAPI provides controls to refine shadow behavior in non-physical ways, including shadow linking, tinting, and falloff.
  • UsdLuxShapingAPI provides controls to shape light emission, including focus, cone-angle falloff, and IES profiles.


Like other USD schemas, UsdLux core may be extended to address features specific to certain environments. Possible renderer- or pipeline-specific capabilities that could be addded as extensions include:

  • specialized light types
    • point cloud lights
    • volumetric/voxel lights
    • procedural sky models
    • light probes, lightfields
  • renderer-specific configuration
    • arbitrary output variable images (AOV's) such as depth or normals
    • light path expressions (LPE's)
    • image post-processing effects
    • refraction and opacity approximations, such as thin shadows
  • sampling and optimization tweaks
    • light sample counts
    • importance multipliers
    • integrator path-depth limits
  • constraint rigging to attach a light to an object

Plugin Lights and Light Filters

We expect "published, pipeline citizen" render delegates to provide typed and applied codeless schemas that derive from the UsdLux base types (even if only UsdLuxLight) for all of the renderer's core light types. But some render delegates may be developed as part of a proprietary application package that is only using USD as a mechanism to communicate to that render delegate... in other words, the application doesn't really want to participate in the open USD ecosystem, but needs to use it for rendering scenes imported from USD and augmented using application/renderer-specific lighting features, or finds it useful to use USD as an archiving format to send jobs to a render-farm so that the full application need not be run there.

In order to lower the barrier somewhat for such applications, we provide UsdLuxPluginLight and UsdLuxPluginLightFilter, concrete schema types that specify a "node identification" encoding, just like UsdShadeShader, so that the application need only plug its extensions into Sdr (by providing node definitions that will be consumed by render delegates), and not be required to take the extra step of generating USD schema definitions. Because they provide less easily accessible information to users, we do not advocate using these types in pipeline-persistent "user-level" USD files.