LightLink

The LightLink node manipulates the lightList attribute on the scene to perform selective lighting of objects. LightLink allows you to control which lights illuminate which objects, using a number of different modes.

Note:  The GafferThree node uses a LightLink internally to provide light linking. The user interface there is substantially similar to the LightLink node.

Note:  Light linking information is stored on the objects themselves in the lightList attribute. This stores the enable state of a light for each location in the scene. Visibility does not have any effect on lights, so a VisibilityAssign does not disable a light. LightLink is the best way to turn a light on or off by hand.

Connection Type

Connection Name

Function

Input

in

The light whose attributes you want to manipulate.

 

Control (UI)

Default Value

Function

effect

illumination

Determines whether the link is acting upon the light's illumination or shadow visibility of the specified objects:

illumination

shadowvisibility

Custom

Note:  Shadow visibility is only currently respected by Arnold renders.

action

off

Controls the LightLink node's behavior:

on - turn the selected lights on for the selected objects. Does nothing else.

exclusive on - turn the selected lights on for the selected objects. Also turn the selected lights off for all other objects. Use this to force the selected lights to only illuminate the selected objects, and nothing else.

off - turn the selected lights off for the selected objects. Does nothing else.

exclusive off - turn the selected lights off for the selected objects. Also turn the selected lights on for all other objects. Use this to force the selected lights to not illuminate the selected objects, but to illuminate everything else.

clear - remove any local setting for light enable/disable for the selected objects; the inherited settings are used on these objects.

delete - the selected lights are removed from the light list for all objects in the scene. This is more than simply turning the lights off; they're removed from the list, and a LightListEdit is required to turn them on again.

delete inverse - the selected lights are the only lights left in the light list for all objects in the scene.

effect: custom

customAttrName

custom

Specifies a custom attribute name to set on the lightList for your object scene graph locations. The value of the custom parameter becomes the attribute name, which is set on the object scene graph location for each light.

When a LightLink node is used with a LightLinkEdit node, for instance, if the:

light parameter is set to /root/world/lgt/spotlight,

custom parameter is set to myAttr,

off CEL parameter is set to /root/world/geo/pony,

Then

/root/world/geo/pony has an attribute named lightList.root_world_lgt_spotlight.myAttr, whose value is set to 0.

objects

N/A

Sets the object(s) on which to operate. The scene graph locations are specified for the objects parameter options by clicking Add Statements.

For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation) or the CEL Statement Widget Type in Common Parameter Widgets.

lightMode

CEL

Controls how you specify which lights to operate on:

CEL

Paths

Paths are included for backward compatibility.

lightMode: CEL

lights

N/A

When lightMode is set to CEL, this CEL statement is used to select the lights to operate on.

The scene graph locations are specified using the Collection Expression Language (CEL). The lights parameter options are available by clicking Add Statements.

For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation) or the CEL Statement Widget Type in Common Parameter Widgets.

lightMode: Paths

lightPaths

N/A

When lightMode is set to Paths, this list of light path names is used as the set of lights to operate on. The lightPaths parameter options are available by clicking Add Locations or dropdown menu.

For more information, refer to the Scene Graph Location and Locations Widget Types in Common Parameter Widgets.