HYDRA-1338 : Update documentation

Autodesk · Dec 17, 2024 · 2a9426e · 2a9426e
1 parent 46a733f
commit 2a9426e
Show file tree

Hide file tree

Showing 6 changed files with 60 additions and 14 deletions.
diff --git a/doc/build.md b/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), 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
 

diff --git a/doc/flowViewportToolkit.md b/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|
diff --git a/lib/flowViewport/usdPlugins/shadersDiscoveryPlugin/README b/lib/flowViewport/usdPlugins/shadersDiscoveryPlugin/README
@@ -1,8 +1,15 @@
+This project shows how to define and register in OpenUSD a custom GLSL shader for Hydra Storm.
+You can retrieve an Maya plugin sample that creates a Hydra primitive and applies to it this custom GLSL shader for Hydra Storm :
+https://github.com/Autodesk/maya-hydra/tree/dev/lib/mayaHydra/flowViewportAPIExamples/customShadersNode
+
 This is a pure usd plugin that is a shaders discovery plugin.
 The shaders defined in shadersDef.usda will be loaded by usd/hydra and available for use in a material network in any Hydra plugin.
 
 You can add the plugInfo.json file path in the environment variable PXR_PLUGINPATH_NAME or use another .json file to load it
-so USD/Hydra loads it at startup.
+so USD/Hydra loads it at startup. Buy default if this project is present in the install folder, it is loaded by Usd.
+
+How to use this custom GLSL shader on usd primitives :
+------------------------------------------------------
 
 To use the FVP_CustomBasicLightingShader GLSLFX shader into a usd file, just add this definition to your file :
 

diff --git a/lib/mayaHydra/flowViewportAPIExamples/customShadersNode/README b/lib/mayaHydra/flowViewportAPIExamples/customShadersNode/README
@@ -0,0 +1,7 @@
+This is a Flow viewport toolkit example. 
+The Flow viewport toolkit has been developed to :
+- create Hydra primitives directly without the need to create OpenUSD data or Maya geometry 
+- add custom Hydra filtering scene indices to MayaHydra to modify the Hydra primitives in the viewport
+
+This project is a Maya node that creates a Hydra primitive and applies to it the custom GLSL shader for Hydra Storm that is created and registered in OpenUSD/Hydra by the project 
+https://github.com/Autodesk/maya-hydra/tree/dev/lib/flowViewport/usdPlugins/shadersDiscoveryPlugin
diff --git a/lib/mayaHydra/flowViewportAPIExamples/flowViewportAPILocator/README b/lib/mayaHydra/flowViewportAPIExamples/flowViewportAPILocator/README
@@ -0,0 +1,11 @@
+This is a Flow viewport toolkit example. 
+The Flow viewport toolkit has been developed to :
+- create Hydra primitives directly without the need to create OpenUSD data or Maya geometry 
+- add custom Hydra filtering scene indices to MayaHydra to modify the Hydra primitives in the viewport
+
+This project shows how to create Hydra mesh primitives directly without the need of importing usd data or create Maya geometry.
+- It creates a grid of cubes which are Hydra mesh primitives, the grid has parameters which can be modified in the Maya node.
+- It shows how to use Hydra instancing as an option for the created cubes.
+- It deals with MayaHydra selection picking so the user can do selection picking on the Hydra cubes in the viewport.
+- It adds a Hydra filtering scene index to MayaHydra that hides mesh primitives that have more vertices than a certain number.
+
diff --git a/lib/mayaHydra/flowViewportAPIExamples/footPrintNode/README b/lib/mayaHydra/flowViewportAPIExamples/footPrintNode/README
@@ -0,0 +1,9 @@
+This is a Flow viewport toolkit example. 
+The Flow viewport toolkit has been developed to :
+- create Hydra primitives directly without the need to create OpenUSD data or Maya geometry 
+- add custom Hydra filtering scene indices to MayaHydra to modify the Hydra primitives in the viewport
+
+This project is similar to the Maya devkit sample named FootPrint node. Except that it doesn't create maya geometry but directly Hydra primitives using the Flow viewport toolkit.
+It also deals with MayaHydra selection picking so the user can do selection picking on the Footprint node in the viewport.
+
+