Merge release v22.05

VERSIONS.md

@@ -15,12 +15,12 @@ Our test machines have the following software versions installed
 | Software      | Linux                | macOS                        | Windows                        |
 | ------------- | -------------------- | ---------------------------- | ------------------------------ |
 | OS            | CentOS Linux 7       | 10.15.7                      | Windows 10                     |
-| C++ Compiler  | gcc 6.3.1            | Apple clang 11.0.3 (Xcode 11.7) | MSVC 14.0 (Visual Studio 2015) |
-| CMake         | 3.14.6               | 3.16.5                       | 3.16.5                         |
+| C++ Compiler  | gcc 6.3.1            | Apple clang 12.0.0 (Xcode 12.4) | MSVC 14.0 (Visual Studio 2015) |
+| CMake         | 3.14.6               | 3.18.6                       | 3.16.5                         |
 | Python        | 2.7.16, 3.6.8        | 2.7.10, 3.7.7                | 2.7.12, 3.7.4, 3.8.10          |
 | Boost         | 1.66.0, 1.70.0       | 1.70.0                       | 1.70.0                         |
 | Intel TBB     | 2018 Update 6        | 2018 Update 1                | 2018 Update 6                  |
-| OpenSubdiv    | 3.4.3                | 3.4.3                        | 3.4.3                          |
+| OpenSubdiv    | 3.4.4                | 3.4.4                        | 3.4.4                          |
 | OpenImageIO   | 2.1.16.0             | 2.1.16.0                     | 2.1.16.0                       |
 | OpenColorIO   | 1.1.0                | 1.1.0                        | 1.1.0                          |
 | OSL           | 1.8.12               |                              |                                |

build_scripts/build_usd.py

@@ -1109,7 +1109,12 @@ def InstallOpenVDB(context, force, buildArgs):
 
 def InstallOpenImageIO(context, force, buildArgs):
     with CurrentWorkingDirectory(DownloadURL(OIIO_URL, context, force)):
-        extraArgs = ['-DOIIO_BUILD_TOOLS=OFF',
+        # The only time that we want to build tools with OIIO is for testing
+        # purposes. Libraries such as usdImagingGL might need to use tools like
+        # idiff to compare the output images from their tests
+        buildOIIOTools = 'ON' if (context.buildUsdImaging
+                                  and context.buildTests) else 'OFF'
+        extraArgs = ['-DOIIO_BUILD_TOOLS={}'.format(buildOIIOTools),
                      '-DOIIO_BUILD_TESTS=OFF',
                      '-DUSE_PYTHON=OFF',
                      '-DSTOP_ON_WARNING=OFF']
@@ -1196,7 +1201,7 @@ def InstallOpenColorIO(context, force, buildArgs):
 ############################################################
 # OpenSubdiv
 
-OPENSUBDIV_URL = "https://github.com/PixarAnimationStudios/OpenSubdiv/archive/v3_4_3.zip"
+OPENSUBDIV_URL = "https://github.com/PixarAnimationStudios/OpenSubdiv/archive/v3_4_4.zip"
 
 def InstallOpenSubdiv(context, force, buildArgs):
     with CurrentWorkingDirectory(DownloadURL(OPENSUBDIV_URL, context, force)):
@@ -1969,7 +1974,8 @@ def __init__(self, args):
         self.buildPrman = self.buildImaging and args.build_prman
         self.prmanLocation = (os.path.abspath(args.prman_location)
                                if args.prman_location else None)                               
-        self.buildOIIO = args.build_oiio
+        self.buildOIIO = args.build_oiio or (self.buildUsdImaging
+                                             and self.buildTests)
         self.buildOCIO = args.build_ocio
 
         # - Alembic Plugin

cmake/defaults/Options.cmake

@@ -134,6 +134,14 @@ if (${PXR_BUILD_USD_IMAGING} AND NOT ${PXR_BUILD_IMAGING})
     set(PXR_BUILD_USD_IMAGING "OFF" CACHE BOOL "" FORCE)
 endif()
 
+if (${PXR_ENABLE_METAL_SUPPORT})
+    if (NOT APPLE)
+        message(STATUS
+            "Setting PXR_ENABLE_METAL_SUPPORT=OFF because Metal is only supported on macOS")
+        set(PXR_ENABLE_METAL_SUPPORT "OFF" CACHE BOOL "" FORCE)
+    endif()
+endif()
+
 if (${PXR_ENABLE_GL_SUPPORT} OR ${PXR_ENABLE_METAL_SUPPORT} OR ${PXR_ENABLE_VULKAN_SUPPORT})
     set(PXR_BUILD_GPU_SUPPORT "ON")
 else()

cmake/defaults/Packages.cmake

@@ -190,6 +190,9 @@ if (PXR_BUILD_IMAGING)
         find_package(OpenEXR REQUIRED)
         find_package(OpenImageIO REQUIRED)
         add_definitions(-DPXR_OIIO_PLUGIN_ENABLED)
+        if (OIIO_idiff_BINARY)
+            set(IMAGE_DIFF_TOOL ${OIIO_idiff_BINARY} CACHE STRING "Uses idiff for image diffing")
+        endif()
     endif()
     # --OpenColorIO
     if (PXR_BUILD_OPENCOLORIO_PLUGIN)

cmake/defaults/Version.cmake

@@ -24,6 +24,6 @@
 # Versioning information
 set(PXR_MAJOR_VERSION "0")
 set(PXR_MINOR_VERSION "22")
-set(PXR_PATCH_VERSION "3")
+set(PXR_PATCH_VERSION "5")
 
 math(EXPR PXR_VERSION "${PXR_MAJOR_VERSION} * 10000 + ${PXR_MINOR_VERSION} * 100 + ${PXR_PATCH_VERSION}")

cmake/macros/Public.cmake

@@ -636,10 +636,22 @@ function(pxr_register_test TEST_NAME)
         return()
     endif()
 
+    set(OPTIONS RUN_SERIAL PYTHON REQUIRES_SHARED_LIBS REQUIRES_PYTHON_MODULES PERCEPTUAL)
+    set(ONE_VALUE_ARGS
+            CUSTOM_PYTHON
+            COMMAND
+            STDOUT_REDIRECT STDERR_REDIRECT
+            POST_COMMAND POST_COMMAND_STDOUT_REDIRECT POST_COMMAND_STDERR_REDIRECT
+            PRE_COMMAND PRE_COMMAND_STDOUT_REDIRECT PRE_COMMAND_STDERR_REDIRECT
+            FILES_EXIST FILES_DONT_EXIST
+            CLEAN_OUTPUT
+            EXPECTED_RETURN_CODE
+            TESTENV
+            WARN WARN_PERCENT HARD_WARN FAIL FAIL_PERCENT HARD_FAIL)
+    set(MULTI_VALUE_ARGS DIFF_COMPARE IMAGE_DIFF_COMPARE ENV PRE_PATH POST_PATH)
+
     cmake_parse_arguments(bt
-        "RUN_SERIAL;PYTHON;REQUIRES_SHARED_LIBS;REQUIRES_PYTHON_MODULES" 
-        "CUSTOM_PYTHON;COMMAND;STDOUT_REDIRECT;STDERR_REDIRECT;POST_COMMAND;POST_COMMAND_STDOUT_REDIRECT;POST_COMMAND_STDERR_REDIRECT;PRE_COMMAND;PRE_COMMAND_STDOUT_REDIRECT;PRE_COMMAND_STDERR_REDIRECT;FILES_EXIST;FILES_DONT_EXIST;CLEAN_OUTPUT;EXPECTED_RETURN_CODE;TESTENV"
-        "DIFF_COMPARE;ENV;PRE_PATH;POST_PATH"
+        "${OPTIONS}" "${ONE_VALUE_ARGS}" "${MULTI_VALUE_ARGS}"
         ${ARGN}
     )
 
@@ -719,6 +731,53 @@ function(pxr_register_test TEST_NAME)
         set(testWrapperCmd ${testWrapperCmd} --baseline-dir=${baselineDir})
     endif()
 
+    if (bt_IMAGE_DIFF_COMPARE)
+        if (IMAGE_DIFF_TOOL)
+            foreach (compareFile ${bt_IMAGE_DIFF_COMPARE})
+                set(testWrapperCmd ${testWrapperCmd} --image-diff-compare=${compareFile})
+            endforeach ()
+
+            # For now the baseline directory is assumed by convention from the test
+            # name. There may eventually be cases where we'd want to specify it by
+            # an argument though.
+            set(baselineDir ${testenvDir}/baseline)
+            set(testWrapperCmd ${testWrapperCmd} --baseline-dir=${baselineDir})
+
+            if (bt_WARN)
+                set(testWrapperCmd ${testWrapperCmd} --warn=${bt_WARN})
+            endif()
+
+            if (bt_WARN_PERCENT)
+                set(testWrapperCmd ${testWrapperCmd} --warnpercent=${bt_WARN_PERCENT})
+            endif()
+
+            if (bt_HARD_WARN)
+                set(testWrapperCmd ${testWrapperCmd} --hardwarn=${bt_HARD_WARN})
+            endif()
+
+            if (bt_FAIL)
+                set(testWrapperCmd ${testWrapperCmd} --fail=${bt_FAIL})
+            endif()
+
+            if (bt_FAIL_PERCENT)
+                set(testWrapperCmd ${testWrapperCmd} --failpercent=${bt_FAIL_PERCENT})
+            endif()
+
+            if (bt_HARD_FAIL)
+                set(testWrapperCmd ${testWrapperCmd} --hardfail=${bt_HARD_FAIL})
+            endif()
+
+            if(bt_PERCEPTUAL)
+                set(testWrapperCmd ${testWrapperCmd} --perceptual)
+            endif()
+
+            # Make sure to add the image diff tool to the PATH so
+            # it can be easily found within the testWrapper
+            get_filename_component(IMAGE_DIFF_TOOL_PATH ${IMAGE_DIFF_TOOL} DIRECTORY)
+            set(testWrapperCmd ${testWrapperCmd} --post-path=${IMAGE_DIFF_TOOL_PATH})
+        endif()
+    endif()
+
     if (bt_CLEAN_OUTPUT)
         set(testWrapperCmd ${testWrapperCmd} --clean-output-paths=${bt_CLEAN_OUTPUT})
     endif()

cmake/macros/testWrapper.py

@@ -58,10 +58,28 @@ def _parseArgs():
             action='append',
             help=('Compare output file with a file in the baseline-dir of the '
                   'same name'))
+    parser.add_argument('--image-diff-compare', default=[], type=str,
+                        action='append',
+                        help=('Compare output image with an image in the baseline '
+                              'of the same name'))
+    parser.add_argument('--fail', type=str,
+                        help='The threshold for the acceptable difference of a pixel for failure')
+    parser.add_argument('--failpercent', type=str,
+                        help='The percentage of pixels that can be different before failure')
+    parser.add_argument('--hardfail', type=str,
+                        help='Triggers a failure if any pixels are above this threshold')
+    parser.add_argument('--warn', type=str,
+                        help='The threshold for the acceptable difference of a pixel for a warning')
+    parser.add_argument('--warnpercent', type=str,
+                        help='The percentage of pixels that can be different before a warning')
+    parser.add_argument('--hardwarn', type=str,
+                        help='Triggers a warning if any pixels are above this threshold')
+    parser.add_argument('--perceptual', action='store_true',
+                        help='Performs a test to see if two images are visually different')
     parser.add_argument('--files-exist', nargs='*',
             help=('Check that a set of files exist.'))
     parser.add_argument('--files-dont-exist', nargs='*',
-            help=('Check that a set of files exist.'))
+            help=('Check that a set of files do not exist.'))
     parser.add_argument('--clean-output-paths', nargs='*',
             help=('Path patterns to remove from the output files being diff\'d.'))
     parser.add_argument('--post-command', type=str,
@@ -166,6 +184,56 @@ def _diff(fileName, baselineDir, verbose):
 
     return True
 
+def _imageDiff(fileName, baseLineDir, verbose, env, warn=None, warnpercent=None,
+               hardwarn=None, fail=None, failpercent=None, hardfail=None,
+               perceptual=None):
+    import platform
+    if platform.system() == 'Windows':
+        imageDiff = 'idiff.exe'
+    else:
+        imageDiff = 'idiff'
+
+    cmdArgs = []
+    if warn is not None:
+        cmdArgs.extend(['-warn', warn])
+
+    if warnpercent is not None:
+        cmdArgs.extend(['-warnpercent', warnpercent])
+
+    if hardwarn is not None:
+        cmdArgs.extend(['-hardwarn', hardwarn])
+
+    if fail is not None:
+        cmdArgs.extend(['-fail', fail])
+
+    if failpercent is not None:
+        cmdArgs.extend(['-failpercent', failpercent])
+
+    if hardfail is not None:
+        cmdArgs.extend(['-hardfail', hardfail])
+
+    if perceptual:
+        cmdArgs.extend(['-p'])
+
+    for image in glob.glob(fileName):
+        cmd = [imageDiff]
+        cmd.extend(cmdArgs)
+        cmd.extend([_resolvePath(baseLineDir, image), image])
+
+        if verbose:
+            print("image diffing with {0}".format(cmd))
+
+        # This will print any diffs to stdout which is a nice side-effect
+        # 0: OK: the images match within the warning and error thresholds.
+        # 1: Warning: the errors differ a little, but within error thresholds.
+        # 2: Failure: the errors differ a lot, outside error thresholds.
+        # 3: The images were not the same size and could not be compared.
+        # 4: File error: could not find or open input files, etc.
+        if subprocess.call(cmd, shell=False, env=env) not in (0, 1):
+            return False
+
+    return True
+
 def _copyTree(src, dest):
     ''' Copies the contents of src into dest.'''
     if not os.path.exists(dest):
@@ -215,7 +283,7 @@ def _runCommand(raw_command, stdout_redir, stderr_redir, env,
                 "Error: return code {0} doesn't match "
                 "expected {1} (EXPECTED_RETURN_CODE).".format(retcode, 
                                                         expected_return_code))
-        sys.exit(1)       
+        sys.exit(1)
 
 if __name__ == '__main__':
     args = _parseArgs()
@@ -225,6 +293,11 @@ def _runCommand(raw_command, stdout_redir, stderr_redir, env,
                          "--diff-compare.")
         sys.exit(1)
 
+    if args.image_diff_compare and not args.baseline_dir:
+        sys.stderr.write("Error: --baseline-dir must be specified with "
+                         "--image-diff-compare.")
+        sys.exit(1)
+
     if args.clean_output_paths and not args.diff_compare:
         sys.stderr.write("Error: --diff-compare must be specified with "
                          "--clean-output-paths.")
@@ -313,4 +386,17 @@ def _runCommand(raw_command, stdout_redir, stderr_redir, env,
                                  '(DIFF_COMPARE).'.format(diff))
                 sys.exit(1)
 
+    if args.image_diff_compare:
+        converted = vars(args)
+        params = {key: converted[key] for key in
+                  ('warn', 'warnpercent', 'hardwarn',
+                   'fail', 'failpercent', 'hardfail', 'perceptual')
+                  if key in converted}
+
+        for image in args.image_diff_compare:
+            if not _imageDiff(image, args.baseline_dir, args.verbose, env, **params):
+                sys.stderr.write('Error: image diff for {0} failed '
+                                 '(IMAGE_DIFF_COMPARE).\n'.format(image))
+                sys.exit(1)
+
     sys.exit(0)

docs/tut_setup_version_badge.rst

@@ -2,4 +2,4 @@
 
    :fa:`cogs` :ref:`Configure your Environment <tut_usd_tutorials:Environment Setup>`
 
-   :fa:`check` Tested with `USD 22.03 <https://github.com/PixarAnimationStudios/USD/tree/v22.03>`_
+   :fa:`check` Tested with `USD 22.05 <https://github.com/PixarAnimationStudios/USD/tree/v22.05>`_

docs/tut_simple_shading.rst

@@ -131,7 +131,7 @@ what identifies the source of the Material's surface shading.
    pbrShader.CreateInput("roughness", Sdf.ValueTypeNames.Float).Set(0.4)
    pbrShader.CreateInput("metallic", Sdf.ValueTypeNames.Float).Set(0.0)
    
-   material.CreateSurfaceOutput().ConnectToSource(pbrShader, "surface")
+   material.CreateSurfaceOutput().ConnectToSource(pbrShader.ConnectableAPI(), "surface")
 
 Add Texturing
 =============
@@ -152,9 +152,9 @@ how to map surface coordinates to texture coordinates.
    diffuseTextureSampler = UsdShade.Shader.Define(stage,'/TexModel/boardMat/diffuseTexture')
    diffuseTextureSampler.CreateIdAttr('UsdUVTexture')
    diffuseTextureSampler.CreateInput('file', Sdf.ValueTypeNames.Asset).Set("USDLogoLrg.png")
-   diffuseTextureSampler.CreateInput("st", Sdf.ValueTypeNames.Float2).ConnectToSource(stReader, 'result')
+   diffuseTextureSampler.CreateInput("st", Sdf.ValueTypeNames.Float2).ConnectToSource(stReader.ConnectableAPI(), 'result')
    diffuseTextureSampler.CreateOutput('rgb', Sdf.ValueTypeNames.Float3)
-   pbrShader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).ConnectToSource(diffuseTextureSampler, 'rgb')
+   pbrShader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).ConnectToSource(diffuseTextureSampler.ConnectableAPI(), 'rgb')
 
 Note that we have not yet specified what texture coordinate (primvar) the
 PrimvarReader should read. We could author the name of the primvar directly on

pxr/base/arch/CMakeLists.txt

@@ -15,6 +15,7 @@ pxr_library(arch
         ${PLATFORM_LIBS}
 
     PUBLIC_CLASSES
+        align
         attributes
         daemon
         debugger
@@ -37,7 +38,6 @@ pxr_library(arch
         vsnprintf
 
     PUBLIC_HEADERS
-        align.h
         api.h
         buildMode.h
         defines.h