For this instalment in our ground-up series about integrating Gaffer into a pipeline, we cover how to change node defaults.
All Gaffer nodes have plugs, whether they are visible in the Graph Editor for easy connection, or in the Node Editor as settings. These plugs have default values defined by the node’s programming. It may be the case however, that these defaults aren’t the most useful values for your use. To help with this, Gaffer allows you to provide your own, “user” defaults.
TL;DR
Gaffer.Metadata.registerValue( <cls>, <plugPath>, "userDefault", <value> )
Gaffer.NodeAlgo.applyUserDefaults( node )Registering user defaults
When a node is created from the Node Menu, Gaffer will apply any user defaults on top of the programmed default values for its plugs. User defaults are stored in Gaffer’s metadata system, and accessed using the Gaffer.Metadata API.
To define a new default value for a particular plug, register it under the userDefault key for the node class, additionally including the path to the plug like so:
Gaffer.Metadata.registerValue(
GafferScene.Camera, "apertureAspectRatio",
"userDefault", 1.77777777778
)
This changes the default aspect ratio for newly created cameras.
tip
ArnoldShader or ArnoldLight. Use the following pattern instead:Gaffer.Metadata.registerValue("<renderer:type>:<shaderName>:<parameterName>","userDefault", <newDefaultValue>)eg, for an Arnold quad light’s intensity, it would be:
"ai:light:quad_light:intensity"The most common place to do this is in a suitable startup script for the node’s module. Eg: GafferScene for the GafferScene.Camera node.
warning
Special behaviour
The gaffer UI distinguishes node defaults and user defaults in a plugs context menu – allowing people to reset values to either one. But more generally, the plug logically has a single ‘default’, which will be the user one if specified, otherwise the programmed one.
Whether or not a plug is set to its default affects a couple of things:
- Editor UIs for the plug will decorate plugs will non-default values with a little green star
. - The value of the plug will not be stored in a saved/copied script if set to the default value.
DIY
Gaffer only applies user defaults when nodes are made in the UI, this is to help keep scripts and other pipeline tools stable, and unaffected user-local changes .
As such, when creating your own node instances, you need to apply the user defaults to it yourself, if you want it to behave like a node made by the user from the node menu:
myCamera = GafferScene.Camera()
Gaffer.NodeAlgo.applyUserDefaults( myCamera )Useful links
- Notes on writing Gaffer startup scripts
- Notes on the Gaffer metadata system
- Gaffer.NodeAlgo helper functions