Fix VP2 rendering of UsdPreviewSurface with opacityThreshold

[jufrantz]

This PR fixes VP2 support for the UsdPreviewSurface opacityThreshold input, aligning it with Pixar's UsdPreviewSurface Specification.

Note: When opacityThreshold is greater than zero, opacity values less than the threshold will not be rendered, while values equal to or greater than the threshold will be fully visible.

Included Changes:

• Fixed the UsdPreviewSurfaceLightAPI*.xml fragment graphs to expose opacityThreshold. The ShadeFragment node input was not connected to the MShaderInstance parameter, which had no effect.
• Updated fragment shader implementations so that non-discarded fragments are fully opaque when opacityThreshold is positive.
• Aligned the C++ implementation PxrMayaUsdPreviewSurface::compute for software rendering.
• Added unit tests.

Results:

Snaphots of the scene included in the unit tests. TestOpacityThreshold.usda features 5 planes with materials bound that have textured opacity, with opacityThreshold gradually increasing from 0.0 to 1.0 from left to right.

usdview/HdStorm

vp2RenderDelegate before PR

vp2RenderDelegate after PR

[JGamache-autodesk]

Nicely done! Thank you!

[seando-adsk]

@jufrantz Unfortunately the preflight failed two different build configurations:

1. Maya 2022, Interactive, Windows:

======================================================================
ERROR: testOpacityThreshold (__main__.testVP2RenderDelegateUSDPreviewSurface)
----------------------------------------------------------------------
Traceback (most recent call last):
  File ".../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate\testVP2RenderDelegateUSDPreviewSurface.py", line 285, in testOpacityThreshold
    mayaUsdLib.PrimUpdaterManager.editAsMaya(stageShapeNode + ",/scene/camera")
AttributeError: 'module' object has no attribute 'PrimUpdaterManager'

I believe here you just need to conditionally run your new test:
@unittest.skipUnless(ufeFeatureSetVersion() >= 3, 'Test only available in UFE v3 or greater.')

2. Maya 2026, Interactive, Linux:

======================================================================
FAIL: testDrawModes (__main__.testVP2RenderDelegateDrawModes.testDrawModes)
----------------------------------------------------------------------
Traceback (most recent call last):
  File ".../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate/testVP2RenderDelegateDrawModes.py", line 87, in testDrawModes
    self.assertSnapshotClose('%s_cross_all_positive.png' % self._testName, imageVersion)
  File ".../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate/testVP2RenderDelegateDrawModes.py", line 64, in assertSnapshotClose
    return self.assertImagesClose(baselineImage, snapshotImage)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../maya-usd/test/testUtils/imageUtils.py", line 208, in assertImagesClose
    self.fail(msg)
AssertionError: Images differed by 0.001973237790486565 (max allowed: 0.0001):
  .../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate/VP2RenderDelegateDrawModesTest/baseline/post-22_11-DrawModes_cross_all_positive.png
  .../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate/testVP2RenderDelegateDrawModesOutput/DrawModes_cross_all_positive.png

I'm not sure if your changes have affected this test. Maybe @JGamache-autodesk can help with this one?

Sean

[JGamache-autodesk]

The change also affects the card draw mode (which uses UsdPreviewSurface since 23.02 with an opacityThreshold of 0.1). This means @jufrantz will have to provide a set of updated baseline images for the testVP2RenderDelegateDrawModes.py unit test.

[JGamache-autodesk]

You can also take these:
updated_test_images.zip

[jufrantz]

Thank you @seando-adsk @JGamache-autodesk.
I updated baseline images with those you provided for USD > 22.11.
I fixed the test with ufe v2 (editAsMaya was not really needed here, it now uses a maya native camera).
Julien

[seando-adsk]

@jufrantz I re-ran the preflight and it still failed on "Maya 2022, Python 2, interactive, Windows"

======================================================================
FAIL: testOpacityThreshold (__main__.testVP2RenderDelegateUSDPreviewSurface)
----------------------------------------------------------------------
Traceback (most recent call last):
  File ".../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate\testVP2RenderDelegateUSDPreviewSurface.py", line 310, in testOpacityThreshold
    self.assertSnapshotClose('opacityThreshold.png')
  File ".../maya-usd/test/lib/mayaUsd/render/vp2RenderDelegate\testVP2RenderDelegateUSDPreviewSurface.py", line 60, in assertSnapshotClose
    return self.assertImagesClose(baseline_image, snapshot_image)
  File "...\maya-usd\test\testUtils\imageUtils.py", line 208, in assertImagesClose
    self.fail(msg)
AssertionError: Images differed by 0.0262658122277 (max allowed: 0.0001):

[jufrantz]

Sorry for this @seando-adsk,
I tried on maya2022 python2 linux and the test is passing.
This might be failing only on windows and I won't have access to a windows setup in the short term.
Are there any additional relevant logs ? Would it be possible to share the snapshot generated by the failing test?
Thank you,
Julien

[jufrantz]

Hello,
I found the issue. I was testing with Maya 2022.5 (Maya light API v2), I just tried Maya 2022.0 (API v1) and got the same image diff ratio than the preflight. Since I didn't add support for opacityThreshold with API v1 and adding it would require more work due to fragment graph changes in V2, I'll just disable the test in this case.
Julien

[JGamache-autodesk]

LGTM. Only one minor comment.

[jufrantz]

Thanks for the detailed review @JGamache-autodesk. On my end this one is ready to pass preflight and hopefully be merged.

[seando-adsk]

@jufrantz I merged your PR this morning. Thank you for the submission and getting all the test errors fixed.