Merge branch 'dev' into tremblp/HYDRA-1242/isolate_select_hang

Author: ppt-adsk

doc/build.md

@@ -12,7 +12,7 @@ Before building the project, consult the following table to ensure you use the r
 |:---------------------:|:-------------------------:|:------------------------------------------------------------:|:---------------------------:|
 |    Operating System   |         Windows 10 <br> Windows 11 | High Sierra (10.13)<br>Mojave (10.14)<br>Catalina (10.15)<br>Big Sur (11.2.x)    |      Rocky Linux 8.6 / Linux® Red Hat® Enterprise 8.6 WS             |
 |   Compiler Requirement| Maya 2024 (VS 2022)<br>Maya 2025 (VS 2022) | Maya 2024 (Xcode 13.4 or higher)<br>Maya 2025 (Xcode 13.4 or higher) | Maya 2024 (gcc 11.2.1)<br>Maya 2025 (gcc 11.2.1) |
-| CMake Version (min/max) |        3.13...3.30      |                              3.13...3.30                     |           3.13...3.30       |
+| CMake Version (min/max) |        3.14...3.30      |                              3.14...3.30                     |           3.14...3.30       |
 |         Python        | 3.10.8, 3.11.4  |                       3.10.8, 3.11.4               |  3.10.8, 3.11.4   |
 |    Python Packages    | PyYAML, PySide, PyOpenGL        | PyYAML, PySide2, PyOpenGL              | PyYAML, PySide, PyOpenGL |
 |    Build generator    | Visual Studio, Ninja (Recommended)    |  XCode, Ninja (Recommended)                      |    Ninja (Recommended)      |
@@ -25,19 +25,20 @@ Before building the project, consult the following table to ensure you use the r
 
 #### 2. Download and Build Pixar USD 
 
-See Pixar's official github page for instructions on how to build USD: https://github.com/PixarAnimationStudios/USD. Pixar has removed support for building Maya USD libraries/plug-ins in their github repository and ```build_usd.py```.
+See Pixar's official github page for instructions on how to build USD: https://github.com/PixarAnimationStudios/USD.<BR> 
+If you want to <B>be able to import usd data in maya through [MayaUSD](https://github.com/Autodesk/maya-usd) and use a hydra render delegate in the viewport, you have to rebuild MayaHydra with the same version used by MayaUSD </B>which is a customized version of OpenUSD, these versions are :
 
-|               |      ![](images/pxr.png)          |USD version used in Maya        
-|:------------: |:---------------:                  |:---------------:
-|  CommitID/Tags | [v22.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v22.11), [v23.08](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.08), [v23.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.11) or [v24.05](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v24.05) |Maya 2024 = v22.11<br>Maya 2025 = v23.11<br>Maya PR = v24.05
+|               |      ![](images/pxr.png)          | USD version used in Maya | USD source for MayaUSD / MayaHydra |
+|:------------: |:---------------:                  |:------------------------:|:-------------------------:|
+|  CommitID/Tags | [v22.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v22.11)<BR>[v23.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v23.11)<BR>[v24.11](https://github.com/PixarAnimationStudios/OpenUSD/releases/tag/v24.11) |Maya 2024 = v22.11<br>Maya 2025 = v23.11<br>Maya PR = v24.11| [v22.11-MayaUsd-Public](https://github.com/autodesk-forks/USD/tree/v22.11-MayaUsd-Public)<br>[v23.11-MayaUsd-Public](https://github.com/autodesk-forks/USD/tree/v23.11-MayaUsd-Public)<br>[v24.11-MayaUsd-Public](https://github.com/autodesk-forks/USD/tree/v24.11-MayaUsd-Public) |
 
 For additional information on building Pixar USD, see the ***Additional Build Instruction*** section below.
 
 ***NOTE:*** Make sure that you don't have an older USD locations in your ```PATH``` and ```PYTHONPATH``` environment settings. ```PATH``` and ```PYTHONPATH``` are automatically adjusted inside the project to point to the correct USD location. See ```cmake/usd.cmake```.
 
 #### 3. Download and Build MayaUSD 
 
-Starting from Maya 2025, the project requires MayaUSD to build.  This enables more features for USD stages when using a Hydra render delegate, such as: hide/delete the stage when the proxy shape node is hidden/deleted, or applying a transform on the proxy shape node will apply it on the stage. 
+Starting from Maya 2025, the project requires [MayaUSD](https://github.com/Autodesk/maya-usd) to build.  This enables more features for USD stages when using a hydra render delegate, such as: hide/delete the stage when the proxy shape node is hidden/deleted, or applying a transform on the proxy shape node will apply it on the stage. 
 
 To build MayaUSD, see the github page https://github.com/Autodesk/maya-usd/blob/dev/doc/build.md
 
@@ -47,7 +48,7 @@ The Universal Front End (UFE) is a DCC-agnostic component that allows Maya to br
 
 | Ufe Version                | Maya Version                                           | Ufe Docs (external) |
 |----------------------------|--------------------------------------------------------|:-------------------:|
-| v4.0.0<br>v4.1.0<br>v4.2.0<br>v4.2.0            | Maya 2024<br>Maya 2024.1<br>Maya 2024.2<br>Maya 2025                                                | https://help.autodesk.com/view/MAYADEV/2025/ENU/?guid=MAYA_API_REF_ufe_ref_index_html |
+| v4.0.0<br>v4.1.0<br>v4.2.0<br>v4.2.0<br>v6.0.0            | Maya 2024<br>Maya 2024.1<br>Maya 2024.2<br>Maya 2025<br>Maya PR                                                | https://help.autodesk.com/view/MAYADEV/2025/ENU/?guid=MAYA_API_REF_ufe_ref_index_html |
 
 To build the project with UFE support, you will need to use the headers and libraries included in the ***Maya Devkit***:
 
@@ -65,9 +66,14 @@ cd maya-hydra
 
 | Location      | Description                                                                                   |
 |-------------  |---------------------------------------------------------------------------------------------  |
-| lib/mayaHydra/mayaPlugin | Contains Maya plugin definition and render override registration  |
-| lib/mayaHydra/hydraExtensions | Contains extensions to and mechanism needed to interface with hydra classes |
-| lib/mayaHydra/ufeExtensions | Contains extensions to translate paths between UFE, USD SdfPath and Maya DAGPath |
+| [lib/adskHydraSceneBrowser](https://github.com/Autodesk/maya-hydra/tree/dev/lib/adskHydraSceneBrowser)| Contains the hydra scene browser to help you debugging the scene indices and usd data |
+| [lib/flowViewport](https://github.com/Autodesk/maya-hydra/tree/dev/lib/flowViewport)| Contains the [Flow Viewport Toolkit](https://github.com/Autodesk/maya-hydra/blob/dev/doc/flowViewportToolkit.md) to add hydra primitives scene indices or add filtering scene indices to the viewport.<BR>What you retrieve in this folder is <B>the code that is not maya dependent and could be re-used by another hydra project</B>|
+| [lib/mayaHydra/](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra)| Contains code that is dependent from Maya |
+| [lib/mayaHydra/flowViewportAPIExamples](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/flowViewportAPIExamples) | Contains samples on how to use the [Flow Viewport Toolkit](https://github.com/Autodesk/maya-hydra/blob/dev/doc/flowViewportToolkit.md) to add hydra primitives scene indices or add filtering scene indices to the viewport|
+| [lib/mayaHydra/hydraExtensions](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/hydraExtensions) | Contains extensions and mechanisms needed to interface with hydra classes |
+| [lib/mayaHydra/mayaPlugin](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/mayaPlugin) | Contains MayaHydra plugin definition and render override registration  |
+| [lib/mayaHydra/ufeExtensions](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/ufeExtensions) | Contains extensions to translate paths between UFE, USD SdfPath and Maya DAGPath |
+
 
 #### 6. How To Use build.py Script
 

doc/flowViewportToolkit.md

@@ -1,6 +1,6 @@
 # Flow viewport toolkit
 
-The Flow viewport toolkit  is an API for clients to customize the Hydra viewport.
+The Flow viewport toolkit is an API for clients to customize the Hydra viewport.
 
 ## About the API
 -   It is based on  **Hydra 2.0** and leverages the scene index mechanisms, it was not designed to be used with a Hydra 1.0 (scene delegate).
@@ -97,5 +97,11 @@ To get an instance of the *VersionInterface* class, please use :
 You get the version as semantic versioning  : majorVersion, minorVersion and patchLevel.
 
 ## Samples
-The API contains examples which are Maya projects on how to filter and add primitives and get viewport information, please see [Flow viewport API examples](../lib/mayaHydra/flowViewportAPIExamples).
-
+The API contains examples which are Maya projects on how to filter and add primitives and get viewport information, please see [Flow viewport API examples](../lib/mayaHydra/flowViewportAPIExamples) :
+
+| Location      | Description                                                                                   |
+|-------------  |---------------------------------------------------------------------------------------------  |
+| [lib/flowViewport/usdPlugins/shadersDiscoveryPlugin](https://github.com/Autodesk/maya-hydra/tree/dev/lib/flowViewport/usdPlugins/shadersDiscoveryPlugin) | Is an example on how to develop a custom GLSL shader for Hydra Storm which you can apply later on USD / Hydra primitives |
+| [lib/mayaHydra/flowViewportAPIExamples/customShadersNode](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/flowViewportAPIExamples/customShadersNode) | Is a Maya node which creates an Hydra primitive and applies the custom GLSL shader for Hydra Storm |
+| [lib/mayaHydra/flowViewportAPIExamples/flowViewportAPILocator](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/flowViewportAPIExamples/flowViewportAPILocator) | Is a Maya node which creates Hydra primitives to display a grid of cubes and applies a filtering scene index to remove primitives with more than a certain number of vertices.<BR>This example shows how to create a Hydra mesh primitive, how to use Hydra instancing and deal with selection picking from MayaHydra|
+| [lib/mayaHydra/flowViewportAPIExamples/footPrintNode](https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/flowViewportAPIExamples/footPrintNode) | Is a Maya node showing how to convert the Maya FootPrint node which is part of the samples from the Maya devkit. It shows how to create Hydra mesh primitives and deal with selection picking from MayaHydra|

doc/selectionHighlightingArchitecture.md

@@ -8,7 +8,7 @@ supports Hydra rendering in this repository as the Flow Viewport Toolkit (name
 subject to change).
 
 This document will describe the state of Flow Viewport Toolkit selection
-highlighting as of 31-May-2024.
+highlighting as of 5-Dec-2024.
 
 ## Behavior
 
@@ -73,7 +73,8 @@ provide the following services:
 - A way to translate the application's selection path(s) into Hydra paths and data sources:
     - So that the appropriate prims in Hydra can be dirtied on selection change.
     - So that selected prims in Hydra can have a data source added.
-  This is embodied in a **Path interface**.
+  This is embodied in a **Path Mapper**.  The plugin must therefore create
+  a path mapper and register it in the **Path Mapper Registry**.
 
 - A way for the plugin to query the Hydra version of the application
   selection:
@@ -85,20 +86,21 @@ provide the following services:
 ### Selection Change
 
 This
-[selection change code](../lib/flowViewport/sceneIndex/fvpSelectionSceneIndex.cpp#L152-L173)
-shows the use of the *Path Interface*, through the *UfePathToPrimSelections()* method,
-called on the input scene index.  The path interface allows the selection scene
-index to translate selected application paths to selected Hydra scene index
-paths.
+[selection change code](../lib/flowViewport/sceneIndex/fvpSelectionSceneIndex.cpp)
+shows the use of the *ufePathToPrimSelections()* utility function.  This
+utility accesses the **Path Mapper Registry** and retrieves a path mapper 
+that implements the translation of selected application paths to selected 
+Hydra scene index paths.  *ufePathToPrimSelections()* then invokes the 
+path mapper and returns the Hydra scene index paths.
 
 ### Wireframe Selection Highlighting
 
 This
-[wireframe selection highlighting code](../lib/flowViewport/sceneIndex/fvpWireframeSelectionHighlightSceneIndex.cpp#L462-L465)
+[wireframe selection highlighting code](../lib/flowViewport/sceneIndex/fvpWireframeSelectionHighlightSceneIndex.cpp)
 shows the use of the *Selection*, through the
-*HasFullySelectedAncestorInclusive()* method, called on the input selection.
+*IsFullySelected()* method, called on the input selection.
 The selection allows a selection highlighting filtering scene index to query
-selected prims.
+selected prims.  It can also query the *selections* data source on a prim to determine selection status.
 
 ## Design Option Discussion
 
@@ -108,12 +110,24 @@ selected prims.
   to them described as `SdfPath`.  This keeps plugins independent of any
   particular application's representation of selection.
 
-- **Plugins access the Hydra selection through the scene index tree**: although
-  the selection is conceptually a singleton, we will provide access to it for
-  scene index selection highlighting plugins through the scene index tree, by
-  adding a mixin interface to the plugins.  This avoids creating another object
-  to maintain and encapsulate the Hydra selection, since the selection scene
-  index is already performing this job.
+- **Plugins create and register a path mapper object** to translate application
+  selection paths to Hydra scene index prim selection paths.  Application
+  paths are described through the Universal Front End API, with 
+  `Ufe::Path`, and Hydra scene index prim paths are described with OpenUSD
+  `SdfPath`.  A selection in the application must be translated to a
+  selection in the Hydra scene graph, using a path mapper.
+
+  For example, consider a USD stage rooted at application path
+  `|stage1|stageShape1`, and a USD prim `/Cube1` in that stage.  This is
+  described in the application by the `Ufe::Path` `|stage1|stageShape1,/Cube1`.
+  Its corresponding Hydra prim path might be 
+  `/MayaUsdProxyShape_PluginNode/mayaUsdProxyShape1/Cube1`.  A Hydra USD data 
+  producer plugin can register a path mapper that converts all `Ufe::Path` that
+  begin with path prefix `|stage1|stageShape1` to Hydra scene index
+  prim paths that begin with the `SdfPath` prefix
+  `/MayaUsdProxyShape_PluginNode/mayaUsdProxyShape1`, so that 
+  `|stage1|stageShape1,/Cube1` gets mapped into 
+  `/MayaUsdProxyShape_PluginNode/mayaUsdProxyShape1/Cube1`.
 
 ## Implementation
 
@@ -161,15 +175,14 @@ graph BT;
         roSn-.->ph2;
     end
     snSi[Selection scene index]-->ph2;
-    fvpm[Flow Viewport merge]-->snSi;
+    dpm[Data producer merge]-->snSi;
     subgraph pd[Plugin data]
         p1[Plugin 1];
         p2[Plugin 2];
     end
-    fvpm-. Path .->p1;
-    p1-->fvpm;
-    p2-->fvpm;
-    snSi-. Path .->fvpm;
+    dpm-. Path .->p1;
+    p1-->dpm;
+    p2-->dpm;
     sn[/Selection/]-.->snSi;
 ```
 The plugin data and plugin highlighting subtrees are where plugins add their
@@ -186,10 +199,6 @@ The object modeling is the following:
 - **Selection scene index**: builtin provided by the Flow Viewport Toolkit.
     - Has a pointer to read and write the Hydra selection.
     - Translates the application selection to Hydra selection.
-- **Flow Viewport merging scene index**: builtin provided by the Flow Viewport
-  library.
-    - Receives data from data provider plugin scene indices.
-    - Forward path interface queries to plugin scene indices
 - **Plugin data scene index**: provided by plugin.
     - Injects plugin data into Hydra
 - **Plugin selection highlighting scene index**: provided by plugin.
@@ -199,14 +208,14 @@ The object modeling is the following:
     - Adds required geometry or data sources to implement selection
       highlighting
 
-### New Scene Index Mixin Interface Base Class
+### New Path Mapper Base Class
 
-The Flow Viewport Toolkit has a new mixin interface class:
+The Flow Viewport Toolkit has a new base class:
 
-- **Path Interface**: so that the builtin selection scene index can query
-  plugins to translate selected object application paths to selected Hydra
+- **PathMapper**: must be provided by data provider plugins so that Hydra
+  can translate selected object application paths to selected Hydra
   prim paths. The plugin provides the concrete implementation of this
-  interface.
+  base class, and registers it to the **path mapper registry***.
 
 ### Implementation Classes
 
@@ -216,8 +225,9 @@ The Flow Viewport Toolkit has a new mixin interface class:
     - Requires selected ancestor query from selection.
     - Dirties descendants on selection dirty.
 - **Render index proxy**:
-    - Provides encapsulated access to the builtin Flow Viewport merging scene
-      index.
+    - Provides encapsulated access to the data producer merging scene
+      index.  This is a standard Hydra merging scene index to which Flow
+      Viewport data producers are connected.
     - Other responsibilities to be determined, for future extension, possibly a
       [facade design pattern](https://en.wikipedia.org/wiki/Facade_pattern).
 
@@ -233,30 +243,20 @@ class Selection{
 +HasFullySelectedAncestorInclusive(SdfPath) bool
 }
 
-class PathInterface{
-+UfePathToPrimSelections(Ufe::Path) SdfPath
-}
-
 class SelectionSceneIndex
-class MergingSceneIndex
 class WireframeSelectionHighlightSceneIndex
 
 class RenderIndexProxy{
-+MergingSceneIndex mergingSceneIndex
++HdMergingSceneIndex mergingSceneIndex
 +InsertSceneIndex()
 +RemoveSceneIndex()
 }
 
 HdSingleInputFilteringSceneIndexBase <|-- SelectionSceneIndex
 
-HdMergingSceneIndex <|-- MergingSceneIndex
-PathInterface       <|-- MergingSceneIndex
-
 HdSingleInputFilteringSceneIndexBase <|-- WireframeSelectionHighlightSceneIndex
 
-RenderIndexProxy *-- MergingSceneIndex : Owns
-
-SelectionSceneIndex ..> MergingSceneIndex : Path
+RenderIndexProxy *-- HdMergingSceneIndex : Owns
 
 SelectionSceneIndex o-- Selection : Read / Write
 
@@ -271,11 +271,6 @@ WireframeSelectionHighlightSceneIndex o-- Selection : Read
   improved (to amortized O(k), for a k-element path) through the use of a
   prefix trie, such as `Ufe::Trie`.
 
-- At time of writing, merging scene index path lookup is O(n), for n input
-  scene indices.  This could be improved by implementing a caching scheme based
-  on application path, as for a given application path prefix the same
-  input scene index will always provide the translation to scene index path.
-
 ## Limitations
 
 - Little investigation of pixel-based selection highlighting capability.