Merge branch '1.4_maintenance'

.github/workflows/main.yml

@@ -109,6 +109,7 @@ jobs:
     - name: Install toolchain (Windows)
       run: |
         python -m pip install scons
+        python -m pip install sphinx==4.3.1 sphinx_rtd_theme==1.0.0 myst-parser==0.15.2 docutils==0.17.1 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-serializinghtml==1.1.5 sphinxcontrib-qthelp==1.0.3
         Invoke-WebRequest -Uri "https://inkscape.org/gallery/item/37363/inkscape-1.2.2_2022-12-09_732a01da63-x64.exe" -OutFile "inkscape.exe"
         Start-Process .\inkscape.exe /S -NoNewWindow -Wait
       shell: pwsh
@@ -165,6 +166,8 @@ jobs:
         curl.exe -L --output mesa.7z --url https://github.com/pal1000/mesa-dist-win/releases/download/22.3.1/mesa3d-22.3.1-release-msvc.7z
         & "C:\Program Files\7-Zip\7z.exe" x mesa.7z -omesa
         ./mesa/systemwidedeploy.cmd 1
+        echo "GALLIUM_DRIVER=llvmpipe" >> $env:GITHUB_ENV
+        Set-DisplayResolution -Width 1280 -Height 1024 -Force
       shell: pwsh
       if: runner.os == 'Windows'
 

.github/workflows/main/sconsOptions

@@ -61,4 +61,5 @@ if sys.platform == "win32" :
 	LOCATE_DEPENDENCY_PYTHONPATH=os.path.join(os.environ["GAFFER_BUILD_DIR"], "python")
 	GLEW_LIB_SUFFIX = "32"
 	INKSCAPE = "C:\\Program Files\\Inkscape\\bin\\inkscape.exe"
-	SPHINX = "noSphinxYet"
+	SPHINX = "sphinx-build.exe"
+	ENV_VARS_TO_IMPORT += " GALLIUM_DRIVER"

.github/workflows/main/setBuildVars.py

@@ -172,15 +172,6 @@
 	print( "Setting $GAFFER_GITHUB_RELEASEID to '%s'" % releaseId )
 	f.write( 'GAFFER_GITHUB_RELEASEID=%s\n' % releaseId )
 
-	if os.name == "nt" :
-		packageExtension = "zip"
-
-		# \todo Remove this when docs are ready to build
-		print( "Setting $GAFFER_VALIDATE_EXTRA_FLAGS to '--skipDocs'" )
-		f.write( 'GAFFER_VALIDATE_EXTRA_FLAGS=--skipDocs\n' )
-
-	else :
-		packageExtension = "tar.gz"
-
+	packageExtension = "zip" if os.name == "nt" else "tar.gz"
 	print( "Setting $PACKAGE_EXTENSION to '%s'" %packageExtension )
 	f.write( 'PACKAGE_EXTENSION=%s\n' %packageExtension )

Changes.md

@@ -58,12 +58,39 @@ Breaking Changes
 - Loop : Removed `nextIterationContext()` method.
 - NodeGadget, ConnectionGadget : Removed `activeForFocusNode()` virtual methods. Override `updateFromContextTracker()` instead.
 
-1.4.x.x (relative to 1.4.9.0)
+1.4.x.x (relative to 1.4.10.0)
 =======
 
 Improvements
 ------------
 
+- SetExpressions : Set Expressions containing only whitespace characters are now treated as empty rather than producing an error.
+- ArnoldShader : Moved Arnold 7.3.3.0's new `standard_volume.scatter_diffusion` parameters to a "Scatter Diffusion" section of the UI.
+
+Fixes
+-----
+
+- Arnold : Fixed bug preventing UI metadata for Imagers from being loaded for Arnold 7.3.
+- WidgetAlgo : Fixed issue preventing `grab()` from capturing popup menus on Windows.
+- ShowURL : Fixed opening of "file://" URLs on Windows (#5861).
+
+API
+---
+
+- PathListingWidget : Added `columnContextMenuSignal()`, allowing multiple clients to collaborate on the creation of a column-specific context menu.
+- HierarchyView : Added `sceneListing()` method, to allow the context menu to be customised.
+
+Documentation
+-------------
+
+- Windows : Documentation is now included in Windows release packages.
+
+1.4.10.0 (relative to 1.4.9.0)
+========
+
+Improvements
+------------
+
 - LightEditor :
   - Values of inherited attributes are now displayed in the Light Editor. These are presented as dimmed "fallback" values. Values are inherited from an ancestor of the inspected location or from attributes created in the scene globals.
   - Default values are now displayed as dimmed "fallback" values for attributes that don't exist in the scene.

SConstruct

@@ -940,7 +940,7 @@ if env["ARNOLD_ROOT"] :
 			shell = True
 		)
 
-		nodeDefRegex = re.compile( r"\s*([a-zA-Z0-9_]+)\s+(driver|color_manager|driver|filter|light|operator|options|override|shader|shape)" )
+		nodeDefRegex = re.compile( r"\s*([a-zA-Z0-9_]+)\s+(driver|color_manager|driver|filter|imager|light|operator|options|override|shader|shape)" )
 		nodes = set()
 		for line in kickOutput.split( "\n" ) :
 			m = nodeDefRegex.match( line )
@@ -2162,13 +2162,17 @@ def generateDocs( target, source, env ) :
 	localFile = os.path.basename( str(source[0]) )
 
 	ext = os.path.splitext( localFile )[1]
+	gafferCmd = shutil.which( "gaffer.cmd" if sys.platform == "win32" else "gaffer", path = env["ENV"]["PATH"] )
 	command = []
 	if localFile == "screengrab.py" :
-		command = [ "gaffer", "screengrab", "-commandFile", localFile ]
+		command = [ gafferCmd, "screengrab", "-commandFile", localFile ]
 	elif ext == ".py" :
-		command = [ "gaffer", "env", "python", localFile ]
+		command = [ gafferCmd, "env", "python", localFile ]
 	elif ext == ".sh" :
-		command = [ "gaffer", "env", "./" + localFile ]
+		if sys.platform == "win32" :
+			command = [ gafferCmd, "env", "sh", "./" + localFile ]
+		else :
+			command = [ gafferCmd, "env", "./" + localFile ]
 	if command :
 		sys.stdout.write( "Running {0}\n".format( os.path.join( root, localFile ) ) )
 		subprocess.check_call( command, cwd = root, env = env["ENV"] )
@@ -2237,7 +2241,7 @@ if haveSphinx and haveInkscape :
 	# use host python to avoid needing a matrix of sphinx versions to match Gaffer's
 	# bundled python version.
 	docEnv = env.Clone()
-	docEnv["ENV"]["PYTHONPATH"] = ":".join( sys.path )
+	docEnv["ENV"]["PYTHONPATH"] = os.path.pathsep.join( sys.path )
 
 	# Since we don't copy the docs reference scripts, the screengrab
 	# scripts must read them from the source, so we use the reference
@@ -2253,9 +2257,9 @@ if haveSphinx and haveInkscape :
 	libraryPathEnvVar = "DYLD_LIBRARY_PATH" if docEnv["PLATFORM"]=="darwin" else "LD_LIBRARY_PATH"
 
 	if docCommandEnv.subst( "$ARNOLD_ROOT" ) :
-		docCommandEnv["ENV"]["PATH"] += ":" + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
-		docCommandEnv["ENV"]["PYTHONPATH"] += ":" + docCommandEnv.subst( "$ARNOLD_ROOT/python" )
-		docCommandEnv["ENV"][libraryPathEnvVar] = docCommandEnv["ENV"].get( libraryPathEnvVar, "" ) + ":" + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
+		docCommandEnv["ENV"]["PATH"] += os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
+		docCommandEnv["ENV"]["PYTHONPATH"] += os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/python" )
+		docCommandEnv["ENV"][libraryPathEnvVar] = docCommandEnv["ENV"].get( libraryPathEnvVar, "" ) + os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
 
 	#  Docs graphics generation
 	docGraphicsCommands = graphicsCommands( docEnv, "resources/docGraphics.svg", "$BUILD_DIR/doc/gaffer/graphics" )

arnoldPlugins/gaffer.mtd

@@ -2684,26 +2684,59 @@
 	[attr density]
 		gaffer.graphEditorLayout.visible BOOL true
 		page STRING "Density"
+		gaffer.layout.index INT 0
 	[attr density_channel]
 		page STRING "Density"
+		gaffer.layout.index INT 1
 
 	[attr scatter]
 		gaffer.graphEditorLayout.visible BOOL true
 		page STRING "Scatter"
+		gaffer.layout.index INT 2
 	[attr scatter_color]
 		gaffer.graphEditorLayout.visible BOOL true
 		page STRING "Scatter"
+		gaffer.layout.index INT 3
 	[attr scatter_color_channel]
 		page STRING "Scatter"
+		gaffer.layout.index INT 4
 	[attr scatter_anisotropy]
 		page STRING "Scatter"
+		gaffer.layout.index INT 5
 	[attr scatter_secondary_anisotropy]
 		page STRING "Scatter"
 		label STRING "Secondary Anisotropy"
 		gaffer.layout.activator STRING "secondaryAnisotropyEnabled"
+		gaffer.layout.index INT 6
 	[attr scatter_secondary_anisotropy_mix]
 		page STRING "Scatter"
 		label STRING "Secondary Anisotropy Mix"
+		gaffer.layout.index INT 7
+
+	[attr scatter_diffusion]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion"
+		gaffer.layout.index INT 8
+	[attr scatter_diffusion_bias]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion Bias"
+		gaffer.layout.index INT 9
+	[attr scatter_diffusion_gain]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion Gain"
+		gaffer.layout.index INT 10
+	[attr scatter_diffusion_roughness]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion Roughness"
+		gaffer.layout.index INT 11
+	[attr scatter_diffusion_roughness_bias]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion Roughness Bias"
+		gaffer.layout.index INT 12
+	[attr scatter_diffusion_roughness_gain]
+		page STRING "Scatter Diffusion"
+		label STRING "Diffusion Roughness Gain"
+		gaffer.layout.index INT 13
 
 	[attr transparent]
 		page STRING "Transparent"

doc/source/Reference/CommandLineReference/generate.py

@@ -1,6 +1,7 @@
 # BuildTarget: index.md
 # UndeclaredBuildTargets
 
+import Gaffer
 import GafferUI
 
 GafferUI.DocumentationAlgo.exportCommandLineReference( "./", ignore = { "op" } )

doc/source/Reference/NodeReference/generate.py

@@ -1,6 +1,7 @@
 # BuildTarget: index.md
 # UndeclaredBuildTargets
 
+import Gaffer
 import GafferUI
 
 # GafferArnold isn't installed under the standard module path

doc/source/WorkingWithScenes/AnatomyOfACamera/screengrab.py

@@ -50,5 +50,6 @@
 
 	window.resizeToFitChild()
 	window.setVisible( True )
+	window.setPosition( imath.V2i( 0, 0 ) )
 
 	GafferUI.WidgetAlgo.grab( widget = sceneInspector, imagePath = "images/interfaceCamera" + imageName )

doc/source/WorkingWithScenes/AnatomyOfAScene/screengrab.py

@@ -83,5 +83,6 @@ def __delay( delay ) :
 
 	window.resizeToFitChild()
 	window.setVisible( True )
+	__delay( 0.5 )
 
 	GafferUI.WidgetAlgo.grab( widget = sceneInspector, imagePath = "images/sceneInspector" + imageName )

doc/source/WorkingWithScenes/Camera/screengrab.py

@@ -16,6 +16,7 @@
 # BuildDependency: scripts/taskStandardOptionsDepthOfFieldPlug_edit.gfr
 
 import os
+import pathlib
 import subprocess
 import tempfile
 import time
@@ -39,20 +40,23 @@ def __delay( delay ) :
 		GafferUI.EventLoop.waitForIdle( 1 )
 
 # Create a random directory in `/tmp` for the dispatcher's `jobsDirectory`, so we don't clutter the user's `~gaffer` directory
-__temporaryDirectory = tempfile.mkdtemp( prefix = "gafferDocs" )
+__temporaryDirectory = pathlib.Path( tempfile.mkdtemp( prefix = "gafferDocs" ) )
 
 def __getTempFilePath( fileName, directory = __temporaryDirectory ) :
-	filePath = "/".join( ( directory, fileName ) )
 
-	return filePath
+	return ( directory / fileName ).as_posix()
+
+def __outputImagePath( fileName ) :
+
+	return pathlib.Path( "images/{}.png".format( fileName ) ).absolute().as_posix()
 
 def __dispatchScript( script, tasks, settings ) :
 	command = "gaffer dispatch -script {} -tasks {} -dispatcher Local -settings {} -dispatcher.jobsDirectory '\"{}/dispatcher/local\"'".format(
 		script,
 		" ".join( tasks ),
 		" ".join( settings ),
-		__temporaryDirectory
-		)
+		__temporaryDirectory.as_posix()
+	)
 	subprocess.check_call( command, shell=True )
 
 # Interface: a Camera node in the Graph Editor
@@ -127,9 +131,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Aperture and Focal Length projection mode in the Node Editor
 __imageName = "taskCameraApertureFocalLengthPlugs"
@@ -143,9 +147,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Custom aperture mode and aperture.x and aperture.y plugs in the Node Editor
 __imageName = "taskCameraCustomAperturePlugs"
@@ -158,9 +162,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-  )
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: animation of adjusting the Aperture Offset in the Node Editor, and the corresponding changes to the camera's frustrum in the Viewer
 ## TODO: Automate `images/taskApertureOffset.gif` when these tools become available:
@@ -173,9 +177,9 @@ def __dispatchScript( script, tasks, settings ) :
 	script = "scripts/{}.gfr".format( __imageName ),
 	tasks = [ "Render" ],
 	settings = [
-		"-Outputs.outputs.output1.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-  )
+		"-Outputs.outputs.output1.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Depth of Field tab, with settings, in the Node Editor
 script["Camera"]["focusDistance"].setValue( 22.0 )
@@ -202,9 +206,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: a Camera node's Render Overrides tab in the Node Editor
 script["Camera"]["renderSettingOverrides"]["resolution"]["value"].setValue( imath.V2i( 5120, 2160 ) )
@@ -236,15 +240,15 @@ def __dispatchScript( script, tasks, settings ) :
 
 # Example: Anamorphic Camera Setup
 __dispatchScript(
-	script = os.path.abspath( "../../../examples/rendering/anamorphicCameraSetup.gfr" ),
+	script = pathlib.Path( "../../../examples/rendering/anamorphicCameraSetup.gfr" ).absolute().as_posix(),
 	tasks = [ "Render" ],
 	settings = [
-		"-StandardOptions.options.renderResolution.value.x '240'",
-		"-StandardOptions.options.renderResolution.value.y '270'",
-		"-Outputs.outputs.output1.fileName '\"{}\"'".format( os.path.abspath( "images/exampleAnamorphicCameraSetup.png" ) ),
+		"-StandardOptions.options.renderResolution.value.x 240",
+		"-StandardOptions.options.renderResolution.value.y 270",
+		"-Outputs.outputs.output1.fileName '\"{}\"'".format( __outputImagePath( "exampleAnamorphicCameraSetup" ) ),
 		"-Outputs.outputs.output1.type '\"png\"'"
-		]
-	)
+	]
+)
 
 # Example: Spherical Camera Setup in Arnold
 # __dispatchScript(