# 1.2.0.0

This version enables Cycles support by default, as we believe we have made sufficient progress to allow wider testing. We may continue to make behaviour-changing updates if necessary though, so support is not yet considered final.

Note

Python 2 support has been removed. All builds are now using Python 3.

## Features

• Windows : Added official builds for Windows.

• HierarchyView : Added control over the Visible Set, which defines the locations within the scene that are loaded and rendered by the Viewer.

• The Inclusions column adds locations to the Visible Set, so that they and their descendants are rendered in the Viewer without needing to be expanded in the HierarchyView.

• The Exclusions column excludes locations from the Visible Set, so that they and their descendants are never rendered in the Viewer, regardless of any other expansions or inclusions.

• Locations can have their Visible Set inclusion or exclusion toggled by clicking within the appropriate column. Shift-clicking will remove the location and any of its descendants from the Visible Set. When multiple locations are selected, edits to any of the selected locations will affect all selected locations.

• Mute/Solo : Added the ability to mute and solo lights.

• A light can be muted by setting the light:mute attribute. If that attribute is not present, the light will not be muted.

• One or more lights can be enabled exclusively via membership in the soloLights set. If that set has one or more members, only the lights in that set will emit. If the set is empty, all lights emit according to their mute state. If a light is both muted and in the soloLights set, it will emit.

• Light Editor :

• Added a “Mute” column for toggling a light’s mute attribute on and off.

• Added a “Solo” column to quickly add and remove lights from the soloLights set.

• Lights : Added a mute toggle, which can be accessed in the node editor from the Light Linking tab.

• Added a visual indication to lights in the viewport when they are muted. Muted lights use a dark gray outline instead of yellow.

• Cycles : Muted lights are disabled in renders.

• Arnold : Muted lights are disabled in renders.

• Animation :

• Added new curve extrapolation modes to determine the shape of a curve outside the range of its keys.

• Constant : Curve is extended as a flat line.

• Linear : Curve is extended as a line with slope matching tangent in direction of extrapolation.

• Cycle : Curve is repeated indefinitely.

• CycleOffset : Curve is repeated indefinitely with each repetition offset in value to preserve continuity.

• CycleFlop : Curve is repeated indefinitely with each repetition mirrored in time.

• CycleFlip : Curve is repeated indefinitely with each repetition inverted in value and offset to preserve continuity.

• Added new curve tab in Animation Editor with controls for setting the extrapolation modes of a curve.

## Improvements

• Cycles : Updated to Cycles 3.4.

• OSLObject, OSLImage : Improved performance when running heavy shaders on Linux (by 3x in one benchmark). This is achieved using OSL’s recently added batched shading API. In the event of any problem, the optimisation may be disabled by setting the environment variable GAFFEROSL_USE_BATCHED=0.

• NodeEditor : Improved interactivity by moving computations onto background threads. The UI will no longer hang while the NodeEditor waits for the result of a slow computation.

• LightEditor :

• Added a “Disable Edit” command to the right-click menu, to easily disable tweaks in EditScopes (shortcut D).

• Added a “Remove Attribute” command to the right-click menu, to delete attributes using the EditScope (shortcut Delete).

• Adjustments made to the width of the “Name” column are now preserved when switching between sections.

• Isolate : The keepLights setting now also keeps light filters.

• AttributeTweaks : Added Remove mode.

• PathListingWidget : Added support for columns that can automatically stretch to make use of available space.

• Animation Editor : For protruding tangents the slope and scale controls are now disabled (non editable) and display constrained values.

• Expression : pathlib.Path values may now be assigned to StringPlugs.

• Render : An error is now emitted if the render camera is hidden, instead of rendering through a default camera instead (#5131).

• ResamplePrimitiveVariables : Extended the supported data types when resampling from a Constant primitive variable.

• Viewer : If Arnold is available, then it is preferred over Appleseed for performing OSL shader previews. If neither is available, then Cycles will be used (#5084).

• FormatPlugValueWidget, ChannelPlugValueWidget, ChannelMaskPlugValueWidget, RGBAChannelsPlugValueWidget, ViewPlugValueWidget : Added support for showing multiple plugs at once, as needed when multiple Spreadsheet cells are selected for editing.

• Improved read performance for sets in USD files, with a benchmark reading a moderately large set seeing more than 2x speedup.

• Improved cancellation responsiveness when reading large sets from USD files.

• SceneWriter : Improved performance when writing sets to USD files.

• Spreadsheet : Improved display of image formats.

## Fixes

• Layouts : Fixed bug applying window size and position from saved layouts (#5042).

• Arnold :

• Fixed input connections to individual color and vector components when rendering with a GPU device.

• The ai:GI_diffuse_depth and ai:GI_specular_depth options now default to 2 when they are left unspecified, matching the default values on the ArnoldOptions node.

• CompoundNumericPlugValueWidget : Fixed failure to construct with an empty list of plugs.

• ChannelPlugValueWidget : Fixed compatibility with multi-view images.

• FilteredSceneProcessor :

• Fixed bugs which allowed read-only nodes to be edited.

• Fixed undo for Remove menu item in Filter tab.

• NodeEditor : Fixed bugs in handling of “green dot” non-default-value indicators with nested plugs.

• 3Delight : Fixed rendering with recent versions of 3Delight, which no longer use the DL_DISPLAYS_PATH to search for display drivers.

• Fixed memory leak.

• ShufflePrimitiveVariables, ShuffleAttributes, OptionQuery, PrimitiveVariableQuery, ShaderQuery, ContextQuery, CreateViews, SetVisualiser, OSLImage, OSLObject, OSLCode, Outputs : Fixed bugs which allowed read-only nodes to be edited.

• CodeWidget : Fixed auto-complete for pathlib.Path objects, and any other classes which throw AttributeError for an attribute advertised by dir().

• Expression : Fixed non-deterministic parsing order for Python expressions (#4935).

• FileSequencePathFilter : Fixed bug whereby files were considered to be part of a sequence if they were in a numbered directory. Now only numbers in the file’s name are considered.

• BoolWidget : Fixed bug triggered by calling setImage() from within a with widgetContainer block.

• LevelSetOffset, MeshToLevelSet, LevelSetToMesh, SphereLevelSet : Fixed bugs which could cause unnecessary repeated computations, or in the worst case, lead to deadlock.

• ValuePlug : Fixed rare deadlock when a TaskParallel compute recurses to a Legacy compute with the same hash.

• GafferTest : Fixed bug which caused parallelGetValue() to use the wrong context.

• LightEditor : Fixed bug which could cause attribute edits to be made for a parent location instead of the desired one.

• BackgroundMethod : Fixed bug that could cause the postCall to be called on a widget that had already been removed from the UI.

## API

• Filesystem path handling : Adopted std::filesystem::path and pathlib.Path in the C++ and Python APIs respectively, with automatic conversion between the two. These simplify common use cases, and provide for more elegant cross-platform path handling.

• ScriptNode : serialiseToFile(), executeFile() and importFile() now take filesystem::path arguments.

• Reference :

• load() now takes a filesystem::path argument.

• fileName() now returns a filesystem::path argument.

• Box : exportForReference() now takes a filesystem::path argument.

• ApplicationRoot :

• savePreferences() now takes a filesystem::path argument.

• preferencesLocation() now returns a filesystem::path.

• FileSystemPath :

• Added a constructor that accepts a filesystem::path.

• Added a standardPath() method returning a std::filesystem::path object in C++ and a pathlib.Path object in Python.

• StringPlug : Added a setValue() overload taking a filesystem::path.

• Dispatcher : jobDirectory() now returns a filesystem::path.

• Backups : File names are now represented using pathlib.Path.

• TestCase : temporaryDirectory() now returns a pathlib.Path.

• ShaderView : registerReferenceScene() now takes a filesystem::path.

• Catalogue : save() and load() take a filesystem::path, and generateFileName() returns one.

• ExtensionAlgo : exportExtension() now takes a pathlib.Path in the directory argument.

• PlugValueWidget : Added new API to provide asynchronous updates. The old _updateFromPlugs() and _plugConnections() methods are deprecated, and support for them will be removed in a future version.

• PathColumn : Added setSizeMode() and getSizeMode() methods, and sizeMode constructor argument. These allow the size behaviour of a PathColumn to be configured.

• EditScopeAlgo : Added acquireSetEdits() method.

• TestCase : Added scopedLocale() method.

• Animation :

• The slope and scale of protruding tangents is now constrained to match the values of the sibling tangent.

• Added curve.extrapolationChangedSignal() function, returns a signal that is called when a curve’s extrapolation has changed.

• Added new api for curve extrapolation modes (see header Animation.h for full details).

• Added description metadata for curve extrapolation modes that is used to generate UI tooltips.

• PlugAlgo : Added findDestination() utility method.

• Style : renderAnimationCurve() function now takes a vector of curve vertices and an inKeyRange argument that indicates whether the specified curve vertices lie within the time range of the curve’s keys.

• PlugAlgo : Added dependsOnCompute() utility method.

• PathColumn : Added buttonPressSignal(), buttonReleaseSignal() and buttonDoubleClickSignal(). These allow a PathColumn to implement its own event handling.

• Capsule : Removed attempts to detect invalidated Capsules.

• VisibleSet/VisibleSetData : Added struct used to define a subset of the scene to be rendered based on expansions, inclusions, and exclusions. This is used to allow scene locations to be defined as always or never renderable, overriding the usual UI expansion behaviour.

• ContextAlgo : Added setVisiblesSet(), getVisibleSet(), and affectsVisibleSet() methods.

• SceneGadget : Added setVisibleSet(), and getVisibleSet() methods.

• EditScopeAlgo : Added methods to modify and query modifications to set members in an Edit Scope.

• Widget : Added support for a _postContructor() method, which is called after the widget is fully constructed. This can be useful for performing post-initialisation work from a base class.

• GafferTest : Added ObjectPlug overloads for repeatGetValue() and parallelGetValue().

• SceneTestCase : Added assertParallelGetValueComputesObjectOnce(). This can be used to check that expensive computes are using an appropriate cache policy.

• Gaffer ( Python module ) : Added rootPath() and executablePath() methods.

• TestLightFilter : Added new node to GafferSceneTest, to aid in testing of scenarios involving LightFilters.

## Breaking Changes

• Python : Removed support for Python 2.

• MaterialX : The majority of OSL shaders in shaders/MaterialX are no longer provided, as the OpenShadingLanguage project removed them and no direct equivalent exists in the MaterialX project itself. We recommend using alternative shaders, or if necessary, sourcing them from a previous Gaffer release.

• Arnold : Changed the default values for the ai:GI_diffuse_depth and ai:GI_specular_depth options.

• Locale : Removed LC_NUMERIC=C environment variable assignment from wrapper. This was a workaround for an OpenColorIO bug that has since been fixed.

• Style : Changed the signature of the renderAnimationCurve() virtual function.

• Signal : Removed disconnect( slot ) method. This was a performance hazard because it was linear in the number of connections. Use Connection::disconnect() instead, which is constant time.

• GafferTest : Removed expectedFailure() decorator. Use unittest.expectedFailure() instead.

• SceneWriter :

• Sets are now only written on the first frame for each file written.

• SceneInterface::writeSet() is now used in preference to SceneInterface::writeTags() for all non-legacy file formats.

• SceneReader : SceneInterface::readSet() is now used in preference to SceneInterface::readTags() for all non-legacy formats.

• CatalogueUI : Hid OutputIndexColumn from public API.

• ContextAlgo : Removed use of the ui:scene:expandedPaths context variable. Any code directly accessing ui:scene:expandedPaths should instead use the getExpandedPaths()/setExpandedPaths()/expand()/expandDescendants() methods provided by ContextAlgo.

• SceneGadget : Removed setExpandedPaths() and getExpandedPaths() methods. setVisibleSet() and getVisibleSet() are now used instead.

• GafferUI : Removed the setReadOnly() and getReadOnly() methods from the following widgets :

• GafferUI.PlugValueWidget

• GafferUI.NodeEditor

• GafferUI.NodeUI

• GafferUI.PlugLayout

• Reference : The fileName() Python binding now returns a pathlib.Path argument, or None for empty file names.

• ApplicationRoot : The preferencesLocation() Python binding now returns a pathlib.Path argument.

• StringPlug : setValue( std::filesystem::path & ) now uses path.generic_string() for the value, whereas before an automatic conversion would have used path.string() (the native string).

• Dispatcher : the jobDirectory() Python binding now returns a pathlib.Path, or None if it is empty.

• Context::EditableScope, ImagePlug::ChannelDataScope, ScenePlug::PathScope/SetScope : Removed deprecated functions which didn’t take pointers and required duplication of data.

• ViewportGadget : Removed deprecated gadgetsAt() signature.

• Isolate : The keepLights setting now also keeps light filters.

## Build

• Updated to GafferHQ/dependencies 6.0.0 :

• Cortex : Updated to version 10.4.5.0.

• Cycles : Updated to version 3.4.

• Embree : Updated to version 3.13.4.

• Expat : Added version 2.5.0.

• Fmt : Added version 9.1.0.

• OpenColorIO : Updated to version 2.1.2.

• OpenImageIO : Updated to version 2.4.8.0.

• OpenShadingLanguage : Updated to version 1.12.9.0.

• OpenSubdiv : Updated to version 3.4.4.

• PyString : Added version 1.1.4.

• USD :

• Updated to version 23.02.

• Enabled the OpenImageIO plugin. Among other things, this allows OpenEXR textures to be shown in usdview.

• YAML-CPP : Added version 0.7.0.

• 3Delight : Updated to 3Delight version 2.9.17.