Gaffer 0.59 includes some important changes to how Boxes are exported for use as References (.grf files).
We no longer reset the default values to those currently set on the node.
If you ever export a Box, or publish a reference, read on!
Summary
When exporting a Box for use as a reference, you will now be warned if any plugs have non-default values. These plugs will be reset to their defaults in the exported .grf file. If you need the current plug values to be used instead, you need to reset the plugs’ default values via the right-click context menu.
References – an overview
Gaffer allows a Box to be exported in a special format – the .grf reference. These files can then be loaded in to the Reference node to be re-used in other graphs. This allows work to be shared between scripts, or simple tools to be made.
When used as a Reference, the contents of the box (its ‘sub-graph’) are locked and can’t be edited directly. Only plugs on the box itself (which then appear on the Reference node) can be adjusted.
A common practice is to promote select plugs from the sub-graph onto the Box before export. This allows the author of the box to define exactly what controls are available to the user in their script.
More details of this process are available in the Gaffer Box node documentation.
Default values
Every plug in Gaffer has a default value. This is the initial value of the plug when its node is created. If its value is adjusted, the green ‘value changed’ dot (
) appears next to its label. Plugs can always set back to their default value via the right-click context menu.
When promoting plugs to a Box for use as a reference, new defaults may be required to make the reference more useful for the user. For example, a GroundPlane tool that makes use of the Plane node, may want to promote the Dimensions plug, but change the default to 1000 x 1000. If you are sharing a lighting setup, a presets menu that changes variations may be exposed with a specific default.
In previous versions of Gaffer, we reset the default values in the .grf export to those set on the box at the time of export.
Inadvertent changes
Though convenient, this caused regular problems in production. People exporting updates to an existing reference may have been experimenting with plug values to test new functionality. As there was no easy way to know what values the plugs were set to for the last export once they’d been changed, this could result in the new export having different defaults.
Gaffer doesn’t save the value for plugs set to their defaults in a script. Changing a plug’s default value has the potential to change the value in every script that uses the reference! This can lead to inadvertent changes in previously signed-off work.
Exports in 0.59 onwards
To help avoid these side-effects, we’ve changed how the Box export mechanism works in Gaffer 0.59.0.0.
You will now be warned if you attempt to export a Box that has plugs set to non-default values. If you choose to continue with the export, the values in the .grf file will be different to those you see in the Node Editor.
If you want the current values to be used instead, you will need to reset the relevant plugs’ default values. The Details section of the confirmation dialogue lists which plugs are not set to their default values.
We hope that making the authoring of defaults into a conscious, explicit action will minimise unexpected side-effects in scripts that make use of the reference.
Resetting default values
There are two options for resetting default values to the current value of a plug.
- Individual plugs : Choose
Reset Default Valuefrom the plug’s right-click context menu. - All plugs on a Node : Choose
Reset Default Valuesfrom the Node’s tool menu (
).
Developer notes
If your pipeline code makes use of Gaffer::Box::exportForReference( fileName ), the new defaults behaviour still applies. As this is a non-UI function, the confirmation stage outlined above will not be shown. You may wish to alert the user in a similar fashion as you see appropriate.