Class Object
See Also: Class BaseObject, Class Deformer, Class Interval, Class GraphicsWindow, Template Class Tab, Geometry Pipeline System.
class Object: public BaseObject , public IXTCAccess
Description:
The object class is the base class for all objects. An object is one of two things: A procedural object or a derived object. Derived objects are part of the system and may not be created by plug-ins. They are containers for modifiers. Procedural objects can be many different things such as cameras, lights, helper objects, geometric objects, etc. Methods of this class are responsible for things such as allowing the object to be deformed (changing its points), retrieving a deformed bounding box, converting the object between different types (to a mesh or patch for example), texture mapping the object (if appropriate) and interacting with the system regarding mapping. There are other methods involved in validity intervals for the object and its channels, and a method used to return the sub-object selection state of the object.
Method Groups:
The hyperlinks below jump to the start of groups of related methods within the class:
Face and Vertex Count Calculations
Object Name, Properties, Display, and IntersectRay Methods
Viewport Rectangle Enlargement
Methods:
Prototype:
virtual int IsDeformable()
Remarks:
Implemented by the Plug-In.
Indicates whether this object is deformable. A deformable object is simply an object with points that can be modified. Deformable objects must implement the generic deformable object methods (NumPoints(), GetPoint(i), SetPoint(i), Deform()).
A deformable object is simply an object with points that can be modified. These points can be stored in any form the object wants. They are accessed through a virtual array interface with methods to get and set the 'i-th' point. If an object has tangents for instance, it would convert them to and from points as necessary. For example, a simple Bezier spline object that stored its control handles relative to the knot would convert them to be absolute when GetPoint() was called with 'i' specifying one of the control points. When the control point is later set, the object can convert it back to be relative to its knot. At this point it could also apply any constraints that it may have, such as maintaining a degree of continuity. The idea is that the entity calling GetPoint(i) and SetPoint(i) doesn't care what the point represents. It will simply apply some function to the point.
Return Value:
Return nonzero if the object is deformable and implements the generic deformable object methods; otherwise 0.
Default Implementation:
{ return 0; }
Deformable object methods. These only need to be implemented if the object returns TRUE from the IsDeformable() method.
Prototype:
virtual int NumPoints()
Remarks:
Implemented by the Plug-In.
The points of a deformable object are accessed through a virtual array interface. This method specifies the number of points in the object. The meaning of 'points' is defined by the object. A TriObject uses the vertices as the points for example.
Default Implementation:
{ return 0;}
Return Value:
The number of points in the object.
Prototype:
virtual Point3 GetPoint(int i)
Remarks:
Implemented by the Plug-In.
The points of a deformable object are accessed through a virtual array interface. This method returns the 'i-th' point of the object.
Note: If your plug-in is a modifier and you want to operate on the selected points of the object you are modifying, you can't tell which points are selected unless you know the type of object. If it is a generic deformable object there is no way of knowing since the way the object handles selection is up to it. Therefore, if you want to operate on selected points of a generic deformable object, use a Deformer.
Parameters:
int i
Specifies which point should be returned.
Default Implementation:
{ return Point3(0,0,0); }
Return Value:
The 'i-th' point of the object.
Prototype:
virtual void SetPoint(int i, const Point3& p)
Remarks:
Implemented by the Plug-In.
The points of a deformable object are accessed through a virtual array interface. This method stores the 'i-th' point of the object.
Parameters:
int i
The index of the point to store.
const Point3& p
The point to store.
Prototype:
virtual BOOL IsPointSelected(int i);
Remarks:
This method is available in release 3.0 and later only.
Returns TRUE if the 'i-th' point is selected; otherwise FALSE.
Parameters:
int i
The zero based index of the point to check.
Default Implementation:
{ return FALSE; }
Prototype:
virtual float PointSelection(int i);
Remarks:
This method is available in release 3.0 and later only.
Returns a floating point weighted point selection if the object supports it. The default implementation just returns 1.0f if selected and 0.0f if not.
Parameters:
int i
The zero based index of the point to check.
Default Implementation:
{ return IsPointSelected(i) ? 1.0f : 0.0f; }
Prototype:
virtual void PointsWereChanged();
Remarks:
Implemented by the Plug-In.
Informs the object that its points have been deformed, so it can invalidate its cache. A developer who uses the GetPoint() / SetPoint() approach to modifying an object will call PointsWereChanged() to invalidate the object's cache. For example, if a modifier calls SetPoint(), when it is finished it should call this method so the object can invalidate and/or update its bounding box and any other data it might cache.
Prototype:
virtual void Deform(Deformer *defProc, int useSel=0);
Remarks:
Implemented by the Plug-In.
This is the method used to deform the object with a deformer. The developer should loop through the object's points calling the defProc for each point (or each selected point if useSel is nonzero).
The Deform() method is mostly a convenience. Modifiers can implement a 'Deformer' callback object which is passed to the Deform() method. The object then iterates through its points calling their deformer's callback for each point. The only difference between using the Deform() method as opposed to iterating through the points is that the Deform() method should respect sub-object selection. For example, the TriObject's implementation of Deform() iterates through its vertices, if the TriObject's selection level is set to vertex then it only calls the Deformer's callback for vertices that are selected. This way modifiers can be written that can be applied only to selection sets without any specific code to check selected points. The default implementation of this method just iterates through all points using GetPoint(i) and SetPoint(i). If an object supports sub-object selection sets then it should override this method.
Parameters:
Deformer *defProc
A pointer to an instance of the Deformer class. This is the callback object that actually performs the deformation.
int useSel=0
A flag to indicate if the object should use the selected points only. If nonzero the selected points are used; otherwise all the points of the object are used.
Default Implementation:
void Object::Deform(Deformer *defProc,int useSel) {
int nv = NumPoints();
for (int i=0; i<nv; i++)
SetPoint(i,defProc->Map(i,GetPoint(i)));
PointsWereChanged();
}
Sample Code:
This code shows the TriObject implementation of this method. Note how it looks at the useSel parameter to only call the selected points if required.
void TriObject::Deform(Deformer *defProc,int useSel) {
int nv = NumPoints();
int i;
if ( useSel ) {
BitArray sel = mesh.VertexTempSel();
float *vssel = mesh.getVSelectionWeights ();
if (vssel) {
for (i=0; i<nv; i++) {
if(sel[i]) {
SetPoint(i,defProc->Map(i,GetPoint(i)));
continue;
}
if (vssel[i]==0) continue;
Point3 & A = GetPoint(i);
Point3 dir = defProc->Map(i,A) - A;
SetPoint(i,A+vssel[i]*dir);
}
} else {
for (i=0; i<nv; i++) if (sel[i]) SetPoint(i,defProc->Map(i,GetPoint(i)));
}
} else {
for (i=0; i<nv; i++)
SetPoint(i,defProc->Map(i,GetPoint(i)));
}
PointsWereChanged();
}
Prototype:
virtual BOOL HasWeights();
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the object has weights for its points that can be set; otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual double GetWeight(int i);
Remarks:
This method is available in release 2.0 and later only.
Returns the weight of the specified point of the object.
Parameters:
int i
The point to return the weight of.
Default Implementation:
{ return 1.0; }
Prototype:
virtual void SetWeight(int i, const double w);
Remarks:
This method is available in release 2.0 and later only.
Sets the weight of the specified point.
Parameters:
int i
The point whose weight to set.
const double w
The value to set.
Default Implementation:
{}
Prototype:
virtual void GetDeformBBox(TimeValue t, Box3& box, Matrix3 *tm=NULL, BOOL useSel=FALSE );
Remarks:
Implemented by the Plug-In.
This method computes the bounding box in the objects local coordinates or the optional space defined by tm.
Note: If you are looking for a precise bounding box, use this method and pass in the node's object TM (INode::GetObjectTM()) as the matrix.
Parameters:
TimeValue t
The time to compute the box.
Box3& box
A reference to a box the result is stored in.
Matrix3 *tm=NULL
This is an alternate coordinate system used to compute the box. If the tm is not NULL this matrix should be used in the computation of the result.
BOOL useSel=FALSE
If TRUE, the bounding box of selected sub-elements should be computed; otherwise the entire object should be used.
Prototype:
virtual int CanConvertToType(Class_ID obtype)
Remarks:
Implemented by the Plug-In.
Indicates whether the object can be converted to the specified type. If the object returns nonzero to indicate it can be converted to the specified type, it must handle converting to and returning an object of that type from ConvertToType().
Also see Class ObjectConverter for additional details on converting objects between types.
Parameters:
Class_ID obtype
The Class_ID of the type of object to convert to. See Class Class_ID, List of Class_IDs.
Return Value:
Nonzero if the object can be converted to the specified type; otherwise 0.
Default Implementation:
{ return 0; }
Prototype:
virtual Object* ConvertToType(TimeValue t, Class_ID obtype)
Remarks:
Implemented by the Plug-In.
This method converts this object to the type specified and returns a pointer it. Note that if ConvertToType() returns a new object it should be a completely different object with no ties (pointers or references) to the original.
Also see Class ObjectConverter for additional details on converting objects between types.
The following is an issue that developers of world space modifiers need to be aware of if the world space modifier specifies anything but generic deformable objects as its input type. In other words, if a world space modifier, in its implementation of Modifier::InputType(), doesn't specifically return defObjectClassID then the following issue regarding the 3ds max pipeline needs to be considered. Developers of other plug-ins that don't meet this condition don't need to be concerned with this issue.
World space modifiers that work on anything other than generic deformable objects are responsible for transforming the points of the object they modify into world space using the ObjectState TM. To understand why this is necessary, consider how 3ds max applies the node transformation to the object flowing down the pipeline.
In the geometry pipeline architecture, the node in the scene has its transformation applied to the object in the pipeline at the transition between the last object space modifier and the first world space modifier. The node transformation is what places the object in the scene -- thus this is what puts the object in world space. The system does this by transforming the points of the object in the pipeline by the node transformation. This is only possible however for deformable objects. Deformable objects are those that support the Object::IsDeformable(), NumPoints(), GetPoint() and SetPoint() methods. These deformable objects can be deformed by the system using these methods, and thus the system can modify the points to put them in world space itself.
If a world space modifier does not specify that it works on deformable objects, the system is unable to transform the points of the object into world space. What it does instead is apply the transformation to the ObjectState TM. In this case, a world space modifier is responsible for transforming the points of the object into world space itself, and then setting the ObjectState TM to the identity. There is an example of this in the sample code for the Bomb space warp. The Bomb operates on TriObjects and implements InputType() as { return Class_ID(TRIOBJ_CLASS_ID,0); }. Since it doesn't specifically return defObjectClassID, it is thus responsible for transforming the points of the object into world space itself. It does this in its implementation of ModifyObject() as follows:
if (os->GetTM()) {
Matrix3 tm = *(os->GetTM());
for (int i=0; i<triOb->mesh.getNumVerts(); i++) {
triOb->mesh.verts[i] = triOb->mesh.verts[i] * tm;
}
os->obj->UpdateValidity(GEOM_CHAN_NUM,os->tmValid());
os->SetTM(NULL,FOREVER);
}
As the code above shows, the Bomb checks if the ObjectState TM is non-NULL. If it is, the points of the object are still not in world space and thus must be transformed. It does this by looping through the points of the TriObject and multiplying each point by the ObjectState TM. When it is done, it sets the ObjectState TM to NULL to indicate the points are now in world space. This ensure that any later WSMs will not transform the points with this matrix again.
For the Bomb world space modifier this is not a problem since it specifies in its implementation of ChannelsChanged() that it will operate on the geometry channel (PART_GEOM). Certain world space modifiers may not normally specify PART_GEOM in their implementation of ChannelsChanged(). Consider the camera mapping world space modifier. Its function is to apply mapping coordinates to the object it is applied to. Thus it would normally only specify PART_TEXMAP for ChannelsChanged(). However, since it operates directly on TriObjects, just like the Bomb, the system cannot transform the points into world space, and therefore the camera mapping modifier must do so in its implementation of ModifyObject(). But since it is actually altering the points of the object by putting them into world space it is altering the geometry channel. Therefore, it should really specify PART_GEOM | PART_TEXMAP in its implementation of ChannelsChanged(). If it didn't do this, but went ahead and modified the points of the object anyway, it would be transforming not copies of the points, but the original points stored back in an earlier cache or even the base object.
This is the issue developers need to be aware of. To state this in simple terms then: Any world space modifier that needs to put the points of the object into world space (since it doesn't implement InputType() as defObjectClassID) needs to specify PART_GEOM in its implementation of ChannelsChanged().
Parameters:
TimeValue t
The time at which to convert.
Class_ID obtype
The Class_ID of the type of object to convert to. See Class Class_ID, List of Class_IDs.
Return Value:
A pointer to an object of type obtype.
Default Implementation:
{ return NULL; }
Sample Code:
The following code shows how a TriObject can be retrieved from a node. Note on the code that if you call ConvertToType() on an object and it returns a pointer other than itself, you are responsible for deleting that object.
// Retrieve the TriObject from the node
int deleteIt;
TriObject *triObject = GetTriObjectFromNode(ip->GetSelNode(0),
deleteIt);
// Use the TriObject if available
if (!triObject) return;
// ...
// Delete it when done...
if (deleteIt) triObject->DeleteMe();
// Return a pointer to a TriObject given an INode or return NULL
// if the node cannot be converted to a TriObject
TriObject *Utility::GetTriObjectFromNode(INode *node, int &deleteIt) {
deleteIt = FALSE;
Object *obj = node->EvalWorldState(0).obj;
if (obj->CanConvertToType(Class_ID(TRIOBJ_CLASS_ID, 0))) {
TriObject *tri = (TriObject *) obj->ConvertToType(0,
Class_ID(TRIOBJ_CLASS_ID, 0));
// Note that the TriObject should only be deleted
// if the pointer to it is not equal to the object
// pointer that called ConvertToType()
if (obj != tri) deleteIt = TRUE;
return tri;
}
else {
return NULL;
}
}
Face and Vertex Count Calculations
Prototype:
virtual BOOL PolygonCount(TimeValue t, int& numFaces, int& numVerts);
Remarks:
This method is available in release 3.0 and later only.
Retreives the number of faces and vertices of the polyginal mesh representation of this object. If this method returns FALSE then this functionality is not supported.
Note: Plug-In developers should use the global function GetPolygonCount(Object*, int&, int&) to retrieve the number f vertices and faces in an arbitrary object.
Parameters:
TimeValue t
The time at which to compute the number of faces and vertices.
int& numFaces
The number of faces is returned here.
int& numVerts
The number of vertices is returned here.
Return Value:
TRUE if the method is fully implemented; otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual Class_ID PreferredCollapseType();
Remarks:
This method is available in release 2.0 and later only.
This method allows objects to specify the class that is the best class to convert to when the user collapses the stack. The main base classes have default implementations. For example, GeomObject specifies TriObjects as its preferred collapse type and shapes specify splines as their preferred collapse type
Default Implementation:
{return Class_ID(0,0);}
Return Value:
The Class_ID of the preferred object type. See List of Class_IDs.
Prototype:
virtual void GetCollapseTypes(Tab<Class_ID> &clist,Tab<TSTR*> &nlist);
Remarks:
This method is available in release 2.0 and later only.
When the user clicks on the Edit Stack button in the modify branch a list of 'Convert To:' types is presented. The use may click on one of these choices to collapse the object into one of these types (for instance, an Editable Mesh or an Editable NURBS object). This method returns a list of Class_IDs and descriptive strings that specify the allowable types of objects that this object may be collapsed into.
Note: Most plug-ins call the base class method in Object in their implementation of this method. The base class implementation provided by Object checks if the object can convert to both an editable mesh and an editable spline. If it can, these are added to the allowable types.
Parameters:
Tab<Class_ID> &clist
The table of allowable Class_IDs.
Tab<TSTR*> &nlist
The table of pointers to strings that correspond to the table of Class_IDs above.
Sample Code:
void SphereObject::GetCollapseTypes(Tab<Class_ID> &clist,Tab<TSTR*> &nlist)
{
Object::GetCollapseTypes(clist, nlist);
Class_ID id = EDITABLE_SURF_CLASS_ID;
TSTR *name = new TSTR(GetString(IDS_SM_NURBS_SURFACE));
clist.Append(1,&id);
nlist.Append(1,&name);
}
Prototype:
virtual Object *CollapseObject();
Remarks:
This method is available in release 4.0 and later only.
This method is called on the world space cache object when the stack gets collapsed, that lets the pipeline object decide, if it wants to return a different object than itself. The default implementation simply returns this. A PolyObject e.g. can create and return an EditablePolyObject in this method, so that the collapsed object has a UI. I only implemented this method for PolyObject, but this can potentially implemented that way for all pipeline objects, that currently pass up the editable version.
It is important, that all places, that collapse the stack are calling this method after evaluating the stack.
It also is important, that the editable version implements this method to simply return this, otherwise you'll get a non-editable object when you collapse an editable polyobject.
Return Value:
A pointer to the resulting object.
Default Implementation:
{ return this;}
Prototype:
virtual int IsMappable()
Remarks:
This method lets you know if the ApplyUVWMap() method is available for this object. This is used by things like the UVW mapping modifier, so that it can determine which objects can have their mapping modified. Returns nonzero if the object is mappable; otherwise zero.
Default Implementation:
{ return 0; }
Prototype:
virtual int NumMapChannels();
Remarks:
This method is available in release 3.0 and later only.
Returns the maximum number of channels supported by this type of object. TriObjects for instance return MAX_MESHMAPS which is currently set to 100.
Default Implementation:
{ return IsMappable(); }
Prototype:
virtual int NumMapsUsed();
Remarks:
This method is available in release 3.0 and later only.
Returns the number of maps currently used by this object. This is at least 1+(highest channel in use). This is used so a plug-in that does something to all map channels doesn't always have to do it to every channel up to MAX_MESHMAPS but rather only to this value.
Default Implementation:
{ return NumMapChannels(); }
Prototype:
void ApplyUVWMap(int type,float utile, float vtile, float wtile,int uflip, int vflip, int wflip, int cap,const Matrix3 &tm, int channel=1);
Remarks:
This method may be called to map the object with UVW mapping coordinates. If the object returns nonzero from IsMappable() then this method should be implemented.
Parameters:
int type
The mapping type. One of the following values:
MAP_PLANAR
MAP_CYLINDRICAL
MAP_SPHERICAL
MAP_BALL
MAP_BOX
float utile
Number of tiles in the U direction.
float vtile
Number of tiles in the V direction.
float wtile
Number of tiles in the W direction.
int uflip
If nonzero the U values are mirrored.
int vflip
If nonzero the V values are mirrored.
int wflip
If nonzero the W values are mirrored.
int cap
This is used with MAP_CYLINDRICAL. If nonzero, then any face normal that is pointing more vertically than horizontally will be mapped using planar coordinates.
const Matrix3 &tm
This defines the mapping space. As each point is mapped, it is multiplied by this matrix, and then it is mapped.
int channel=1
This parameter is available in release 2.0 and later only.
This indicates which channel the mapping is applied to. See List of Mapping Channel Index Values.
Object Name, Properties, Display, and IntersectRay Methods
Prototype:
virtual int IsRenderable()=0;
Remarks:
Implemented by the Plug-In.
Indicates whether the object may be rendered. Some objects such as construction grids and helpers should not be rendered and can return zero.
Return Value:
Nonzero if the object may be rendered; otherwise 0.
Prototype:
virtual int IsConstObject()
Remarks:
Implemented by the Plug-In.
This is called to determine if this is a construction object or not.
Return Value:
Nonzero if the object is a construction object; otherwise 0.
Default Implementation:
{ return 0; }
Prototype:
virtual void InitNodeName(TSTR& s)=0;
Remarks:
Implemented by the Plug-In.
This is the default name of the node when it is created.
Parameters:
TSTR& s
The default name of the node is stored here.
Prototype:
virtual int UsesWireColor()
Remarks:
Implemented by the Plug-In.
This method determines if the object color is used for display.
Return Value:
TRUE if the object color is used for display; otherwise FALSE.
Default Implementation:
{ return TRUE; }
Prototype:
virtual int DoOwnSelectHilite()
Remarks:
Implemented by the Plug-In.
If an object wants to draw itself in the 3D viewports in its selected state in some custom manner this method should return nonzero. If this item returns nonzero, the BaseObject::Display() method should respect the selected state of the object when it draws itself. If this method returns zero the system will use its standard method of showing the object as selected.
Default Implementation:
{ return 0; }
Return Value:
Nonzero if the object will draw itself in the selected state; otherwise 0. If nonzero, the plug-in developer is responsible for displaying the object in the selected state as part of its Display() method.
Prototype:
virtual int IntersectRay(TimeValue t, Ray& r, float& at, Point3& norm)
Remarks:
Implemented by the Plug-In.
This method is called to compute the intersection point and surface normal at this intersection point of the ray passed and the object.
Parameters:
TimeValue t
The time to compute the intersection.
Ray& r
Ray to intersect. See Class Ray.
float& at
The point of intersection.
Point3& norm
Surface normal at the point of intersection.
Default Implementation:
{return FALSE;}
Return Value:
Nonzero if a point of intersection was found; otherwise 0.
See Also: The Mesh class implementation of this method.
Prototype:
virtual BOOL NormalAlignVector(TimeValue t,Point3 &pt, Point3 &norm);
Remarks:
This method is available in release 2.0 and later only.
Objects that don't support the IntersectRay() method (such as helper objects) can implement this method to provide a default vector for use with the normal align command in 3ds max.
Parameters:
TimeValue t
The time to compute the normal align vector.
Point3 &pt
The point of intersection.
Point3 &norm
The normal at the point of intersection.
Return Value:
TRUE if this method is implemented to return the normal align vector; otherwise FALSE.
Default Implementation:
{return FALSE;}
Prototype:
virtual Interval ObjectValidity(TimeValue t)
Remarks:
Implemented by the Plug-In.
This method returns the validity interval of the object as a whole at the specified time.
Parameters:
TimeValue t
The time to compute the validity interval.
Default Implementation:
{ return FOREVER; }
Return Value:
The validity interval of the object.
Prototype:
void UpdateValidity(int nchan, Interval v);
Remarks:
Implemented by the Plug-In.
When a modifier is applied to an object, it needs to include its own validity interval in the interval of the object. To do this, a modifier calls the UpdateValidity() method of an object. This method intersects interval v to the nchan channel validity of the object.
Parameters:
int nchan
The validity interval of the modifier is intersected with this channel of the object. See List of Object Channel Numbers.
Interval v
The interval to intersect.
Shape viewports can reference shapes contained within objects, so the system needs to be able to access the shapes within an object. The following four methods provide this access. These methods are used by the loft object. Since loft objects are made up of shapes, this gives the system the ability to query the object to find out if it is a shape container. Most objects don't contain shapes so they can just use the default implementations.
Prototype:
virtual int NumberOfContainedShapes();
Remarks:
Implemented by the Plug-In.
Returns the number of shapes contained inside this object. A shape container may return zero if it doesn't currently have any shapes.
Return Value:
The number of shapes. A return value of -1 indicates this is not a container.
Default Implementation:
{ return -1; }
Prototype:
virtual ShapeObject *GetContainedShape(TimeValue t, int index)
Remarks:
Implemented by the Plug-In.
This method returns the ShapeObject specified by the index passed at the time specified. See Class ShapeObject.
Parameters:
TimeValue t
The time to return the shape.
int index
The index of the shape.
Default Implementation:
{ return NULL; }
Prototype:
virtual void GetContainedShapeMatrix(TimeValue t, int index, Matrix3 &mat)
Remarks:
Implemented by the Plug-In.
Returns the matrix associated with the shape whose index is passed. This matrix contains the offset within the object used to align the shape viewport to the shape.
Parameters:
TimeValue t
The time to return the matrix.
int index
The index of the shape whose matrix to return.
Matrix3 &mat
The matrix is returned here.
Default Implementation:
{}
Prototype:
virtual BitArray ContainedShapeSelectionArray()
Remarks:
Implemented by the Plug-In.
This is used by the lofter. The lofter can have several shapes selected, and the bit array returned here will have a bit set for each selected shape. See Class BitArray.
Return Value:
Default Implementation:
{ return BitArray(); }
Prototype:
virtual BOOL CheckObjectIntegrity()
Remarks:
Implemented by the Plug-In.
This method is used for debugging only. The TriObject implements this method by making sure its face's vert indices are all valid.
Return Value:
TRUE if valid; otherwise FALSE.
Default Implementation:
{return TRUE;}
Prototype:
virtual DWORD GetSubselState()
Remarks:
Implemented by the Plug-In.
For objects that have sub selection levels, this method returns the current selection level of the object. For example, a TriObject has the following selection levels: object, vertex, face, edge. Other object types may have different selection levels. The only standard is that a value of 0 indicates object level.
Default Implementation:
{return 0;}
Return Value:
The current selection level of the object.
Most plug-in procedural objects do not need to be concerned with the following methods associated with locks, channels and shallow copies. The only type of plug-ins that needs to be concerned with these methods are objects that actually flow down the pipeline. Most procedural plug-ins don't go down the pipeline, instead they convert themselves to a TriObject or PatchObject, and these goes down the pipeline. It is these TriObjects or PatchObject that deal with these methods. However plug-in objects that actually flow down the pipeline will use these methods. For more information see the Advanced Topics section on the Geometry Pipeline System.
Prototype:
virtual ObjectState Eval(TimeValue t)=0;
Remarks:
Implemented by the Plug-In.
This method is called to evaluate the object and return the result as an ObjectState. When the system has a pointer to an object it doesn't know if it's a procedural object or a derived object. So it calls Eval() on it and gets back an ObjectState. A derived object managed by the system may have to call Eval() on its input for example. A plug-in (like a procedural object) typically just returns itself.
A plug-in that does not just return itself is the Morph Object (\MAXSDK\SAMPLES\OBJECTS\MORPHOBJ.CPP). This object uses a morph controller to compute a new object and fill in an ObjectState which it returns.
Parameters:
TimeValue t
Specifies the time to evaluate the object.
Return Value:
The result of evaluating the object as an ObjectState.
Sample Code:
Typically this method is implemented as follows:
{ return ObjectState(this); }
Prototype:
void LockObject()
Remarks:
Implemented by the System.
This method locks the object as a whole. The object defaults to not modifiable.
Prototype:
void UnlockObject()
Remarks:
Implemented by the System.
This method unlocks the object as a whole.
Prototype:
int IsObjectLocked()
Remarks:
Implemented by the System.
Returns nonzero if the object is locked; otherwise 0.
Prototype:
void LockChannels(ChannelMask channels)
Remarks:
Implemented by the System.
Locks the specified channels of the object.
Parameters:
ChannelMask channels
The channels to lock.
Prototype:
void UnlockChannels(ChannelMask channels)
Remarks:
Implemented by the System.
Unlocks the specified channel(s) of the object.
Parameters:
ChannelMask channels
Specifies the channels to unlock.
Prototype:
ChannelMask GetChannelLocks()
Remarks:
Implemented by the System.
Returns the locked status of the channels.
Return Value:
The channels of the object that are locked.
Prototype:
void SetChannelLocks(ChannelMask channels)
Remarks:
Implemented by the System.
Sets the locked status of the object's channels.
Parameters:
ChannelMask channels
The channel to set to locked.
Prototype:
ChannelMask GetChannelLocks(ChannelMask m)
Remarks:
Implemented by the System.
Returns the locked status of the channels.
Parameters:
ChannelMask m
Not used.
Return Value:
The channels of the object that are locked.
Prototype:
void CopyChannelLocks(Object *obj, ChannelMask needChannels);
Remarks:
Implemented by the System.
Copies the specified channels from the object passed.
Parameters:
Object *obj
The source object.
ChannelMask needChannels
Indicates the channels to copy.
Prototype:
virtual Interval ChannelValidity(TimeValue t, int nchan);
Remarks:
Implemented by the Plug-In.
Retrieve the current validity interval for the nchan channel of the object.
Note that most procedural objects won't implement this method since they don't have individual channels. Developers wanting to get the validity interval for a procedural object should use Object::ObjectValidity() instead.
Parameters:
TimeValue t
The time to retrieve the validity interval of the channel.
int nchan
Specifies the channel to return the validity interval of. See List of Object Channel Numbers.
Return Value:
The validity interval of the specified channel.
Default Implementation:
return FOREVER;
Prototype:
virtual void SetChannelValidity(int nchan, Interval v);
Remarks:
Implemented by the Plug-In.
Sets the validity interval of the specified channel.
Parameters:
int nchan
Specifies the channel. See List of Object Channel Numbers.
Interval v
The validity interval for the channel.
Prototype:
virtual void InvalidateChannels(ChannelMask channels)
Remarks:
Implemented by the Plug-In.
This method invalidates the intervals for the given channel mask. This just sets the validity intervals to empty (calling SetEmpty() on the interval) .
Parameters:
ChannelMask channels
Specifies the channels to invalidate.
Prototype:
void ReadyChannelsForMod(ChannelMask channels);
Remarks:
Implemented by the System.
If the requested channels are locked, this method will replace their data with a copy and unlock them, otherwise it leaves them alone.
Parameters:
ChannelMask channels
The channels to ready for modification.
Prototype:
virtual Object *MakeShallowCopy(ChannelMask channels)
Remarks:
Implemented by the Plug-In.
This method must make a copy of its "shell" and then shallow copy (see below) only the specified channels. It must also copy the validity intervals of the copied channels, and invalidate the other intervals.
Parameters:
ChannelMask channels
The channels to copy.
Return Value:
A pointer to the shallow copy of the object.
Default Implementation:
{ return NULL; }
Prototype:
virtual void ShallowCopy(Object* fromOb, ChannelMask channels)
Remarks:
Implemented by the Plug-In.
This method copies the specified channels from the fromOb to this and copies the validity intervals.
A plug-in needs to copy the specified channels from the specified object fromOb to itself by just copying pointers (not actually copying the data). No new memory is typically allocated, this method is just copying the pointers.
Parameters:
Object* fromOb
Object to copy the channels from.
ChannelMask channels
Channels to copy.
Prototype:
virtual void NewAndCopyChannels(ChannelMask channels)
Remarks:
Implemented by the Plug-In.
This method replaces the locked channels with newly allocated copies. It will only be called if the channel is locked.
Parameters:
ChannelMask channels
The channels to be allocate and copy.
Prototype:
virtual void FreeChannels(ChannelMask channels)
Remarks:
Implemented by the Plug-In.
This method deletes the memory associated with the specified channels and set the intervals associated with the channels to invalid (empty).
Parameters:
ChannelMask channels
Specifies the channels to free.
Prototype:
Interval GetNoEvalInterval()
Remarks:
This method is used internally.
Prototype:
void SetNoEvalInterval(Interval iv);
Remarks:
This method is used internally.
Prototype:
virtual void ReduceCaches(TimeValue t);
Remarks:
Implemented by the Plug-In.
This method give the object the chance to reduce its caches.
Parameters:
TimeValue t
The time to discard any caches the object has.
Modifier Stack Branching Methods.
Prototype:
virtual int NumPipeBranches(bool selected = true)
Remarks:
Implemented by the Plug-In.
This method returns the number of pipeline branches combined by the object. This is not the total number of branches, but rather the number that are active. For example in the boolean object, if the user does not have any operands selected, this methods would return zero. If they have one selected it would return one.
Parameters:
bool selected = true
This parameter is available in release 4.0 and later only.
This parameter must be supported by all compound objects. In case the selected parameter is true the object should only return the number of pipebranches, that are currently selected in the UI (this is the way it worked in R3 and before. In case this parameter is false, the object has to return the number of all branches, no matter if they are selected or not
Default Implementation:
{return 0;}
Prototype:
virtual Object *GetPipeBranch(int i, bool selected = true)
Remarks:
Implemented by the Plug-In.
Retrieves sub-object branches from an object that supports branching. Certain objects combine a series of input objects (pipelines) into a single object. These objects act as a multiplexer allowing the user to decide which branch(s) they want to see the history for.
It is up to the object how they want to let the user choose. For example the object may use sub-object selection to allow the user to pick a set of objects for which the common history will be displayed.
When the history changes for any reason, the object should send a notification (REFMSG_BRANCHED_HISTORY_CHANGED) via NotifyDependents().
Parameters:
int i
The branch index.
bool selected = true
This parameter is available in release 4.0 and later only.
This parameter must be supported by all compound objects. In case the selected parameter is true the object should only return the number of pipebranches, that are currently selected in the UI (this is the way it worked in R3 and before. In case this parameter is false, the object has to return the number of all branches, no matter if they are selected or not
Return Value:
The 'i-th' sub-object branch.
Default Implementation:
{return NULL;}
Prototype:
virtual INode *GetBranchINode(TimeValue t, INode *node, int i, bool selected = true)
Remarks:
Implemented by the Plug-In.
When an object has sub-object branches, it is likely that the sub-objects are transformed relative to the object. This method gives the object a chance to modify the node's transformation so that operations (like edit modifiers) will work correctly when editing the history of the sub object branch. An object can implement this method by returning a pointer to a new INodeTransformed that is based on the node passed into this method. See Class INodeTransformed.
Parameters:
TimeValue t
The time to get the INode.
INode *node
The original INode pointer.
int i
The branch index.
bool selected = true
This parameter is available in release 4.0 and later only.
This parameter must be supported by all compound objects. In case the selected parameter is true the object should only return the number of pipebranches, that are currently selected in the UI (this is the way it worked in R3 and before. In case this parameter is false, the object has to return the number of all branches, no matter if they are selected or not
Return Value:
A pointer to an INode. This can be the original passed in (the default implementation does this) or a new INodeTransformed.
Default Implementation:
{return node;}
Prototype:
virtual BOOL CanCacheObject()
Remarks:
Implemented by the Plug-In.
This method determines if this object can have channels cached. Particle objects flow up the pipeline without making shallow copies of themselves and therefore cannot be cached. Objects other than particle system can just use the default implementation.
Return Value:
TRUE if the object can be cached; otherwise FALSE.
Default Implementation:
{return TRUE;}
Prototype:
virtual void WSStateInvalidate()
Remarks:
Implemented by the Plug-In.
This is called by a node when the node's world space state has become invalid. Normally an object does not (and should not) be concerned with this, but in certain cases like particle systems an object is effectively a world space object an needs to be notified.
Default Implementation:
{}
Prototype:
virtual BOOL IsWorldSpaceObject()
Remarks:
Implemented by the Plug-In.
Returns TRUE if the object as a world space object; otherwise FALSE. World space objects (particles for example) can not be instanced because they exist in world space not object space. Objects other than particle system can just use the default implementation.
Default Implementation:
{return FALSE;}
Prototype:
virtual Object *FindBaseObject();
Remarks:
Implemented by the Plug-In.
This method moved from IDerivedObject where it was in release 1.x.
It is called to return a pointer to the base object (an object that is not a derived object). This method is overridden by DerivedObjects to search down the pipeline for the base object. The default implementation just returns this. This function is still implemented by derived objects and WSM's to search down the pipeline. This allows you to just call it on a nodes ObjectRef without checking for type.
Default Implementation:
{ return this; }
Prototype:
virtual BOOL IsParamSurface();
Remarks:
Implemented by the Plug-In.
This method is available in release 2.0 and later only.
There are several methods used to access a parametric position on the surface of the object. If this method returns TRUE then Object::GetSurfacePoint() will be called to return a point on the surface that corresponds to the u and v parameters passed to it. If this method returns FALSE then it is assumed the object does not support returning a point on the surface based on parameteric values. For sample code see \MAXSDK\SAMPLES\OBJECTS\SPHERE.CPP. If the object has several parametric surfaces then a second version of GetSurfacePoint() with an integer which specifies which surface will be called.
Default Implementation:
{ return FALSE; }
Prototype:
virtual int NumSurfaces(TimeValue t);
Remarks:
This method is available in release 3.0 and later only.
Returns the number of parametric surfaces within the object. Prior to release 3.0 only one parametric object could be accessed.
Parameters:
TimeValue t
The time at which to check.
Default Implementation:
{return 1;}
Prototype:
virtual Point3 GetSurfacePoint(TimeValue t, float u, float v,Interval &iv);
Remarks:
Implemented by the Plug-In.
This method is available in release 2.0 and later only.
This method needs to be implemented if Object::IsParamSurface() returns TRUE. This method is used to retrieve a point on the surface of the object based on two parameters of the surface, u and v.
Note: This method assumes there is a single parametric surface. If there is more than 1 (NumSurfaces() returns > 1, use the GetSurface() method below which allows for multiple surfaces.
Parameters:
TimeValue t
The time to retrieve the point.
float u
The parameter along the horizontal axis of the surface.
float v
The parameter along the vertical axis of the surface.
Interval &iv
This interval is updated based on the interval of the surface parameter.
Default Implementation:
{return Point3(0,0,0);}
Prototype:
virtual Point3 GetSurfacePoint(TimeValue t, int surface, float u, float v,Interval &iv);
Remarks:
This method is available in release 3.0 and later only.
This method is used to retrieve a point on the specified surface of the object based on two parameters of the surface, u and v.
Parameters:
TimeValue t
The time to retrieve the point.
int surface
The zero based index of the surface. This number is >=0 and <NumSurfaces().
float u
The parameter along the horizontal axis of the surface.
float v
The parameter along the vertical axis of the surface.
Interval &iv
This interval is updated based on the interval of the surface parameter.
Default Implementation:
{return Point3(0,0,0);}
Prototype:
virtual void SurfaceClosed(TimeValue t, int surface, BOOL &uClosed, BOOL &vClosed);
Remarks:
This method is available in release 3.0 and later only.
This method allows the object to return flags that indicate whether the parametric surface is closed in the U and V dimensions. Set the appropriate closure variables to TRUE if the surface is closed in that direction, FALSE if it is not. A torus, for example, is closed in both directions.
Parameters:
TimeValue t
The time to check the surface.
int surface
The zero based index of the surface. This number is >=0 and <NumSurfaces().
BOOL &uClosed
Set to TRUE if the surface is closed in U; otherwise to FALSE.
BOOL &vClosed
Set to TRUE if the surface is closed in V; otherwise to FALSE.
Default Implementation:
{uClosed = vClosed = TRUE;}
Viewport Rectangle Enlargement
Prototype:
virtual void MaybeEnlargeViewportRect(GraphicsWindow *gw, Rect &rect);
Remarks:
This method is available in release 3.0 and later only.
This method allows the object to enlarge its viewport rectangle, if it wants to. The system will call this method for all objects when calculating the viewport rectangle; the object can enlarge the rectangle if desired. This is used by the Editable Spline code to allow extra room for vertex serial numbers, which can extend outside the normal bounding rectangle.
Parameters:
GraphicsWindow *gw
Points to the GraphicsWindow associated with the viewport.
Rect &rect
The enlarged rectangle is returned here.
Default Implementation:
{}
Sample Code:
void SplineShape::MaybeEnlargeViewportRect(GraphicsWindow *gw, Rect &rect) {
if(!showVertNumbers)
return;
TCHAR dummy[256];
SIZE size;
int maxverts = -1;
for(int i = 0; i < shape.splineCount; ++i) {
int verts = shape.splines[i]->KnotCount();
if(verts > maxverts)
maxverts = verts;
}
sprintf(dummy,"%d",maxverts);
gw->getTextExtents(dummy, &size);
rect.SetW(rect.w() + size.cx);
rect.SetY(rect.y() - size.cy);
rect.SetH(rect.h() + size.cy);
}
Prototype:
virtual BOOL GetExtendedProperties(TimeValue t, TSTR &prop1Label, TSTR &prop1Data, TSTR &prop2Label, TSTR &prop2Data);
Remarks:
This method is available in release 3.0 and later only.
This method allows an object to return extended Properties fields. It is called when the Object Properties dialog is being prepared. If you don't want to display any extended properties, simply return FALSE.
To display extended property fields, place the field label in the appropriate label string and the display value in a formatted string. Two fields are supplied, each with a label and a data string; if only using one, make the second label field and data field blank (""). Return TRUE to indicate you have filled in the fields. The properties dialog will display your returned values.
Parameters:
TimeValue t
The time at which the strings are requested.
TSTR &prop1Label
The string for the property 1 label.
TSTR &prop1Data
The formatted data string to appear as property 1.
TSTR &prop2Label
The string for the property 2 label.
TSTR &prop2Data
The formatted data string to appear as property 2.
Return Value:
TRUE if this method is implemented and the fields are filled in; otherwise FALSE.
Default Implementation:
{return FALSE;}
Prototype:
void AddXTCObject(XTCObject *pObj, int priority = 0, int branchID = -1);
Remarks:
This method is available in release 4.0 and later only.
This method adds an extension object into the pipeline.
Implemented by the System.
Parameters:
XTCObject *pObj
Points to the extension object to add.
int priority = 0
The priority of the object. The methods (XTCObject::Display(), PreChanChangedNotify() etc) of higher priority XTCObjects will be called before those of lower priority XTCObjects.
int branchID = -1
The branch identifier of the object.
Prototype:
int NumXTCObjects();
Remarks:
This method is available in release 4.0 and later only.
Returns the number of extension objects maintained by this Object.
Implemented by the System.
Prototype:
XTCObject *GetXTCObject(int index);
Remarks:
This method is available in release 4.0 and later only.
Returns a pointer to the specified extension object.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object to return.
Prototype:
void RemoveXTCObject(int index);
Remarks:
This method is available in release 4.0 and later only.
Removes the extension object as indicated by the index.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object to remove.
Prototype:
void SetXTCObjectPriority(int index,int priority);
Remarks:
This method is available in release 4.0 and later only.
Sets the priority for the extension object whose index is passed.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object to remove.
int priority
The new priority to assign.
Prototype:
int GetXTCObjectPriority(int index);
Remarks:
This method is available in release 4.0 and later only.
Returns the integer priority number of the extension object whose index is passed.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object to check.
Prototype:
void SetXTCObjectBranchID(int index,int branchID);
Remarks:
This method is available in release 4.0 and later only.
Sets the branch ID of the extension object whose index is passed.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object whose branch ID is set.
int branchID
The branch identifier to set.
Prototype:
int GetXTCObjectBranchID(int index);
Remarks:
This method is available in release 4.0 and later only.
Returns the integer branch ID of the extension object whose index is passed.
Implemented by the System.
Parameters:
int index
The zero based index of the extension object whose branch ID is to be returned.
Prototype:
void MergeAdditionalChannels(Object *from, int branchID);
Remarks:
This method is available in release 4.0 and later only.
This method has to be called whenever the CompoundObject updates a branch (calling Eval() on it). Object *from is the object returned from Eval(os.obj). The branchID is an integer that specifies that branch. The extension channel will get a callback to XTCObject::RemoveXTCObjectOnMergeBranches() and XTCObject::MergeXTCObject(). By default it returns true to RemoveXTCObjectOnMergeBranches which means that the existing XTCObjects with that branchID will be deleted. The method MergeXTCObject simply copies the XTCObjects from the incoming branch into the compound object.
Implemented by the System.
Parameters:
Object *from
The object to merge additional channels from.
int branchID
The branch identifier to set.
Prototype:
void BranchDeleted(int branchID, bool reorderChannels);
Remarks:
This method is available in release 4.0 and later only.
This method has to be called on the CompoundObject so it can delete the XTCObjects for the specified branch. The XTCObject will again have the final decision if the XTCObject gets really deleted or not in a callback to XTCObject::RemoveXTCObjectOnBranchDeleted() which will return true if the XTCOject should be removed.
Implemented by the System.
Parameters:
int branchID
Specifies which brach of the compound object the extension objects are deleted from.
bool reorderChannels
TRUE to reorder the channels, otherwise FALSE.
Prototype:
void CopyAdditionalChannels(Object *from, bool deleteOld = true, bool bShallowCopy = false);
Remarks:
This method is available in release 4.0 and later only.
This method copies all extension objects from the "from" object into the current object. In case deleteOld is false the objects will be appended. If it is true the old XTCObjects will be deleted.
Implemented by the System.
Parameters:
Object *from
The source object which contains extension objects.
bool deleteOld = true
If true the original objects are deleted after the copy; if false they remain after the copy.
bool bShallowCopy = false
If true only a ShallowCopy() is performed; if false a complete copy of the objects is done.
Prototype:
void DeleteAllAdditionalChannels();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
This method will delete all additional channels.
The following function is not part of this class but is available for use:
Function:
void GetPolygonCount(TimeValue t, Object* pObj, int& numFaces, int& numVerts);
Remarks:
This global function is available in release 3.0 and later only.
This global function (not part of class Object) may be used to count the number of faces and vertices in an object. It uses Object::PolygonCount() if it is supported, and converts to TriObject and counts faces and vertices otherwise.
Parameters:
TimeValue t
The time at which to compute the number of faces and vertices.
Object* pObj
Points to the object to check.
int& numFaces
The number of faces is returned here.
int& numVerts
The number of vertices is returned here.