HYDRA-242 - Edit pass on mayaHydraVsMtoh.md (#388)

HYDRA-242 - Edit pass on mayaHydraVsMtoh.md
and README.md
Rename mayaHydraVsMtoh.md to mayaHydraDetails.md
Plus edits from Martin Chesnay

lib/mayaHydra/README.md

@@ -1,42 +1,43 @@
 # Hydra for Maya (Technology Preview)
 
-_Hydra for Maya_ introduces Hydra as a viewport framework for Maya and it allows extending the viewport render engine through Hydra render delegates. Unlike _MtoH_ it utilizes a new API for efficient translation of Maya or USD data.
-To ensure Autodesk builds the right foundation, this API is subject to change. Because of this _Hydra for Maya_ is currently a Technology Preview and not feature complete. In addition there are also current limitations in the Hydra framework which are under consideration.
+The _Hydra for Maya_ project creates a Maya plugin that replaces the main Maya viewport with a Hydra viewer. _Hydra for Maya_ is developed and maintained by Autodesk. The project and this documentation are a work-in-progress and under active development. The contents of this repository are fully open source and open to contributions under the [Apache license](../../doc/LICENSE.md)!
 
-## What it can do?
-- Use Storm as the default render delegate for Maya's viewport
-- Render and interact with most of Maya's node types
-- Use different render delegates using USD/Hydra's plugin system
-- Natively view USD data with USD Extension for Maya through SceneIndex rather than SceneDelegates
-- Use it side-by-side with Maya's current Viewport 2.0
+Hydra is the rendering API inside [Pixar's USD](http://openusd.org/).
 
-## Maya DAG node scene index registration
+## Motivation
 
-DAG node scene index registration enables the use of custom scene indices for drawing of custom Maya shapes via Hydra prims. Internally, we are using this technology to enable maya-usd with the new Hydra viewport with no dependencies on maya-usd from maya-hydra and vice-versa.
+The goal for _Hydra for Maya_ is to introduce Hydra as an open source viewport framework for Maya to extend the viewport render engine through Hydra render delegates. _Hydra for Maya_ uses the previous Maya to Hydra (MtoH) code, which is part of MayaUSD, as a foundation to build on. You can find more details on what changed from MtoH [here](./doc/mayaHydraDetails.md). _Hydra for Maya_ is currently a Technology Preview; we are just laying the foundation and there is still work ahead. As the plugin evolves and the Hydra technology matures, you can expect changes to API and to face limitations.
 
-The registration code is called on the first, render override frame, when Hydra resources are initialized (MtohRenderOverride::_InitHydraResources). Upon first initialization, or when a node is added, a scene index is created. In the case of MayaUsd the nodes in question are MayaUsdProxyShapeBase. The scene index defined by the MayaUsdProxyShapeMayaNodeSceneIndex simply wraps UsdImagingSceneIndex which knows how to draw Usd data.
+## What can it do?
 
+With the _Hydra for Maya_ plugin, you can:
+
+- Use Storm as the default render delegate for Maya's viewport.
+- Render and interact with most of Maya's node types.
+- Use different render delegates using USD/Hydra's plugin system.
+- Natively view USD data with USD Extension for Maya through HdSceneIndex.
+- Use Hydra side-by-side with Maya's current Viewport 2.0.
 
 ## Current Limitations
-This is a list of known issues and limitations.
-
-- USD stage viewable only. Interactive transform edits are not working with the chosen v22.11 USD release (Fixed by https://github.com/PixarAnimationStudios/USD/commit/9516b96e90).
-- UsdGeomCapsule, UsdGeomCone, UsdGeomCube, UsdGeomCylinder, and UsdGeomSphere are not supported. Use the supported UsdGeomMesh to create such geometries.
-- MaterialX is not supported
-- Basic support for Maya materials (only direct texture inputs)
-- Hypershade nodes are not supported except texture inputs
-- Drawing issues with selection and highlighting
-- Shading differences with Maya's Viewport 2.0
-- Blue Pencil is not supported
-- Screen space effects like depth of field and motion blur are not supported through Storm
-- Following Maya node types are not viewable:
-    - Bifrost
-    - nParticles
-    - Fluid
-- Arnold lights are not supported with Storm
-- Animation Ghosting has wrong shading
 
+The _Hydra for Maya_ plugin has the following isses and limitations:.
+
+- The USD stage is only viewable. Interactive transform edits are not working with the v22.11 USD release (Fixed by https://github.com/PixarAnimationStudios/USD/commit/9516b96e90).
+- UsdGeomCapsule, UsdGeomCone, UsdGeomCube, UsdGeomCylinder, and UsdGeomSphere are not supported. UsdGeomMesh can be used as an alternative.
+- MaterialX is not supported.
+- Only direct texture inputs are supported for Maya materials.
+- Limited support for Maya shader networks.
+- Drawing issues with selection and highlighting.
+- Hydra shading differs from Maya's Viewport 2.0.
+- Blue Pencil is not supported.
+- Screen space effects like depth of field and motion blur are not supported through Storm.
+- The following Maya node types are not viewable:
+  - Bifrost
+  - nParticles
+  - Fluid
+- Arnold lights are not supported with Storm.
+- Animation Ghosting has the wrong shading.
 
 ## Detailed Documentation
 + [Building the mayaHydra.mll plugin](./doc/mayaHydraBuild.md)
-+ [Differences between MayaHydra and Mtoh (Luma Pictures)](./doc/mayaHydraVsMtoh.md)
++ [Technical details of MayaHydra](./doc/mayaHydraDetails.md)

lib/mayaHydra/doc/mayaHydraDetails.md

@@ -0,0 +1,33 @@
+# Introduction to MayaHydra
+
+The _Hydra for Maya_ project builds on the foundation of the Maya to Hydra (MtoH) plugin, contributed by Luma Pictures.  Our goal is to extend this plugin to cover a wider array of use cases, prioritizing performance, robustness, and customizability.
+
+The MayaHydra code is a Maya plugin using the MRenderOverride API. This API binds the plugin to a Maya viewport window, adds an entry in the Renderer menu to activate the plugin, and allows control of overall viewport rendering.
+
+### Maya API Additions
+
+We have begun adding new APIs to Maya to provide efficient access to renderable viewport data.  The experimental MDataServerOperation gives an MRenderOverride plugin like MayaHydra access to Viewport 2.0's internal copy of renderable scene data.  MayaHydra can use this as an option to render data provided by Viewport 2.0, instead of having to reconstruct internal Maya features to match viewport appearance and the behavior of Maya features.
+
+### Data Access and Interpretation
+
+Maya contains many different object types and features that affect how they render.  To try to replicate that rendering, a plugin viewport would have to access the raw data of each object through node attributes and to reimplement the display logic. This makes supporting a wide range of object types and features too costly.
+
+Instead of always extracting state from the raw attributes of a Maya node, the MDataServerOperation API provides an abstract view of things to be rendered via the (pre-existing) MRenderItem API.  A render item is similar to a Hydra RPrim and roughly corresponds to a single traditional 3D "draw call" in OpenGL or DirectX. It is an association of geometry buffers with an index buffer, a primitive type (triangles, lines, points), a shader, and shader parameters (transform matrices, colors, textures, etc.)  The MRenderItem wraps an internal renderable object that VP2 uses internally to draw.
+
+One effect of the MRenderItem approach is that the plugin viewport no longer needs to care about the details of most Maya node types.  For something like a Maya joint node, the original attribute approach involved writing an adapter class that manages all the attributes for the type and its interactions with other DAG objects.  In the MRenderItem approach, the plugin doesn't necessarily need any joint-specific code.  Instead, it receives an MRenderItem with the line geometry and color information, which is enough to render and support selection.  In this way, we leverage the existing Maya viewport code that implements the "business logic" that decides what a joint looks like, while delegating rendering control to the Hydra framework.  Here the Maya internal viewport code functions as a data source, serving primitives to Hydra.
+
+### MRenderItem Method Can be Optional
+
+The MRenderItem approach might not make sense in all circumstances, and can be optional.  The lead case is that mesh geometry buffers might work better using the MFnMesh interface. This is the approach the original MtoH code used. The reason is that the default geometry format that the Maya viewport translation code produces has been triangulated and re-indexed so that all geometry streams share a single index buffer.  But Hydra, and especially Storm, prefer untriangulated face data.  For the simple default case of drawing a mesh, possibly with its full wireframe displayed (and nothing else), the value of the render item system is unclear.  We can bypass the render items and provide raw face data using the MFnMesh extraction method from the original MtoH class HdMayaMeshAdapter, skipping normal buffer generation and re-indexing.  This option is likely to be simpler and more efficient in the default case for meshes.  When MRenderItems are needed for meshes using extra display modes, we can combine those approaches.  We expect animation workflows to fit better with the raw face data approach and modelling workflows to require the MRenderItem approach.  This requires more experimentation to validate these assumptions.
+
+We have the flexibility needed to handle other object types outside the MRenderItem system.  This can also be a customization point for other custom sources of data.
+
+### Integration with MayaUSD and Other Maya Plugin Nodes
+
+The maya-usd plugin provides access to USD data files inside Maya by injecting that data into Maya, for Viewport 2.0 to render.  It extracts that data from USD and tweaks it for compatibility with Maya features via a custom Hydra render delegate.  This method doesn't work when the aim is to draw with Hydra Storm or a different render delegate, so we are exploring new methods to integrate MayaHydra with MayaUSD.  MayaUSD continues to facilitate the USD data source (through the MayaUsdProxyShape Maya node) and the editing of that data.  MayaHydra controls the rendering of that data.
+
+Experimentally, we have separated the two plugins so that they no longer link together.  We use USD's HdSceneIndexPluginRegistry interface to query for a registered HdSceneIndex provider for a Maya node, using a naming convention based on the node type name.  Our hope is that this can also be the entry point for third-party plugins to control the viewport rendering of custom node types (MPxLocatorNode or MPxSurfaceShape) purely through the Hydra API instead of through Maya's various viewport APIs.  This could potentially replace the Maya APIs MPxSubsceneOverride, MPxDrawOverride, and MPxGeometryOverride.  
+
+### Change Notifications
+
+The new MDataServerOperation API provides change notifications that better match the requirements of a viewport.  Without this API, a plugin depends on individual attribute change callback notices, something that scales poorly with large scenes.  Instead of these low-level, fine-grained change notices the MayaHydra plugin can leverage the internal change notification system used by vp2.  This system boils down different attributes into simpler categories that better align with Hydra HdDirtyBits.  This internal change notification system is efficiently and thread-safely integrated with the Maya Evaluation Manager and the EM Caching system.