From f735c098d7f737f26429afdc9bea7caa8c5dc8bb Mon Sep 17 00:00:00 2001 From: Pierre Baillargeon Date: Wed, 3 Aug 2022 14:52:28 -0400 Subject: [PATCH] MAYA-124418 document the Maya ref edit router --- README_DOC.md | 1 + .../translators/mayaReferenceEditRouter.md | 90 +++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 lib/usd/translators/mayaReferenceEditRouter.md diff --git a/README_DOC.md b/README_DOC.md index 63a950e6da..66a77f28b3 100644 --- a/README_DOC.md +++ b/README_DOC.md @@ -12,3 +12,4 @@ + [MaterialX Code Gen](lib/mayaUsd/render/MaterialXGenOgsXml/README.md) + [MayaToHydra](doc/MayaToHydra.md) + [Layer Saving](lib/mayaUsd/nodes/Layer_Saving_Docs.md) ++ [Maya Reference Edit Router](lib/usd/translators/mayaReferenceEditRouter.md) diff --git a/lib/usd/translators/mayaReferenceEditRouter.md b/lib/usd/translators/mayaReferenceEditRouter.md new file mode 100644 index 0000000000..473cd6b2a8 --- /dev/null +++ b/lib/usd/translators/mayaReferenceEditRouter.md @@ -0,0 +1,90 @@ +# Maya Reference Edit Router Documentation + +The Maya USD plugin supports hosting a Maya reference inside the USD scene. +This Maya reference can be edited as Maya data and then cached as USD prims. +The caching process supports customization of its behaviour, even a full +replacement of its logic through an `edit router`. + +This document outlines the API of this `edit router` and what the default +implementation does. + + +## Edit Router Generalities + +The edit router is a callback that receives information in a USD `VtDictionary` +and fills another `VtDictionary` with information about what work it did. + +The interface to declare and register an `edit router` is found in the file +`lib\mayaUsd\utils\editRouter.h`. It declares the `EditRouter` class itself +and functions to register and retrieve an `edit router`. The `edit router` +is registered and retrieved by name. + + +## Maya Reference Edit Router + +The Maya Reference `edit router` is named "mayaReferencePush". The default +implementation found in the file `lib\mayaUsd\utils\editRouter.cpp` as the +function named `cacheMayaReference` does the following: + +- Extract all necessary inputs from the input `VtDictionary`. +- Validate the path of the Maya Reference that was edited. +- Validate the destination layer and destination prim. +- Determine the file format of the USD cache. +- Export the edited Maya data into a USD layer, the USD cache. +- Copy the transform of the root of the Maya data into the Maya Reference. +- Refer to the USD cache either as a reference or payload, optionally + in a variant. +- Fill the output `VtDictionary` with information about the layer and prim. + +We will go into more details about these steps in the following sections. + +### Maya Reference Edit Router Inputs + +The input information received by the Maya Reference `edit router` are: + +- "prim" (std::string): the `SdfPath` of the USD Maya Reference that was edited. +- "defaultUSDFormat" (std::string): the USD file format used to create the cache. +- "rn_layer" (std::string): the file path to the cache. A layer will be created there. +- "rn_primName" (std::string): the name of the root prim of the cache. +- "rn_listEditType" (std::string): how the reference is added: "Append" or "Prepend". +- "rn_payloadOrReference" (std::string): type of ref: "Reference" or "Payload". +- "rn_defineInVariant" (int): if the cache is in a variant. 0 or 1. +- "rn_variantSetName" (std::string): name of the variant set if in a variant. +- "rn_variantName" (std::string): name of the variant in the set, if in a variant. +- "src_stage" (UsdStageRefPtr): the source `UsdStage` to copy the transform. +- "src_layer" (SdfLayerRefPtr): the source `SdfLayer` to copy the transform. +- "src_path" (SdfPath): the source `SdfPath` to copy the transform. +- "dst_stage" (UsdStageRefPtr): the destination `UsdStage` to copy the transform. +- "dst_layer" (SdfLayerRefPtr): the destination `SdfLayer` to copy the transform. +- "dst_path" (SdfPath): the destination `SdfPath` to copy the transform. + +The last six inputs correspond to the parameters received by the Maya Reference +updater `pushCopySpecs` function. That is the function that is calling the +`edit router`. + +### Validation and Export + +The Maya Reference default `edit router` validates various inputs to verify +that the Maya Reference exists and was edited. It then exports the Maya scene +nodes of the Maya Reference file to a USD layer file. That layer file will be +used as the USD cache representing the contents of the Maya Reference. + +### Copy the Transform + +To support that the user might have moved the root of the Maya Reference when +editing as Maya data, the transform of this root is copied to the USD Maya +Reference. This preserve the position of the data. + +### Create the Cache Prim + +The USD cache must be referenced in the USD stage. The `edit router` creates +a reference or payload, possibly in a variant, inside a USD prim. Remember +that the path to that prim was given in "rn_primName". + +### Fill the Output VtDictionary + +The output `VtDictionary` is filled with the following information: + +- "layer" (std::string): the identifier of the cache layer, will be equal to "rn_layer". +- "save_layer" (std::string): "yes" if the layer should be saved. (Calling `Save` on it.) +- "path" (std::string): the `SdfPath` to the prim that contains the cache.