Custom Shapes in the Maya API

A
user-defined surface shape is one of the most complex types of nodes that can
be implemented within Maya. A number of supporting classes are required, and a
number of virtual methods must be properly implemented to get your class
working right with the various parts of Maya. The goal of this article is to
break down the process of creating the shape into manageable chunks, and to
provide details of each step of the process so that you can make good design
decisions as you decide how and what to implement for your custom shape.

We will start by
discussing the motivation for user-defined shapes. And continue step-by-step by
adding the methods used to support drawing, selection, components,
manipulation, history, sets and deformation. At each step we will show the minimum
needed to implement each level of functionality so that you can decide which
level of complexity is appropriate for the particular type of shape you want to
implement. As we add virtual methods to our shape, we will discuss the purpose
and the circumstances under which the methods are called. This paper also
covers some related areas such as deformers, sets (groupParts, groupIds), and
tweaks. See this previous article for more details.

In conjunction
with the post, I have provided a number of example plug-ins. These plug-ins
demonstrate the shape implementation at various stages: draw/select, settable
components, manipulatable components, etc… The shape represented in all of
these plug-ins is extremely simple à a 4-point line segment sometimes
drawn as a hermite curve. The goal of using such a simple, immediately
understandable shape is that we didn’t want the details of the shape type to
obscure details of the implementation of the node itself.

MPxLocatorNode vs. MPxSurfaceShape

Two classes
can be used to implement a shape within Maya. The most basic is the
MPxLocatorNode class. If your shape needs to support only drawing and
selection, it is best to derive from the MPxLocatorNode class. The
MPxLocatorNode class is derived from the same nodes as Maya’s internal locator
(crosshair) node.

The Maya
Developer’s Toolkit includes an example MPxLocatorNode called
footPrintNode.cpp. This example shows that deriving from MPxLocatorNode is
quite straightforward. Typically, the only virtual methods that need to be
overridden are:

• MPxLocatorNode::draw()
• MPxLocatorNode::boundingBox()
• MPxLocatorNode::isBounded()

The draw
implementation typically would contain OpenGL calls to draw the shape. The
boundingBox and isBounded methods allow Maya to determine whether or not your
object is within the camera’s view. When the object is not within the view, the
draw method will not be invoked.

Selection of
nodes derived from MPxLocatorNode works automatically based on the
implementation of the above three routines. When the mouse click/drag falls
within the bounding box returned by your shape, Maya invokes the draw method
using OpenGL selection to determine whether the shape has been selected.

If you want
your shape to include any of the following, more advanced capabilities, you
must instead derive from MPxSurfaceShape:

• Component
  selection or manipulation
• History
  operations
• Sets
• Deformers

Introduction to MPxSurfaceShape

As a learning
tool, we begin our look at the MPxSurfaceShape class by implementing the same
functionality as an MPxLocatorNode using the MPxSurfaceShape class. In other
words, this section covers what is needed to implement drawing and selection
without components for an MPxSurfaceShape.

An example plug-in implementing
this level of functionality has been provided with the post in the folder
called curveDrawSel. This example plug-in simply draws a
non-editable 4-point line segment, and is extremely similar to the
footPrintNode in its capabilities.

The
Developer’s Toolkit for Maya has an example MPxSurfaceShape example plug-in
called apiMeshShape. One improvement to note in the curveDrawSel plug-in over
the apiMeshShape is that we use OpenGL selection rather than simply saying that
the shape is selected any time a selection occurs within its bounding box.

The UI class: MPxSurfaceShapeUI

An MPxSurfaceShape cannot be
implemented as a single class in isolation. Instead, for any MPxSurfaceShape
that is implemented, a corresponding MPxSurfaceShapeUI class must also be
implemented. The duties of the UI class are drawing and selection. The
MPxSurfaceShape node class performs all other shape-related operations.

The MPxSurfaceShapeUI
methods that must be implemented are:

• MPxSurfaceShapeUI::getDrawRequests()
• MPxSurfaceShapeUI::draw()
• MPxSurfaceShapeUI::select()

Maya documentation covers
the motivation and usage of these methods, and can be found under Developer
Resources: API Guide -> Shapes -> Drawing and Refresh.

The shape node class: MPxSurfaceShape

Now that the
UI class is handling drawing and selection, the only required methods within
MPxSurfaceShape are:

• MPxSurfaceShape::boundingBox()
• MPxSurfaceShape::isBounded()

These methods
are called by Maya to determine whether or not to invoke your node’s selection
and drawing methods based on the view frustum of the camera.

Summary

If you simply
want a shape to draw itself and be selectable, use the MPxLocatorShape as your
base class. Doing the same thing with the surfaceShape class wasn’t a whole lot
more difficult, but we had to use 2 classes instead of one, and we had to
implement 2 new methods (select and getDrawRequests) to implement functionality
that is handled automatically for the locator shape.

On the plus
side, we have more flexibility. If we wanted to do some alternative tricky
implementation of select rather than OpenGL select, the surfaceShape class does
allow this sort of customization while the locatorShape does not. But the main
reason to derive from MPxSurfaceShape is so that we can expand our shape to add
component handling.

Component Handling

In this
section, we add basic component handling to the shape. The example plug-in for
this section is provided in the folder called compCurveDrawSel.
Here we add support for customizing the shape of the curve by specifying the
component locations using the setAttr command. We do not yet allow the user to
select or move the components, only to specify their locations using setAttr or
connections.

The component attribute

The first
decision to be made is how we want to represent the components within the node.
In this example, like the existing apiMeshShape.cpp example, we will store the
components in the same attribute as some existing Maya shapes: the
“controlPoints” attribute. The controlPoints attribute is inherited from the
“controlPoint” node type – one of the base classes of MPxSurfaceShape. The
controlPoint node is also a base class of Maya’s nurbsSurface, mesh,
subdivSurface, nurbsCurve and lattice shapes. The nurbsSurface, nurbsCurve and
lattice types all make use of the “controlPoints” attribute. Meshes use their
own attribute to store vertices because of an architectural decision to use
floating point rather than double storage.

 

Attribute documentation from the
controlPoint node’s controlPoints attribute.

The reason
for storing the control points in an attribute is threefold. First, because the
individual xyz components are numeric attributes, the attribute can be animated
and connected to other numeric attributes. Second, the Maya file format is
organized around attributes, and the controlPoints attribute data is saved to
file. The third reason is simply consistency. All the other shape nodes within
Maya store their points in a similar manner.

Internal shape data

We could
implement our shape by storing the controlPoint data solely in the datablock of
the plug-in node. The setAttr and getAttr commands will get and set data
directly into the datablock by default. If we did store the data solely in the
datablock, each time the draw method asked for the points, our code would use
an MArrayDataHandle to get the value of the controlPoints attribute from the
MDataBlock. For such a small shape as the curve in our example plug-in, these
operations would not be very expensive. However for a large shape with many
controlPoints, accessing points from the MArrayDataHandle class can be rather
tedious.

In addition,
many shapes have more information per component than solely the position. You
may want to store per-vertex tangency or connectivity information. For this
reason, many shapes within Maya choose to store their control point position
data separately from the datablock (for example in a geometry data attribute or
in an internal class member).

We chose to
store our shape data as an internal member of the node class. At this stage of
our example, our shape data can consist simply of an MPointArray. We call it
fCurvePoints and store it as a member of our node class.

setInternalValue

In order to
transfer the values that the user sets or connects to the controlPoints
attribute into our MPointArray class member, we implement the virtual method setInternalValue.
We take the data passed in and place it into our internal array. We also call

MPxSurfaceShape::setInternalValue (plug, handle);

from our
override of setInternalValue. This call puts the controlPoint
data into the node’s datablock in addition to storing it in our MPointArray
class, and means that we do not need to implement getInternalValue. Instead, if
anyone (such as the getAttr command) asks for the value of the controlPoints
attribute, it will be handled by the DG, and will retrieve the value from the
datablock. Alternatively, if storage space was an issue, we would not need to
place the controlPoints into the datablock at all. In this case, we would
implement getInternalValue to retrieve and return the appropriate value from
our internal MPointArray.

One other
detail is necessary to keep our shape on screen up-to-date when the
controlPoints attribute is keyed (or is given some other input connection). We
need to change the method called from our UI class to retrieve the points. We
add the 2 lines shown below in bold:

void compCurveDrawSel::points(MPointArray points) {
MDataBlock block =forceCache ();
block.inputArrayValue (mControlPoints);
points.setLength (sCurvePointCount);
for (unsigned ii =0; ii < sCurvePointCount; ii++)
points.set (fCurvePoints [ii], ii);
}

This is only
necessary when there is an input connection to the controlPoints attribute
because of how dirty propagation and evaluation work within Maya. In other
words, when the user does a “setAttr” MEL command on the controlPoints
attribute, the data will be set immediately into the node and setInternalValue will be called. However, when there is
a connection to the controlPoints attribute, our node will be marked dirty
dirty, but setInternalValue does not get called unless our node
asks for the controlPoints value. When the controlPoints value is requested, it
will be dirty and will trigger evaluation of the connection. The addition of
the above 2 lines to the points method accomplishes the evaluation, and will
cause setInternalValue to be invoked, thereby updating the
fCurvePoints to the proper value.

The bounding box, an optional performance improvement

Our shape is
now controllable by the user, so its bounding box is variable. That means we
need to improve our bounding box handling. The boundingBox
method is called quite frequently — each time the window refreshes. Therefore,
we don’t want to have an expensive calculation inside the boundingBox method.

To address
this, we will add 2 attributes to our shape representing the 2 corners of the
bounding box. We make these attributes affected by the controlPoints attributes
so that they will be marked dirty when the controlPoints are modified. These
are output attributes, so we implement a compute method that calculates the boundingBox based on the location of the controlPoints.

Now, when the
boundingBox method is called, it retrieves the
bounding corners from the datablock of the node. If the bounding corners are
not dirty, this is a very fast operation that simply references into the
datablock. If the corners are dirty, compute will be invoked to recalculate and
set the bounding box.

Summary

In this
section, we simply added support for user-settable and animatable control point
locations. We didn’t have to change our UI class at all. However, we did end up
implementing 2 new virtual methods (setInternalValue
and compute) and adding attributes to our node to improve the performance
of our bounding box calculation.

Manipulation of components

In this
section, we will add the ability to select and move individual components or
sets of components using both the manipulator and the move/rotate/scale
commands. The example plug-in demonstrating this additional capability is in
the folder called compCurveMovable.

Adding
support for component motion is a lot of work. This section covers the methods
and the additional class required, their purpose and when they are called from
Maya.

The transformUsing() method

The transformUsing method is called from the transformation MEL commands
such as move, rotate and scale. It is also called from the transform-related
manipulators such as translate, rotate and scale manips.

virtual void transformUsing (
const MMatrix& mat,
const MObjectArray& componentList,
MVertexCachingMode cachingMode,
MPointArray* pointCache
);

Part of the
complexity of the transformUsing method is related to undo. The transformUsing method is called during both the original transform
command and during undo. During the initial command, the cachingMode will be
set to “save”. In undo, the cachingMode will be restored.

During
manipulator use, the cachingMode will be set to “save” initially, and “update”
subsequently. Undo of manipulations will have the cachingMode set to “restore”.
These settings can be better understood if we consider the motivation. Imagine
the user starts moving an object using the translate manipulator. In a single
mouse drag, the screen will refresh multiple times and the object will be
transformed in small increments by the many calls to transformUsing method. If the user then hits “Undo”, Maya wants to
restore the object to its original location in one operation, not multiple
calls to the transformUsing method. 

One thing to
note about our implementation of the transformUsing method is that we have implemented it
to transfer the motions directly into our class’s internal shape data
(fCurvePoints). One by-product of this is that it is now possible for our
internal data to be out of sync with the controlPoints attribute. The
manipulator links itself to the controlPoints attribute, and it needs to be
able to query the controlPoints attribute for the proper location of the point.
Therefore, we need to implement getInternalValue for our node.

The getInternalValue() method

Typically
you’ll implement getInternalValue for your node at the same time as you
implement setInternalValue. In the last chapter, we explained
why we were able to avoid implementing getInternalValue. Now there is no way to avoid it.
With the addition of transformation support, getInternalValue
is required to keep our node working right. The reason is that since transformUsing does not go through setInternalValue,
the transformation data never goes into the datablock. We implement getInternalValue so that it returns the requested
values from our internal fCurvePoints into the supplied handle argument.

The componentToPlugs() method

When a
transform manipulator is used on selected components, they call the componentToPlugs method to learn which plugs on your
shape node correspond to the selected components. The manipulator will query
these attribute values when it is determining where to draw itself.

This method is
also called when a command such as the setKeyframe command needs to determine
where to connect new animationCurves when a selected component is keyframed.

Iterator Support

Manipulators
in Maya require iterator support on shapes. This means that you need to add an
additional class, derived from MPxGeometryIterator. The following three virtual
methods also need to be added:

• geometryIteratorSetup
• acceptsGeometryIterator(bool)
• acceptsGeometryIterator(MObject&,
  bool, bool)

If you are
writing multiple user-defined shapes, you may well be able to share the same
iterator class amongst your shapes, although that will depend somewhat on how
you store the data within your shape class. If each shape has a very unique
data structure, it will probably make more sense to have a separate iterator
for each type of data.

How you
design your iterator will depend on your class itself, and what it needs to
support. As the seminar continues, we will be enhancing the iterator. For this
example, it is satisfactory to simply make the iterator store a pointer to our
shape, and loop through the shape’s points. The primary thing to consider when
writing your iterator is that it should not rely on any data that could be
destructed while the iterator is using it. For example, if geometryIteratorSetup is invoked with readOnly = false,
then you can expect the setPoint method to be called more than once.
Be sure that nothing in your implementation of setPoint
could cause the data held onto by the iterator to become stale.

The UI Class

The UI class
needs to be enhanced to support drawing and selection of the individual
components separately from the shape itself. This means expanding the getDrawRequests implementation to handle the case where the 2^nd
argument (objectAndActiveOnly) is false.

void compCurveMovableUI::getDrawRequests (
const MDrawInfo & info,
bool objectAndActiveOnly,
MDrawRequestQueue & queue
);

When
objectAndActiveOnly is false, we will create and add an additional drawRequest
to the queue corresponding to the point components of our shape. If any of our
components are active, we also create a drawRequest for them.

When
components are drawn, our draw method will now get called more than once. We
modify our draw method to use the MDrawRequest::token() method to determine what should be
drawn.

When the user
selects in component mode, our select method needs to be able to handle it. In
component select mode, our shape will be hilited, and we use this as a cue to
determine whether or not to check for selected points.

The matchComponent method

Having
implemented all of the above, your node already supports the selection tool and
the transformation manipulators. But what if you manually enter the select or
move command and pass it a string that corresponds to your vertices?  The matchComponent method is used by Maya to create a
component corresponding to a string typed in by the user.

Simple History Support

The next
modification we will make to our shape is to support “simple” history. By
simple history, what we mean is that we are going to modify our shape so that
any node that outputs a data of type “vectorArray” can be provided as input to
our node. The figure below shows an example where we’ve connected the
particleShape’s position attribute into our curve node’s inputSurface
attribute.

The particleShape position drives the
location of the curve’s points.

By referring
to this as “simple” history, we are distinguishing it from more advanced types
of history covered in the next chapter such as deformer support and support for
component sets with history (groupParts nodes).

Two forms of input: history and tweaks

The trickiest
part of basic history support on a shape is that there are now two sources of
input for the position of the shape’s components.  Positions may be coming from the history
attribute.  In addition, the user can
make “tweaks” to the points, i.e. select and move them around or animate their
position. This data comes in as before, through the controlPoints attribute. As
a node designer, you must make a decision how you want to combine the history
data with the tweak data. 

In writing
this example shape, we chose to implement tweak handling in the same manner as
Maya’s internal shapes (nurbs, meshes, subds, lattices). These nodes all treat
tweaks as relative when the shape has history, and absolute when
the shape does not have history. The benefit of this approach is that the
tweaks made by the user can be combined with the input history even when the
history is animated.

 

Adding tweaks on sphere: radius=1              Modifying history: radius=1.5

An
alternative approach would be to store the tweaks as absolute, regardless of
whether the shape has history. However, that would mean that when the history
changed, the tweaked points would need to either:

• lose
  their tweaks to follow the history, or
• stay
  at the position defined by the tweaks, ignoring the new history

Keep in mind that tweaks can be animated/connected
as well, so resetting the tweak attribute values on the fly as the history
changes is not really an option unless you want to prevent connections to them
when there is history. In the long run, how you implement your shape depends on
what you are trying to accomplish.

Shape Input Data

Thus far in
our example plug-ins, we have stored the shape data as a simple type,
MPointArray. In continuing this example, adding support for history might seem
like the appropriate time to switch our data to a more complex type, derived
from MPxGeometryData. Indeed, if we want to support component sets and
deformers, we must store our geometry data as an MPxGeometryData type. However,
at this stage in the example, we want to demonstrate the use of internal Maya
data types as the history attribute, so we will continue storing our data as an
MPointArray, and define our inputSurface attribute to accept data of type
MFnData::kVectorArray.

The example plug-in

The example
plug-in for this chapter is in the folder called compCurveSimpHist.
There is a MEL script in the folder called compCurveSimpSetup.mel which creates
the curve and attaches it to a particle shape. If you run the setup MEL script
and push play, you can see the curve points move along with the particles. You
can select points on the curve and tweak them to see how the tweaks interact
with the history.

Adding the input surface attribute

The most
obvious requirement is that we now need an input surface attribute. As
mentioned before, we are using an input data type of MFnData::kVectorArray for
the inputSurface. The inputSurface affects the boundingBox, and we will make it
an internal attribute, so that any time we evaluate it, we can transfer the
values from the input data into a local data member we’ll call fInputPoints.

When we add
the input attribute, it is also useful to override the virtual method:

MObject compCurveSimpHist::localShapeInAttr() const;

This method
is called from a number of places such as:

• the attribute editor, when it
  builds its related node tabs
• the channel box when it builds
  its “Inputs” list
• the delete construction history
  operation (delete –ch MEL command)

Handling relative vs. absolute tweaks

The other
primary job to be done to support history is to put in our history-dependent
handling for tweaks.

Internal
Data

Our previous
implementation of the shape had only one piece of internal data: the curve
points in absolute space. Now we will instead store 2 pieces of data:

• fCurvePoints (the history plus
  the tweaks)
• fInputPoints (the history)

We could
store a third array with the tweaks, but instead we will store the tweak data
directly in the datablock. There is no obvious advantage or disadvantage to
storing it in the datablock, but it does serve as an example of a different way
to store the data. You can decide how you want to store the tweaks in your own
node.

setInternalValue
and
getInternalValue

We modify
these virtual methods. They already had handling for the controlPoints
attribute, but we modify them so that when the shape has history, the data will
go directly to the datablock.

transformUsing

We implemented
transformUsing in the previous chapter. Its
responsibility is to tranfer motion from transform commands/manips into the
shape, and it bypasses setInternalValue. Since we are storing our tweaks in
the datablock when there is history, we need a way to transfer the motion from transformUsing into the datablock. We add a utility method called
updateControlPoints to do this, and call it from transformUsing
when there is history.

Getting the points for drawing/boundingBox

When we are
asked for the bounding box or need to draw the points, we want to make sure we
always have the most up-to-date representation of them. We add the lines shown
below to our boundingBox method and our points
method:

if (fHasHistory) {
block.inputValue (inputSurface);
applyTweaks (block);
}

If the
history has changed, inputSurface will be dirty, and the call to inputValue
will invoke evaluation and a call to setInternalValue to make sure our fInputPoints are
up-to-date. The applyTweaks method will then add all of the tweaks
from the datablock to the fInputPoints.

The mHasHistoryOnCreateAttribute

One of the
attributes we inherit from the base class is the “mHasHistoryOnCreate”
attribute. This is an internal attribute which you can use to your advantage if
you want to know during file IO whether your shape will have history or not.
This is useful because during file IO, connectAttrs always come after setAttrs.
So when setInternalValue gets called for the controlPoints
attribute and you want to have different handling for history vs. non-history,
you can’t simply look for the connection to see if the shape has history or
not. By implementing setInternalValue and getInternalValue
for “mHasHistoryOnCreate” we are able to know during file IO whether there will
be history on our shape.

Because there
are several places in our node where we want to know whether or not there is
history, we also add overrides of the virtual methods

• connectionMade
• connectionBroken

This allows
us to set a boolean flag indicating whether or not there is history. This way
of storing whether there is history is optional, but checking this flag is
quite a bit more efficient than checking for input connections to the
inputSurface attribute.

Summary

Until now,
all of our previous examples have been fairly cut and dry. If you wanted to
make a user-defined shape with movable components, you basically have to follow
the basic plan outlined in chapters II-V. Where the creativity and design on
your part really starts coming into play is when you start adding support for
history. The implementation presented here is one way to go, and closely mimics
how shapes inside of Maya are implemented.

Deformer Support – Background Info

The term
deformer refers to any type of node derived from the base class “geometryFilter”.
Examples of deformers are lattices, clusters, nonlinears, and MPxDeformerNodes.
When you add a deformer to a shape, a number of things happen:

• The shape is copied. This copy of
  the shape is called the “intermediate object” and is placed in the history
  of the shape. (Subsequent deformers will reuse the existing intermediate
  object. New copies will not be added.)
• a set gets created to store the
  components affected by the deformer
• a tweak node is created to store
  subsequent tweaks made to the shape
• the deformer node and any related
  auxiliary objects are created

A typical
dependency graph set-up including deformers is shown below:

 

Hypergraph view of deformers in
the history of a shape

At the far
right, pSphereShape is the deformed shape node. At the far left,
pSphereShapeOrig is the intermediate object. The intermediate object is
typically hidden (unless you disable its intermediateObject attribute), and is
at the head of every chain of deformers. It serves as a storage place for the
original undeformed positions of the shape.

In a typical
deformer chain, shape data flows out of the intermediate object and then flows
through each of the deformers. In this example, the deformers that are
traversed are tweak1, cluster1 and ffd1. In this example, only a single shape
flows through ffd1. However, most deformers can operate on any number of shapes
since the input and output geometry attributes of the deformer base class are
multis. The two exceptions to this rule are skinClusters and the wrap node.
Because of implementation details, the skinCluster and the wrap node can
operate on only a single geometry. Additional geometries connected to the
skinCluster and the wrap will be ignored.

Sets on shapes with history

Each deformer
is associated with a single set. It will deform only the points that are
included in its set. If you add points to a deformers using the sets command,
the deformer will automatically be wired up to the construction history of the
shape. Similarly, if you remove points from a set, the deformer will stop
acting upon those points.

Most sets in
Maya are composed of only a single node: the objectSet node. However, component
sets in Maya are different. Component sets are stored within the shape data
rather than within the objectSet node. The set is connected to a groupId node
per shape, and a groupParts node per “construction-historied”
shape.  If you look at the history of a
shape in the hypergraph, by default Maya will hide the groupParts and the groupId
because they clutter the view and are not of interest. If you turn on display
of “auxiliary nodes”, the groupParts and groupId will be drawn.

Hypergraph view showing the groupParts, groupId and objectSet node for an ffd
deformer. Note that the tweak node was deleted from this shape’s history in order
to make the figure less cluttered.

The groupId
node is simply a means of storing an id that is unique within the scene for
fast look-up of the membership of the set within the shape’s list of sets.

The
groupParts node stores component sets for shapes with construction history.
This is because as the shape data flows through the history, it may change its
numbering. Component lists are stored using the vertex index and some
construction history nodes modify the vertex numbering – for example, “polySplit”,
“deleteComponent”, etc. Because the groupParts is in the construction
history, it remains immune to the vertex numbering changes. It receives the
shape data before the vertices are renumbered. This architecture has proved
useful for certain poly modeling operations.

Tweak Nodes

A tweak is
the name given to translations of vertices on shapes in Maya. Shapes without
construction history are able to add tweak deltas directly into their vertex
position data. However, shapes with construction history need to store the
tweaks as deltas that get added to the shape data coming in through the history
attribute.

When a
deformer is added to a shape in Maya, we do lot of work to prevent tweaks from
existing on the shape. Why? In the previous chapter, we discussed how shapes
store tweaks as relative moves which get added to the history. The example
below shows how such a relative tweak would get added into a smooth skinned
surface.

  
Left: Salty the seal’s
initial state.
Middle: Salty’s nose was
tweaked (think Pinocchio).
Right: The neck joint is
rotated, causing the skin to deform. The tweak does not get deformed since is
added after the deformation.

In the above
picture (left), the user has skinned the seal shape to a skeleton so that
rotating the various joints creates a smooth skinning deformation. In a later
plot twist, Salty is beset by a strange Pinocchio-like spell. The user needed
to make Salty’s nose grow, and accomplished this by translating a few vertices
over in X. For this example, there is no tweak node, so the vertex deltas are
stored on the shape node. It all looks ok until we rotate the neck. Now since
the tweaks get added after the skinning deformation, the deltas move the nose
vertices over in X even though Salty’s nose is no longer aligned with the
X-axis.  In order for Salty to rotate his
head successfully, we need the skinning algorithm to act on Salty’s tweaked
nose, instead of having the tweaks act on Salty’s skinned nose.

To address
this issue, whenever there are deformers in the history of a shape, a tweak
deformer is created automatically and inserted at the front of the deformer
chain. If the shape being deformed had existing tweaks or animated CVs, the
tweaks & animation are moved onto the tweak node. Otherwise, the tweak node
is left empty until the user grabs some cvs and moves them (or keys them). New
tweaks are also added to the tweak node (unless the user manually deletes it,
in which case we revert to the old behavior).

Deformer Support – Implementation

In this
section, we’ll present the changes necessary to upgrade our example plug-in so
that it will support deformers. The example code referred to here is in the
directory called compCurveDeformable. To try out this shape, use
the MEL script compCurveDefSetup to create this shape. Then add some deformers
to your shape, and move some vertices around.

Geometry Data

In order to
support either sets or deformers, it is necessary for the shape-related
attributes on the shape to be geometry data. You could use one of Maya’s
internal geometry data types, such as mesh data. Or you can write your own type
of geometry data derived from MPxGeometryData. For the purposes of this
example, we created our own data type, compCurveData. The data itself contains
a simple MPointArray. When implementing your own type of data, you need to
implement a number of virtual methods to support file io, geometry iteration
over the data, copy, and set creation.

Inside our
example plug-in, you will see that we have gotten rid of all of our internal
data (fInputPoints and fCurvePoints). We are now storing all of our data in the
datablock in the geometry attributes described next.

The change
from storing the data internally as a class member to storing it in a data type
required a lot of small changes to the code. Basically every place where we
were using fInputPoints, we now use the point array that is stored in the data
for the input shape. Every place where we were using fCurvePoints, we now use
the point array stored in the data for the cached shape.

Geometry Attributes

Any
deformable geometry requires at a minimum the following three attributes:

• input shape
• cached shape
• local output shape
• world output shape

The input
shape is where history gets connected into your node, as in the previous
example. The cached shape is the input shape plus the tweaks – generally
treated to be your node’s private storage place. The local and world output
shape attributes give other nodes the ability to connect downstream from your
shape’s data. The world output shape simply bundles the world matrix of the
shape with the local shape data. The shape data itself is still in local space.

Geometry Attribute Overrides

4 virtual
methods should be implemented to return the attributes corresponding to the
above 4 attributes:

• localShapeInAttr
• cachedAttr
• localShapeOutAttr
• worldShapeOutAttr

Of these
attributes, 2 are outputs and required us to add to our existing override of
the compute method to handle our 2 new outputs.

These
attributes are used in commands that want to know about history/future shape
attributes on your node. For example, the listHistory command will utilize
these methods to find the history or future (listHistory –future) of your node.
When a deformer is attached to a shape, it connects to the attribute returned
by the worldShapeOutAttr of the intermediate object and to the
localShapeInAttr of the deformed object.

Overrides required for set support

Three methods
must be added to our shape to support the creation of sets of our components:

• match: This method is used by the set creation code to
  determine whether the selected component type is valid for inclusion in a
  vertex-restricted sets. Since deformer sets must be vertex-restricted,
  your shape must override match to specify that its control point
  components satisfy the vertex restriction.
• createFullVertexGroup: This method is used by the set
  creation code when it wants to create a set containing all of the control
  points in the entire shape. An example of when this would occur is if you
  select your shape as an object (rather than as in component-mode), and
  create a deformer. The deformer’s set would contain all of the vertex
  components of your shape as defined by the createFullVertexGroup method
  implementation.
• geometryData: This method is used by the set
  creation and editing code to access the geometry data. Set information for
  components is stored with the geometryData.

Tweak node support

You must
override the tweakUsing method to support movement of
controlPoints on shapes with tweak nodes in their history. The tweakUsing method is fairly similar to the transformUsing method, but it allows the tweaks to be transferred to
the tweak node rather than directly into the shape data itself.

Conclusion

Writing a
custom shapes is not trivial. However, if you start simple, and then add more
details, it’s not so difficult. We recomment that you build up your custom
shape piece by piece and get each part of it solid before you proceed to the
next. Hopefully the example plug-ins and material presented in this article will
provide a good starting point for this process.