Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes

MPxSurfaceShape Class Reference

This reference page is linked to from the following overview topics: Parent class descriptions, Shapes in Maya, Shape classes, Writing a shape, Components, Marking Menus.


Search for all occurrences

Detailed Description

Parent class of all user defined shapes.

MPxSurfaceShape is the parent class of all user defined shapes. User defined shapes are dependency nodes (and DAG nodes) which contain overridable drawing, selection, and component methods.

This class can be used to implement new kinds of shapes within Maya that can have selectable/manipulatable components and behave in a similar manner to the default shapes in maya.

The UI dependent aspects of the shape should be implemented in a class derived from MPxSurfaceShapeUI. This includes the drawing and interactive selection of the shape and any components that the shape implements.

Examples:

apiMeshShape.h, apiMeshShapeUI.cpp, and quadricShape.cpp.

#include <MPxSurfaceShape.h>

Inheritance diagram for MPxSurfaceShape:
Inheritance graph
[legend]

List of all members.

Public Types

enum   MVertexCachingMode { kNoPointCaching, kSavePoints, kRestorePoints, kUpdatePoints }
 

Vertex caching modes.

More...
enum   MVertexOffsetMode { kNormal, kUTangent, kVTangent, kUVNTriad }
 

Vertex offset modes.

More...
enum   MatchResult {
  kMatchOk, kMatchNone, kMatchTooMany, kMatchInvalidName,
  kMatchInvalidAttribute, kMatchInvalidAttributeIndex, kMatchInvalidAttributeRange, kMatchInvalidAttributeDim
}
 

Return values for the matchComponent() method.

More...
enum   MChildChanged { kObjectChanged, kBoundingBoxChanged }
 

Scope of change.

More...

Public Member Functions

  MPxSurfaceShape ()
  Class constructor.
virtual  ~MPxSurfaceShape ()
  Class destructor.
virtual MPxNode::Type  type () const
  Returns the type of node that this is.
virtual bool  isBounded () const
  This method should be overridden to return true if the user supplies a bounding box routine.
virtual MBoundingBox  boundingBox () const
  This method should be overridden to return a bounding box for the shape.
virtual void  transformUsing (const MMatrix &mat, const MObjectArray &componentList)
  Transform the given components using the specified transformation matrix.
virtual void  transformUsing (const MMatrix &mat, const MObjectArray &componentList, MVertexCachingMode cachingMode, MPointArray *pointCache)
  Transform the given components using the specified transformation matrix.
virtual void  tweakUsing (const MMatrix &mat, const MObjectArray &componentList, MVertexCachingMode cachingMode, MPointArray *pointCache, MArrayDataHandle &handle)
  Transform the given components using the specified transformation matrix.
bool  convertToTweakNodePlug (MPlug &plug) const
  Check if a tweak node is connected to this node.
virtual bool  vertexOffsetDirection (MObject &component, MVectorArray &direction, MVertexOffsetMode mode, bool normalize)
  This method should be overridden if the shape supports components that can be moved in the direction of the normal or UV's using the move vertex normal tool.
virtual MObject  newControlPointComponent () const
  The default action of this method is to return an MFnSingleIndexedComponent (of type MFn::kMeshVertComponent) in order to support rigid skinning binds.
virtual void  componentToPlugs (MObject &component, MSelectionList &selectionList) const
  Converts the given component into a selection list of plugs.
virtual bool  match (const MSelectionMask &mask, const MObjectArray &componentList) const
  This method is used to check for matches between a selection type (or mask) and a given component.
virtual MatchResult  matchComponent (const MSelectionList &item, const MAttributeSpecArray &spec, MSelectionList &list)
  This method is used to convert the string representation of a component into a component object and to validate that the indices.
virtual MObject  createFullVertexGroup () const
  This method is used to create a component containing every vertex/CV in the object.
virtual bool  deleteComponents (const MObjectArray &componentList, MDoubleArray &undoInfo)
  This method should be overridden if the shape is to support deletion of components.
virtual bool  undeleteComponents (const MObjectArray &componentList, MDoubleArray &undoInfo)
  This method should be overridden if the shape is to support undeletion of components.
virtual MObject  localShapeInAttr () const
  Returns the input attribute of the shape.
virtual MObject  localShapeOutAttr () const
  Returns the local output attribute of the shape.
virtual MObject  worldShapeOutAttr () const
  Returns the world space output attribute of the shape.
virtual MObject  cachedShapeAttr () const
  Returns the cached shape attribute of the shape.
virtual MObject  geometryData () const
  Returns the geometry data of the shape.
virtual void  closestPoint (const MPoint &toThisPoint, MPoint &theClosestPoint, double tolerance)
  This method is used by Maya in functions (such as select) that require closest point information from your surface.
virtual bool  pointAtParm (const MPoint &atThisParm, MPoint &evaluatedPoint)
  This method is used by Maya in functions (such as select) that require point at parameter values.
virtual MPxGeometryIterator geometryIteratorSetup (MObjectArray &, MObject &, bool forReadOnly=false)
  This method should be overridden by the user to return a geometry iterator compatible with the user's geometry.
virtual bool  acceptsGeometryIterator (bool writeable=true)
  If the shape can supply a component iterator then then this method should be overridden to return true.
virtual bool  acceptsGeometryIterator (MObject &, bool writeable=true, bool forReadOnly=false)
  If the shape can supply a component iterator then then this method should be overridden to return true.
MObjectArray  activeComponents () const
  Returns a list of active (selected) components for the shape.
bool  hasActiveComponents () const
  This method is used to determine whether or not the shape has active (selected) components.
void  childChanged (MChildChanged=kObjectChanged)
  This method can be used to trigger the shape to recalculate its bounding box.
bool  isRenderable () const
  Returns true if the shape is a renderable shape.
void  setRenderable (bool)
  Specifies whether the shape is a renderable shape.
MMatrix  getWorldMatrix (MDataBlock &, unsigned int) const
  Returns MMatrix which takes a point from local object space to world space.

Static Public Member Functions

static const char *  className ()
  Returns the name of this class.

Static Public Attributes

static MObject  mControlPoints
  Control points for the derived shapes.
static MObject  mControlValueX
  X value of a control point.
static MObject  mControlValueY
  Y value of a control point.
static MObject  mControlValueZ
  Z value of a control point.
static MObject  nodeBoundingBox
  bounding box attribute
static MObject  nodeBoundingBoxMin
  bounding box minimum point
static MObject  nodeBoundingBoxMinX
  X component of boundingBoxMin.
static MObject  nodeBoundingBoxMinY
  Y component of boundingBoxMin.
static MObject  nodeBoundingBoxMinZ
  Z component of boundingBoxMin.
static MObject  nodeBoundingBoxMax
  bounding box maximum point
static MObject  nodeBoundingBoxMaxX
  X component of boundingBoxMax.
static MObject  nodeBoundingBoxMaxY
  Y component of boundingBoxMax.
static MObject  nodeBoundingBoxMaxZ
  Z component of boundingBoxMax.
static MObject  nodeBoundingBoxSize
  bounding box size vector
static MObject  nodeBoundingBoxSizeX
  X component of boundingBoxSize.
static MObject  nodeBoundingBoxSizeY
  Y component of boundingBoxSize.
static MObject  nodeBoundingBoxSizeZ
  Z component of boundingBoxSize.
static MObject  center
  object center attribute
static MObject  boundingBoxCenterX
  X component of boundingBoxCenter.
static MObject  boundingBoxCenterY
  Y component of boundingBoxCenter.
static MObject  boundingBoxCenterZ
  Z component of boundingBoxCenter.
static MObject  matrix
  matrix attribute
static MObject  inverseMatrix
  inverse matrix attribute
static MObject  worldMatrix
  world matrix attribute
static MObject  worldInverseMatrix
  inverse world matrix attribute
static MObject  parentMatrix
  parent matrix attribute
static MObject  parentInverseMatrix
  inverse parent matrix attribute
static MObject  visibility
  visibility attribute
static MObject  intermediateObject
  intermediate object attribute
static MObject  isTemplated
  template attribute
static MObject  instObjGroups
  instances object group info attribute
static MObject  objectGroups
  object groups attributes
static MObject  objectGrpCompList
  component in object groups attribute
static MObject  objectGroupId
  group id attribute
static MObject  objectGroupColor
  group id attribute
static MObject  useObjectColor
  controls choice of wireframe dormant object color
static MObject  objectColor
  the per object dormant wireframe color

Member Enumeration Documentation

Vertex caching modes.

Enumerator:
kNoPointCaching 

No point caching.

kSavePoints 

Points should be saved for undo in the point cache.

kRestorePoints 

Points should be restored from the point cache.

kUpdatePoints 

Update the points.

Vertex offset modes.

Enumerator:
kNormal 

Move in normal direction.

kUTangent 

Move in u tangent direction.

kVTangent 

Move in v tangent direction.

kUVNTriad 

Calculate u, v, and normal offsets.

Return values for the matchComponent() method.

Enumerator:
kMatchOk 

The component was matched without error.

kMatchNone 

No component was matched.

kMatchTooMany 

Not used.

kMatchInvalidName 

One of the names in the attribute specification was not valid.

kMatchInvalidAttribute 

Not used.

kMatchInvalidAttributeIndex 

The attribute specification contained an index for a non-array attribute.

kMatchInvalidAttributeRange 

An attribute index was out of range.

kMatchInvalidAttributeDim 

The attribute specification provided the wrong number of dimensions for an attribute.

Scope of change.

Enumerator:
kObjectChanged 

Object geometry changed. Internal caches need to be updated.

kBoundingBoxChanged 

Object geometry is unchanged but its bounding box has changed.

This might happen if the object was moved or an offset changed.


Constructor & Destructor Documentation

Class constructor.

Any calls the MPxSurfaceShape methods must be done in the postConstructor method and not here.


Member Function Documentation

MPxNode::Type type ( ) const [virtual]

Returns the type of node that this is.

This is used to differentiate user defined nodes that are derived off different MPx base classes.

It is not necessary to override this method.

Returns:
Type of the node (MPxNode::kSurfaceShape)

Reimplemented from MPxNode.

bool isBounded ( ) const [virtual]

This method should be overridden to return true if the user supplies a bounding box routine.

Supplying a bounding box routine makes refresh and selection more efficient.

Returns:
A boolean value indicating whether a bounding box routine has been supplied
Examples:
apiMeshShape.h, and quadricShape.cpp.
MBoundingBox boundingBox ( ) const [virtual]

This method should be overridden to return a bounding box for the shape.

If this method is overridden, then MPxSurfaceShape::isBounded should also be overridden to return true.

Returns:
The bounding box of the shape
Examples:
apiMeshShape.h, apiMeshShapeUI.cpp, and quadricShape.cpp.
void transformUsing ( const MMatrix matrix,
const MObjectArray componentList 
) [virtual]

Transform the given components using the specified transformation matrix.

This method should be overridden if the shape supports components that can be transformed using maya's move, scale, and rotate tools.

Parameters:
[in] matrix the matrix representing the transformation that is to be applied to the components
[in] componentList a list of components to be tranformed. If the list is empty, it indicates that every point in the geometry should be transformed.

Reimplemented in MPxComponentShape.

Examples:
apiMeshShape.h.
void transformUsing ( const MMatrix mat,
const MObjectArray componentList,
MVertexCachingMode  cachingMode,
MPointArray pointCache 
) [virtual]

Transform the given components using the specified transformation matrix.

This method should be overridden if the shape supports components that can be transformed using maya's move, scale, and rotate tools.

Parameters:
[in] mat the matrix representing the transformation that is to be applied to the components
[in] componentList a list of components to be transformed. If the list is empty, it indicates that every point in the geometry should be transformed.
[in] cachingMode whether the points should be cached in the pointCache argument, or restored from the pointCache
[in] pointCache used to store for undo and restore points during undo

Reimplemented in MPxComponentShape.

void tweakUsing ( const MMatrix mat,
const MObjectArray componentList,
MVertexCachingMode  cachingMode,
MPointArray pointCache,
MArrayDataHandle handle 
) [virtual]

Transform the given components using the specified transformation matrix.

This method should be overridden if the shape supports components that can be transformed using maya's move, scale, and rotate tools. This method is called when the shape has history & connected to a tweak node. The most common reason why the shape would be connected to a tweak node is if it is being deformed. When a shape is connected to a tweak node, transformations applied to the points are placed in the tweak node rather than in the shape itself.

Parameters:
[in] mat the matrix representing the transformation that is to be applied to the components
[in] componentList a list of components to be tranformed. If the list is empty, it indicates that every point in the geometry should be transformed.
[in] cachingMode whether the points should be cached in the pointCache argument, or restored from the pointCache
[in] pointCache used to store for undo and restore points during undo
[in] handle array data handle where the tweaks are stored
Examples:
apiMeshShape.h.
bool convertToTweakNodePlug ( MPlug plug ) const

Check if a tweak node is connected to this node.

If it is, then reset the supplied plug to contain the controlPoints attribute on the tweak node.

Parameters:
[in] plug plug which will be set to point to the associated tweak node plug if a tweak node is connected
Returns:
true if a tweak node was found, false if the plug was unchanged
bool vertexOffsetDirection ( MObject component,
MVectorArray direction,
MVertexOffsetMode  mode,
bool  normalize 
) [virtual]

This method should be overridden if the shape supports components that can be moved in the direction of the normal or UV's using the move vertex normal tool.

This method should calculate the offset direction for a vertex components. The direction vector array is an array of offsets corresponding to the elements in the component. The mode argument specifies the type of movement that is being performed.

The default for this method is to return false, i.e. no support for move normal tool.

Parameters:
[in] component
[in] direction
[in] mode The type of vertex movement
  • mode = 0 -> normal
  • mode = 1 -> U
  • mode = 2 -> V
  • mode = 3 -> UVN triad
Parameters:
[in] normalize specifies whether the offset vectors should be normalized
Returns:
true if the shape supports the current mode, false if the shape cannot do the requested vertex move
Examples:
apiMeshShape.h.
MObject newControlPointComponent ( ) const [virtual]

The default action of this method is to return an MFnSingleIndexedComponent (of type MFn::kMeshVertComponent) in order to support rigid skinning binds.

This method can be overriden to support other types of components such as MFnDoubleIndexedComponent and MFnTripleIndexedComponent and should return a new component of that type. The types allowed are those listed in the create() method docs for each MFn*IndexedComponent.

No argument is required.

The skinning code handles the deallocation of the new component.

Returns:
The new component
void componentToPlugs ( MObject component,
MSelectionList list 
) const [virtual]

Converts the given component into a selection list of plugs.

This method is used to associate a shapes components into the corresponding attributes (plugs) within the shape. For example, it gets called by the translate manipulator to determine which attributes should be driven by the manipulator, and by the setKeyframe command to determine where to connect animCurves for components.

This method should be overridden if the shape supports components that can be selected and moved in Maya.

Parameters:
[in] component the component to be converted
[in] list a selection list where the plug should be added

Reimplemented in MPxComponentShape.

Examples:
apiMeshShape.h.
bool match ( const MSelectionMask mask,
const MObjectArray componentList 
) const [virtual]

This method is used to check for matches between a selection type (or mask) and a given component.

If your shape has components representing attributes then this method is used to match up your components with selection masks.

This is used by sets and deformers to make sure that the selected components fall into the "vertex only" category. This is useful when you want to make sure that only a particular component can be deformed.

Parameters:
[in] mask the selection mask to test against
[in] componentList a list of components to be tested
Returns:
  • true the match was successfull
  • false the match failed

Reimplemented in MPxComponentShape.

Examples:
apiMeshShape.h.
MPxSurfaceShape::MatchResult matchComponent ( const MSelectionList item,
const MAttributeSpecArray spec,
MSelectionList list 
) [virtual]

This method is used to convert the string representation of a component into a component object and to validate that the indices.

This method should be overridden if the shape has components.

Parameters:
[in] item DAG selection item for the object being matched
[in] spec attribute specification object
[in] list list to add components to
Returns:
The component match result
Examples:
apiMeshShape.cpp, and apiMeshShape.h.
MObject createFullVertexGroup ( ) const [virtual]

This method is used to create a component containing every vertex/CV in the object.

This method is supposed to return non-NULL only if the dag object contains vertices/CVs (control points), so derived classes that do should override this method.

Eg: use MFnSingleIndexedComponent::setCompleteData( numVertices ) to specify that a component represents all the vertices of the shape.

Returns:
A component containing all of the vertices in the shape.

Reimplemented in MPxComponentShape.

Examples:
apiMeshShape.h.
bool deleteComponents ( const MObjectArray componentList,
MDoubleArray undoInfo 
) [virtual]

This method should be overridden if the shape is to support deletion of components.

A list of components to be deleted will be passed in as well as an array of doubles where information about each deleted component can be stored for undo purposes. A typical use for this array is to store knot values or weights for control points that are deleted.

Parameters:
[in] componentList List of components to be deleted
[in] undoInfo Values used for undo purposes
Returns:
true if this method was successful, false otherwise
bool undeleteComponents ( const MObjectArray componentList,
MDoubleArray undoInfo 
) [virtual]

This method should be overridden if the shape is to support undeletion of components.

A list of components to be deleted will be passed in as well as an array of doubles where information about each deleted component is stored for undo purposes. A typical use for this array is to store knot values or weights for control points that are deleted.

Parameters:
[in] componentList List of components that were deleted
[in] undoInfo Values used for undo purposes
Returns:
true if this method was successful, false otherwise
MObject localShapeInAttr ( ) const [virtual]

Returns the input attribute of the shape.

This method will be called by Maya to determine if the shape has construction history.

Returns:
The input attribute

Reimplemented in MPxComponentShape.

Examples:
apiMeshShape.h.
MObject localShapeOutAttr ( ) const [virtual]

Returns the local output attribute of the shape.

Returns:
The output attribute
Examples:
apiMeshShape.h.
MObject worldShapeOutAttr ( ) const [virtual]

Returns the world space output attribute of the shape.

Returns:
The world space output attribute
Examples:
apiMeshShape.h.
MObject cachedShapeAttr ( ) const [virtual]

Returns the cached shape attribute of the shape.

Returns:
The attribute that stores the cached shape
Examples:
apiMeshShape.h.
MObject geometryData ( ) const [virtual]

Returns the geometry data of the shape.

The geometry data must be derived from the MPxGeometryData class.

The data is used by Maya to add, edit and query component grouping (set) information for the shape. This set information is stored and managed by Maya's shape base class, geometryShape.

Returns:
The geometry data of the shape
Examples:
apiMeshShape.h.
void closestPoint ( const MPoint toThisPoint,
MPoint theClosestPoint,
double  tolerance 
) [virtual]

This method is used by Maya in functions (such as select) that require closest point information from your surface.

Parameters:
[in] toThisPoint the point to test against
[out] theClosestPoint the closest point on your surface
[in] tolerance tolerance to use in your calculations
Examples:
apiMeshShape.h.
bool pointAtParm ( const MPoint atThisParm,
MPoint evaluatedPoint 
) [virtual]

This method is used by Maya in functions (such as select) that require point at parameter values.

This only makes sense for parametric surfaces such as NURBS.

Parameters:
[in] atThisParm the parameter to check
[out] evaluatedPoint the surface point
Returns:
true if a point was found, false otherwise
MPxGeometryIterator * geometryIteratorSetup ( MObjectArray componentList,
MObject components,
bool  forReadOnly = false 
) [virtual]

This method should be overridden by the user to return a geometry iterator compatible with the user's geometry.

A geometry iterator is used for iterating over the components of a shape, such as the vertices of a mesh, in a generic manner.

The components to be iterated over are passed to this function in on of two ways, as a list of components, or as a single component. Only one of these arguments is used at any particular time.

Parameters:
[in] componentList a list of components to be iterated over
[in] components the components to be iterated over
[in] forReadOnly specifies whether the iterator is for read-only
Returns:
The component match result
Examples:
apiMeshShape.h, and apiSimpleShape.h.
bool acceptsGeometryIterator ( bool  writeable = true ) [virtual]

If the shape can supply a component iterator then then this method should be overridden to return true.

The default is to return false.

Parameters:
[in] writeable is this component type writable by an iterator
Returns:
  • true the shape can supply an iterator
  • false the shape cannot supply an iterator
Examples:
apiMeshShape.h, and apiSimpleShape.h.
bool acceptsGeometryIterator ( MObject component,
bool  writeable = true,
bool  forReadOnly = false 
) [virtual]

If the shape can supply a component iterator then then this method should be overridden to return true.

The default is to return false. The component argument can be used to when the shape has multiple components and not all of them can be iterator over.

Parameters:
[in] component the component to test
[in] writeable is this component type writable by an iterator
[in] forReadOnly is this component type readable by an iterator
Returns:
  • true the shape can supply an iterator
  • false the shape cannot supply an iterator
MObjectArray activeComponents ( ) const

Returns a list of active (selected) components for the shape.

Returns:
An array of active components
bool hasActiveComponents ( ) const

This method is used to determine whether or not the shape has active (selected) components.

Returns:
  • true there are active components
  • false there are no active components
void childChanged ( MChildChanged  state = kObjectChanged )

This method can be used to trigger the shape to recalculate its bounding box.

Parameters:
[in] state the type of change that has occurred
bool isRenderable ( ) const

Returns true if the shape is a renderable shape.

Making a shape renderable allows the shape to have shading group assignments.

Returns:
  • true the shape is renderable
  • false the shape is not renderable
void setRenderable ( bool  flag )

Specifies whether the shape is a renderable shape.

Making a shape renderable allows the shape to have shading group assignments.

Parameters:
[in] flag true if the shape is to be renderable, false otherwise
MMatrix getWorldMatrix ( MDataBlock block,
unsigned int  instanceGeom 
) const

Returns MMatrix which takes a point from local object space to world space.

Parameters:
[in] block a MDataBlock
[in] instanceGeom the instance this MPxSurfaceShape corresponds to
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented from MPxNode.


MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape
MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape MPxSurfaceShape