|
AL_USDMaya
0.29.4
USD to Maya Bridge
|
|
AL_USDMaya
0.29.4
USD to Maya Bridge
|
The plug-in translator system that is the core of AL_USDMaya provides a number of ways to integrate USD with existing maya nodes (including custom Maya plug-ins). Any particular type can be integrated in one (or all) of these ways:
File Import File Export Importing as part of an AL_usdmaya_ProxyShape Handling the changes to a AL_usdmaya_ProxyShape as a result of a variant switch
The API for defining your own plug-in translator may at first seems a little convoluted (especially if you were expecting to override a pair of import/export methods), however this API has evolved over time to ensure it works correctly with live variant switches, prim activation/de-activation, and a number of other live changes to the underlying USD scene.
To try to explain how this all works, let's start of with an extremely silly plug-in example that will create a custom translator plugin to represent a polygon cube node in Maya.
PolyCubeNodeTranslator.h*
As an absolute minimum, you'll need to implement the update and tearDown methods. The following is an explanation of what those methods do, and how to implement them correctly.
General Setup
PolyCubeNodeTranslator.cpp*
initialize
The initialize method is a one time initialisation step for your translator plug-in. Now we all want to ensure our plug-ins operate as quickly as possible right? So the initialize step is really to help improve the performance when accessing data via MPlugs (i.e. Ideally we don't want to be accessing MPlugs by constantly calling findPlug("someString"))
needsTransformParent
One function you may want to overload is the needsTransformParent() function.
If your node is a DAG node (i.e. a shape or custom transform), it will need to have a transform created for it, so return true in this case. If however you node is a simple DG node (e.g. surface shader, texture etc), then you should return false from this method.
If you return true, a new transform will be generated within Maya to which you can parent your shape on creation. If you return false, no transform will be generated.
import
The Import method should only really be used to create the Maya nodes that will represent your custom prim. Now there is a small caveat to this. If the contents of your prim does not have any relationships to other prims in the stage, then you may as well do all of the setup you need within Import.
This example will create a simple polyCubeCreator node, a mesh, and connect them together. To do this will not require information from any other prim (for example, if there was another prim that contained a surface material, or a mesh deformation, then there would be a second step involved here to make those relationships in the Maya DG).
Post Import
Having generated all of the nodes you need to, you might end up needing to hook those nodes to other prims. This is admittedly a bit of a bad example (because in this case the node connections could have all been made within import itself).
However, in cases where the scene involves relationships between prims (e.g. one prim is a material, the other is the shape), it won't be possible to make those connections within import (because the other Maya node may not have been created yet). In those cases, you will need to make use of the postImport method to perform the connection of the maya nodes to other prims.
Variant Switching
If you've only supported the methods previously discussed, then your custom prim type should now be imported when you load a usd scene with the proxy shape.
If however you want to be able to respond to variant switches, and swap in or out nodes as a result, there is a little bit more work to do.
When a variant is switched, the proxy shape intercepts an event generated by USD that indicates that a variant is about to switch on a specific prim. At this point, the AL maya plugin will traverse the hierarchy under the prim on which the variant switched, and call a preTearDown() method. This method can be used to copy any values from your maya nodes into a layer within the usd stage.
After the variant switch has occurred, the AL USD plugin will do a quick sanity check comparing the prims that were there previously, and the ones that are there now.
For each prim, if a corresponding prim still exists after the variant switch, AND the prim type is the same, then it call an update() method on your translator. Adding this method is optional, however it can improve the speed of a variant switch, so it is recommended!
If you wish to provide an update method to your translator, you will first need to opt in to this mechanism. By returning true from supportsUpdate (by default it returns false), you will now be able to provide a slightly quicker way for handling prims that do not change as a result of the switch. If however you return false here, your node will always be destroyed (via tear down), before being re-imported.
Once you have notified AL usd maya that your translator can update, simply provide your update function (which should simply copy the values from the prim and onto the maya nodes you previously created)
Now the eagle eyed reader may notice that the above function looks very similar to the import() function we initially wrote. To save yourself from a boiler plate code explosion, one option would be to simply call update from import:
Now, if the variant switch results in the prim type changing, or the prim being removed, then a final method will be called, which is tearDown. The simplest implementation of this method is the following:
In most cases that is probably enough. In some cases however, there may be times when you need to ensure the nodes are deleted in a specific order, or you have some other book keeping exercise to perform. Feel free to do so here!
It should be noted that whilst preTearDown and update are optional, tearDown is NOT. You must implement this method in order to support variant switching!
Importable by Default
When a USD file is imported into a proxy shape node, if you always want that node to be imported immediately, then you should return true from the importableByDefault method (which is the default). This will cause the translator to be run as soon as the matching prim type has been encountered. In some cases, you might not want those prims to be immediately imported. One example of this is with mesh data.
If you are importing a very geometry heavy scene with a large number of dense meshes, you would want to keep those meshes within USD/Hydra for as long as possible for performance reasons. If you return false from importableByDefault, then that particular node type can only be manually imported by calling the AL_usdmaya_TranslatePrim command. This means that importing and displaying the data will be quick by default, however if you need to make modifications to that particular prim, you'll be able to selectively import the data when needed.
canExport
If you wish to provide support for the standard file export operations (e.g. export some Maya data as a USD file), then there is a two step process you need to adhere to. The first step is to determine whether this translator can handle the export of a given Maya node, and the second step is to implement the actual export of that data.
exportObject
Finally, if the object can be exported by your translator, and it is the best translator available, then AL_USDMaya will call the exportObject method to export the data into USD. It's worth noting that the preTearDown and exportObject methods are likely to share a significant amount of code, hence the reason for utilising a common 'writeEdits' method.
1.8.7 
