Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# GafferThree

The GafferThree node type allows you to create lights under an arbitrary hierarchy of rigs. Materials, transformations, and constraints can be applied to lights from within the GafferThree's Parameters interface. This node also supports:

• Creating and applying Template Materials to lights.

• Muting and soloing lights, or all lights under a rig.

• Linking lights to specific objects.

• Editing lights from the incoming scene, and editing multiple lights at once.

• Adding aim constraints to lights.

Connection Type | Connection Name | Function
Input | in | The place in the node graph where you want to create a GafferThree for creating several lights together.

Control (UI) | Function
> Select In Scenegraph | Sets the scene graph path to the location to be created. For more information, see Common Parameter Widgets.
> Show Incoming Scene | Displays all incoming lights, rigs, and Template Materials from upstream Gaffer-type nodes.
sync selection | When enabled, selecting a Gaffer light within the Parameters tab selects its location within the Scene Graph tab: • off - no syncing is performed (the default). • out - selection of a light in the GafferThree node is mirrored in the Scene Graph tab, but not the other way around. • in/out - selecting in either the Scene Graph tab or GafferThree node results in the corresponding entry in the other also being selected.
[Gaffer object table] | Displays a list of all objects controlled by this GafferThree node. The object table contains the following information: • Name - the name of the object. Double-click in this column to change the name of the item. • M - click to mute the object so that it is omitted from renders. • S - click to solo the object so that everything not solo-ed is omitted from interactive renders. • Shader - displays the shader associated with the object. You can also right-click in this column to select a shader. Once you've added a shader, double-click in this column to assign or change it at any time. • Color - specifies the color of a light. Double-click the swatch to activate the color picker. If there isn't a swatch, you need to add a color in the Material tab before you can change it in this column. • Int - sets the light intensity. • Exp - sets the light exposure. • Linking - indicates whether or not the item is linked. A star in the entry indicates there are exceptions.
Right-click the [Gaffer object table item]
Add > Template Material | Adds a Template Material to the gaffer table. The Template Material is assigned to lights, providing the same material for multiple lights. Each light is also capable of overriding the defaults set by this Template Material.
Add > Light | Adds a light to the object table.
Add > Rig | Adds a rig for multiple lights to the object table.
Add > Light Filter Reference | Adds a light filter that references another light filter package.
Add > Light Filter | Adds a light filter that modifies the behavior of a light, depending on the renderer you're using.
Add > Sky Dome | Adds a sky dome light, used to provide environment lighting to your scene.
Add > Import Rig... | Adds a previously exported rig to the object table.
Delete | Deletes the selected entity in the object table.
Duplicate | Creates a copy of the currently selected entity.
Adopt for Editing | Allow you to make edits on a light, rig, or Template Material that has been shown from an incoming scene, which can be any upstream Gaffer-type node.
Delete Edit Package | If you adopted a light, rig, or Template Material for editing, you can revert back to a read-only state and reverse the changes that you applied.
Toggle Lock State of Selected Items | Toggles the lock state of the selected entity in the object table.
Group Selected Siblings Under Rig | Groups the selected siblings under a newly created rig.
Export Rig | Exports the currently selected item as a .rig file.
Create Shared Light Filter | Creates a light filter on a light that references a light filter that already exists in another location in the scenegraph.
Expand All | Expands the selected branch in the object table to reveal all children. If the selected branch does not have any children, nothing happens when attempting to expand. Note: In the menu, Expand All becomes Expand Branch whenever there is more than one item in the Gaffer object table.
Expand All To | Expand the branch to a specific type, either assembly, component, or level-of-detail group. This method of expansion applies specifically to the scene graph, and has limited use for the GafferThree. Note: In the menu, Expand All To becomes Expand Branch To whenever there is more than one item in the Gaffer object table.
Collapse All To | Collapse the branch to a specific type, either assembly, component, or level-of-detail group. This method of collapse applies specifically to the scene graph, and has limited use for the GafferThree. Note: In the menu, Collapse All To becomes Collapse Branch To whenever there is more than one item in the Gaffer object table.
Collapse All | Collapses the selected branch in the object table to hide all children. If the selected branch does not have any children, nothing happens when attempting to collapse. Note: In the menu, Collapse All becomes Collapse Branch whenever there is more than one item in the Gaffer object table.
Expand Location | Expands the selected location to only the children and leaves directly below it in the hierarchy.
Collapse Location | Collapses the selected location and any children and leaves directly below it, but not any entities higher than the location in the hierarchy.

The display parameters for the Object, Material, and Linking tabs are dependent on what's selected in the Gaffer object table. Where a particular tab isn't listed for an object type, there are no parameters in that tab.

Control (UI) | Default Value | Function
--- | --- | ---
Object list: Template Material
Material tab
useLookFileMaterial | Disabled | When enabled, the material from an associated Look File is used.
Add Shader | N/A | Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.

Control (UI) | Default Value | Function
Object list: light
Object tab > geometry
projection | perspective | Sets the light projection mode: • perspective - a warped projection where distant objects/features appear smaller than those nearer the camera. • orthographic - a two-dimensional representation of a three-dimensional object.
radius | 1 | Sets the light's radius.
fov | 70 | Controls the field of view angle in degrees.
orthographicWidth | 30 | Sets the orthographic projection width.
centerOfInterest | 20 | Sets the center of interest.
near | 0.1 | Sets the near clipping plane distance.
far | 100000 | Sets the far clipping plane distance.
screenWindow | -1.0, 1.0, -1.0, 1.0 | Controls the screen window placement on the imaging plane. They are the left, right, bottom, and top bounds of the screen window.
Object tab > transform
transform | N/A | Transforms the light according to the SRT or matrix controls. For more information, refer to the Transform Controls Widget Type in the Common Parameter Widgets.
transform > Tools | N/A | Adjusts the light to match selected scene graph selection options in the dropdown menu. For more information, refer to the Transform Tools Widget Type in the Common Parameter Widgets.
enable aim constraint: enabled; aim constraint options
targetPath | N/A | Specifies the object(s) to constrain to. If you want to aim a light to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter. For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.
addToConstraintList | Yes | Specifies whether or not to add the base path for the light to the globals.constraintList at /root/world in the Attributes tab.
targetOrigin | Object | Sets how the center of the target object is calculated: • Object - uses the local origin of the object as the target. • Bounding Box - uses the center of the object’s bounding box as the target. • Face Center Average - uses the face center average of the object as the target. • Face Bounding Box - uses the face center average of the object’s bounding box as the target.
baseAimAxis | 0.0, 0.0, -1.0 | The axis of the base object that is pointed at the target. Adjusting these values changes the side of the object that is aimed at the target.
baseUpAxis | 0.0, 1.0, 0.0 | The axis of the base object that is pointed upwards relative to the target. Adjusting these values changes the rotation of the base object, while keeping the aim constant.
targetUpAxis | 0.0, 1.0, 0.0 | The axis of the target object that is pointed upwards relative to the base object. Adjusting these values changes the rotation of the target object, while maintaining the aim constant.
setRelativeTargets | No | Stores target paths in the scene graph constraint definition as paths relative to the base path. Targets should still be specified as absolute paths in this node's parameters.
Object tab > annotation
text | N/A | Places a label in the Viewer containing the string entered in the text field.
previewColor | 1.0, 1.0, 1.0 | Specifies the color of the light annotation in the Viewer. This value does not affect the color value of the light. For more information, refer to the Color Widget Type in the Common Parameter Widgets.
Material tab > material
useLookFileMaterial | Disabled | When enabled, the material from an associated Look File is used.
Add Shader | N/A | Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.
useLookFileMaterial: enabled
reference > asset | N/A | Set the path to the asset you want in your scene. For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.
reference > materialPath | N/A | Choose the material path from the dropdown list, based on the asset you have listed in the asset field above. If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.
Linking tab > light linking Support for light linking is dependent on your renderer.
action | append linking information | Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.
initialState | on (or use existing value for adopted lights) | Determines whether the newly-added light location is initially on, off, or use existing value. Note: The use existing value option is only available for adopted lights.
clearUnmatched | disabled | When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions. The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active. Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.
on | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.
off | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.
Linking tab > shadow linking Support for shadow linking is dependent on your renderer.
action | append linking information | Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.
initialState | don't set value (or use existing value for adopted lights) | Determines the initial value for shadow visibility in the lightList entry for the newly-added light: on, off, don't set value, or use existing value. Note: The use existing value option is only available for adopted lights.
clearUnmatched | disabled | When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions. The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active. Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.
on | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light on for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.
off | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light off for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.

Control (UI) | Default Value | Function
--- | --- | ---
Object list: rig
Object tab > transform
transform | N/A | Transforms the rig according to the SRT or matrix controls. For more information, refer to the Transform Controls Widget Type in the Common Parameter Widgets.
transform > Tools | N/A | Adjusts the rig to match selected scene graph selection options in the dropdown menu. For more information, refer to the Transform Tools Widget Type in the Common Parameter Widgets.
Object tab parameters continued
enable point constraint | disabled | When enabled, specifies the point constraint options.
enable orient constraint | disabled | When enabled, specifies the orient constraint options.
when enable point constraint: enabled; point constraint options
targetPath | N/A | Specifies the object(s) to constrain to. If you want to aim a rig to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter. For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.
addToConstraintList | Yes | Specifies whether or not to add the base path for the rig to the globals.constraintList at /root/world in the Attributes tab.
allowMissingTargets | No | When set to Yes, silently ignore the constraint if its target is not in the scene graph. When set to No, produce an error on constraint resolution if the target is missing.
baseOrigin | Object | Sets how the center of the base object is calculated: • Object - uses the local origin of the object as the origin. • BoundingBox - uses the center of the object’s bounding box as the base origin.
targetOrigin | Object | Sets how the center of the target object is calculated: • Object - uses the local origin of the object as the target origin. • BoundingBox - uses the center of the object’s bounding box as the target origin. • FaceCenterAverage - uses the face center average of the object as the target origin. • FaceBoundingBox - uses the face center average of the object’s bounding box as the target origin.
setRelativeTargets | No | Stores target paths in the scene graph constraint definition as paths relative to the base path. Targets should still be specified as absolute paths in this node's parameters.
when enable orient constraint: enabled; orient constraint options
targetPath | N/A | Specifies the object(s) to constrain to. If you want to aim a rig to point at a target, this is the target. If you set multiple targets, then the constraint aims at the average center of the objects. The targetPath parameter options are available in either a scene graph widget or dropdown menu to the right of the parameter. For more information, refer to the Scene Graph Location Widget Type in the Common Parameter Widgets.
addToConstraintList | yes | Specifies whether or not to add the base path for the rig to the globals.constraintList at /root/world in the Attributes tab.
targetOrientation | Object | Sets how the orientation of the target object is calculated: • Object - uses the local origin of the object as the target. • Face - uses the local origin on the face as the target.
allowMissingTargets | No | When set to Yes, silently ignore the constraint if its target is not in the scene graph. When set to No, produce an error on constraint resolution if the target is missing.
xAxis | Enabled | When enabled, orientation is constrained on the x axis.
yAxis | Enabled | When enabled, orientation is constrained on the y axis.
zAxis | Enabled | When enabled, orientation is constrained on the z axis.
setRelativeTargets | No | Stores target paths in the scene graph constraint definition as paths relative to the base path. Targets should still be specified as absolute paths in this node's parameters.

Control (UI) | Default Value | Function
--- | --- | ---
Object list: light filter reference
Object tab
referencePath | N/A | The path to the light filter package that you want to reference as part of this light filter.

Control (UI) | Default Value | Function
--- | --- | ---
Object list: light filter
Object tab
inherits | N/A | The path to another light filter package that you want to inherit from.
Object tab > viewer
fill | solid | The manner in which the light filter is displayed in the viewer: as points, a wireframe, or a solid fill.
Object tab > transform
translate | 0.0, 0.0, 0.0 | Transforms the light filter by moving it on the x, y, or z axes. Modifying the light filter in the viewer using the Translate manipulators also updates these parameter values.
rotate | 0.0, 0.0, 0.0 | Transforms the light filter by rotating it around the x, y, or z axes. Modifying the light filter in the viewer using the Rotate manipulators also updates these parameter values.
scale | 1.0, 1.0, 1.0 | Transforms the light filter by scaling it along the x, y, or z axes. Modifying the light filter in the viewer using the Scale manipulators also updates these parameter values.
Material tab
useLookFileMaterial | disabled | When enabled, the material from an associated Look File is used.
Add Shader | N/A | Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.
useLookFileMaterial: enabled
reference > asset | N/A | Set the path to the asset you want in your scene. For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.
reference > materialPath | N/A | Choose the material path from the dropdown list, based on the asset you have listed in the asset field above. If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.
Linking tab > light linking
action | append linking information | Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.
initialState | don't set value | Determines whether the newly-added light location is initially on, off, or doesn't have a value set.
clearUnmatched | disabled | When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions. The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active. Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.
on | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.
off | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.

Control (UI) | Default Value | Function
--- | --- | ---
Object list: sky dome
Object tab > transform
translate | 0.0, 0.0, 0.0 | Transforms the sky dome light by moving it on the x, y, or z axes. Modifying the sky dome in the viewer using the Translate manipulators also updates these parameter values.
rotate | 0.0, 0.0, 0.0 | Transforms the sky dome light by rotating it around the x, y, or z axes. Modifying the sky dome in the viewer using the Rotate manipulators also updates these parameter values.
scale | 1000.0, 1000.0, 1000.0 | Transforms the sky dome light by scaling it along the x, y, or z axes. Modifying the sky dome in the viewer using the Scale manipulators also updates these parameter values.
Material tab > material
useLookFileMaterial | enabled | When enabled, the material from an associated Look File is used and the additional parameters are contained in the reference dropdown.
Add Shader | N/A | Click to add a renderer-specific shader from the dropdown list. The Material tab is populated with controls appropriate to the shader selected, and are dependent on the renderers installed.
useLookFileMaterial: enabled
reference > asset | /tmp/hdriSkyDomeLight.klf | Set the path to the look file you've written to disk. For more information, refer to the Asset and File Path Widget Types in the Common Parameter Widgets.
reference > materialPath | /root/materials/hdriSkyDomeLight | Choose the material path from the dropdown list, based on the asset you have listed in the asset field above. If you do not have an asset listed in the asset field, nothing appears in the dropdown list for materialPath.
Linking tab > light linking
action | append linking information | Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.
initialState | don't set value | Determines whether the newly-added light location is initially on, off, or doesn't have a value set.
clearUnmatched | disabled | When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions. The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active. Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.
on | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light on for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.
off | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning the light off for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using the CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to CEL Statement Widget Type in Common Parameter Widgets.
Linking tab > shadow linking Support for shadow linking is dependent on your renderer.
action | append linking information | Determines whether the linking options set in this node override the incoming scene options or if the new settings are appended to the incoming options. If this light doesn't exist in the incoming scene, this option has no effect.
initialState | don't set value (or use existing value for adopted lights) | Determines the initial value for shadow visibility in the lightList entry for the newly-added light: on, off, don't set value, or use existing value. Note: The use existing value option is only available for adopted lights.
clearUnmatched | disabled | When linking is resolved, the clearUnmatched parameter determines whether or not existing light linking attributes for this light are removed from locations that do not match the on or off expressions. The effect of this parameter is only visible in the Attributes tab when linking has been resolved, which means after a LightLinkResolve node or when Implicit Resolvers are active. Examines the lightList attribute on your linked objects to ensure that the attributes have been set correctly. If the parameter has been disabled, the value of the enable child attribute in the lightList attribute for your light is 0; otherwise, the default enabled setting is 1.
on | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light on for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.
off | N/A | A CEL Statement through which scene graph locations can be linked to the selected light, thereby turning shadow casting from this light off for those locations. The scene graph locations are specified using the Collection Expression Language (CEL). For more information, refer to the CEL Reference document found on the documentation HTML page (accessed through Help > Documentation). CEL Statements are edited using CEL Statement Widgets. For more information on the CEL Statement Widget type, refer to the CEL Statement Widget Type in Common Parameter Widgets.