This reference page is linked to from the following overview topics: Particle System Plug-ins, Plug-in Base Classes.

Detailed Description

See also:: Class ParticleObject, Marker Types, Class Mesh, Class ParticleSys, Class Interval, Template Class Tab, Class ParamDimension,.

Description:: This class provides a base class from which you may derive Particle System plug-ins. This class may be used by particle systems that fit within its form. The form is primarily dictated by the data members maintain by the class. The class maintains an instance of class ParticleSys that describes the particles. It also has a table of force fields and collision objects. The emitter for the particles is represented by a mesh. There is also a parameter block pointer available.

Particle system plug-ins that don't fit this form may derive from a base class without any constraints. See Class ParticleObject for more details.

Data Members:: IParamBlock *pblock;

The parameter block pointer.

ParticleSys parts;

This is a description of the particles themselves (their count, position, velocities, ...).

TimeValue tvalid;

A particle system derived from SimpleParticle is valid at a particular time only (it does not have a validity interval). It is assumed to be always changing. This data member holds the time at which it is valid (when valid is TRUE).

BOOL valid;

This flag indicates if the particle system is valid. If TRUE, tvalid should contain the time it is valid for.

Tab<ForceField*> fields;

The table of force fields affecting the particles.

Tab<CollisionObject*> cobjs;

The table of collision objects affecting the particles.

Mesh mesh;

The mesh object that represents the emitter.

Interval mvalid;

The validity interval for the emitter mesh. If the mesh is invalid BuildEmitter() will be called.

static SimpleParticle *editOb;

The SimpleParticle object that is being edited between BeginEditParams() and EndEditParams().

static IObjParam *ip;

Storage for the interface pointer passed into BeginEditParams(). This pointer is only valid between BeginEditParams() and EndEditParams().

#include <simpobj.h>

Inheritance diagram for SimpleParticle:

[legend]

List of all members.

Public Member Functions
CoreExport	SimpleParticle ()
CoreExport	~SimpleParticle ()
CoreExport void	Update (TimeValue t, INode *node=NULL)
CoreExport void	UpdateMesh (TimeValue t)
CoreExport void	GetBBox (TimeValue t, Matrix3 &tm, Box3 &box)
void	MeshInvalid ()
void	ParticleInvalid ()
CoreExport void	BeginEditParams (IObjParam ip, ULONG flags, Animatable prev)
CoreExport void	EndEditParams (IObjParam ip, ULONG flags, Animatable next)
CoreExport int	HitTest (TimeValue t, INode inode, int type, int crossing, int flags, IPoint2 p, ViewExp *vpt)
	This method is called to determine if the specified screen point intersects the item.
CoreExport int	Display (TimeValue t, INode inode, ViewExp vpt, int flags)
	This is called by the system to have the item display itself (perform a quick render in viewport, using the current TM).
CoreExport IParamArray *	GetParamBlock ()
	An object or modifier should implement this method if it wishes to make its parameter block available for other plug-ins to access it.
CoreExport int	GetParamBlockIndex (int id)
	If a plug-in makes its parameter block available (using GetParamBlock()) then it will need to provide #defines for indices into the parameter block.
int	DoOwnSelectHilite ()
	If an object wants to draw itself in the 3D viewports in its selected state in some custom manner this method should return nonzero.
CoreExport ObjectState	Eval (TimeValue time)
	This method is called to evaluate the object and return the result as an ObjectState.
void	InitNodeName (MSTR &s)
	This is the default name of the node when it is created.
CoreExport Interval	ObjectValidity (TimeValue t)
	This method returns the validity interval of the object as a whole at the specified time.
CoreExport int	CanConvertToType (Class_ID obtype)
	Indicates whether the object can be converted to the specified type.
CoreExport Object *	ConvertToType (TimeValue t, Class_ID obtype)
	This method converts this object to the type specified and returns a pointer it.
CoreExport Object *	MakeShallowCopy (ChannelMask channels)
	This method must make a copy of its "shell" and then shallow copy (see below) only the specified channels.
void	WSStateInvalidate ()
	This is called by a node when the node's world space state has become invalid.
BOOL	IsWorldSpaceObject ()
	Returns TRUE if the object as a world space object; otherwise FALSE.
CoreExport void	GetWorldBoundBox (TimeValue t, INode inode, ViewExp vpt, Box3 &box)
	This method returns the world space bounding box for Objects (see below for the Sub-object gizmo or Modifiers gizmo version).
CoreExport void	GetLocalBoundBox (TimeValue t, INode inode, ViewExp vpt, Box3 &box)
	This is the object space bounding box, the box in the object's local coordinates.
CoreExport void	GetDeformBBox (TimeValue t, Box3 &box, Matrix3 *tm, BOOL useSel)
	This method computes the bounding box in the objects local coordinates or the optional space defined by tm.
CoreExport void	ApplyForceField (ForceField *ff)
	This method is called to add the force field object passed to the list of force field objects operating on this particle system.
CoreExport BOOL	ApplyCollisionObject (CollisionObject *co)
	This method is called to add the collision object passed to the list of collision objects operating on this particle system.
CoreExport TimeValue	ParticleAge (TimeValue t, int i)
	Returns the age of the specified particle -- the length of time it has been 'alive'.
CoreExport void	SetParticlePosition (TimeValue t, int i, Point3 pos)
CoreExport void	SetParticleVelocity (TimeValue t, int i, Point3 vel)
CoreExport void	SetParticleAge (TimeValue t, int i, TimeValue age)
void	GetClassName (MSTR &s)
	Retrieves the name of the plugin class.
int	NumSubs ()
Animatable *	SubAnim (int i)
CoreExport MSTR	SubAnimName (int i)
CoreExport void *	GetInterface (ULONG id)
	Inherited from Animatable.
int	NumRefs ()
	Returns the total number of references this ReferenceMaker can hold.
RefTargetHandle	GetReference (int i)
	Returns the 'i-th' reference.
CoreExport RefResult	NotifyRefChanged (Interval changeInt, RefTargetHandle hTarget, PartID &partID, RefMessage message)
	Receives and responds to messages.
virtual void	UpdateParticles (TimeValue t, INode *node)=0
virtual void	BuildEmitter (TimeValue t, Mesh &amesh)=0
virtual Interval	GetValidity (TimeValue t)=0
virtual MarkerType	GetMarkerType ()
virtual BOOL	OKtoDisplay (TimeValue t)
virtual BOOL	EmitterVisible ()
virtual void	InvalidateUI ()
virtual ParamDimension *	GetParameterDim (int pbIndex)
virtual MSTR	GetParameterName (int pbIndex)
Public Attributes
IParamBlock *	pblock
ParticleSys	parts
TimeValue	tvalid
BOOL	valid
Tab< ForceField * >	fields
Tab< CollisionObject * >	cobjs
Mesh	mesh
Interval	mvalid
MetaParticle	metap
Static Public Attributes
static CoreExport SimpleParticle *	editOb
static CoreExport IObjParam *	ip
Protected Member Functions
virtual void	SetReference (int i, RefTargetHandle rtarg)
	Stores a ReferenceTarget as its 'i-th' reference`.

Constructor & Destructor Documentation

CoreExport SimpleParticle ( )

Remarks:: Constructor. The pblock is initialized to NULL, the mvalid interval is set to empty, and valid is set to FALSE.

CoreExport ~SimpleParticle ( )

Member Function Documentation

CoreExport void Update	(	TimeValue	t,
		INode *	node = `NULL`
	)

Search for all occurrences

CoreExport void UpdateMesh ( TimeValue t )

Search for all occurrences

CoreExport void GetBBox	(	TimeValue	t,
		Matrix3 &	tm,
		Box3 &	box
	)

Search for all occurrences

void MeshInvalid ( ) [inline]

Search for all occurrences

{mvalid.SetEmpty();}

void ParticleInvalid ( ) [inline]

Search for all occurrences

{valid=FALSE;}

CoreExport void BeginEditParams	(	IObjParam *	ip,
		ULONG	flags,
		Animatable *	prev
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is called by the system when the user may edit the item's (object, modifier, controller, etc.) parameters.

Parameters:

ip	Interface pointer. The developer can use it to call methods such as AddRollupPage(). Note that this pointer is only valid between BeginEditParams() and EndEditParams(). It should not be used outside this interval.
flags	Describe which branch of the command panel or dialog the item is being edited in. The following are possible values: BEGIN_EDIT_CREATE Indicates an item is being edited in the create branch. BEGIN_EDIT_MOTION Indicates a controller is being edited in the motion branch. BEGIN_EDIT_HIERARCHY Indicates a controller is being edited in the Pivot subtask of the hierarchy branch. BEGIN_EDIT_IK Indicates a controller is being edited in the IK subtask of the hierarchy branch. BEGIN_EDIT_LINKINFO Indicates a controller is being edited in the Link Info subtask of the hierarchy branch.
prev	Pointer to an Animatable object. This parameter may be used in the motion and hierarchy branches of the command panel. This pointer allows a plug-in to look at the ClassID of the previous item that was being edited, and if it is the same as this item, to not replace the entire UI in the command panel, but simply update the values displayed in the UI fields. This prevents the UI from 'flickering' when the current item begins its edit. For example, if you are in the motion branch and are looking at an item's PRS controller values, and then select another item that is displayed with a PRS controller, the UI will not change - only the values displayed in the fields will change. If however you selected a target camera that has a lookat controller (not a PRS controller) the UI will change because a different set of parameters need to be displayed. Note that for items that are edited in the modifier branch this field can be ignored.

Reimplemented from Animatable.

CoreExport void EndEditParams	(	IObjParam *	ip,
		ULONG	flags,
		Animatable *	next
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is called when the user is finished editing an objects parameters. The system passes a flag into the EndEditParams() method to indicate if the rollup page should be removed. If this flag is TRUE, the plug-in must un-register the rollup page, and delete it from the panel.

Parameters:

ip	An interface pointer. The developer may use the interface pointer to call methods such as DeleteRollupPage().
flags	The following flag may be set: END_EDIT_REMOVEUI If TRUE, the item's user interface should be removed.
next	Animatable pointer. Can be used in the motion and hierarchy branches of the command panel. It allows a plug-in to look at the ClassID of the next item that was being edited, and if it is the same as this item, to not replace the entire UI in the command panel. Note that for items that are edited in the modifier branch this field can be ignored.

Reimplemented from Animatable.

CoreExport int HitTest	(	TimeValue	t,
		INode *	inode,
		int	type,
		int	crossing,
		int	flags,
		IPoint2 *	p,
		ViewExp *	vpt
	)		`[virtual]`

Search for all occurrences

This method is called to determine if the specified screen point intersects the item.

The method returns nonzero if the item was hit; otherwise 0.

Parameters:

t	The time to perform the hit test.
inode	A pointer to the node to test.
type	The type of hit testing to perform. See Scene and Node Hit Test Types. for details.
crossing	The state of the crossing setting. If TRUE crossing selection is on.
flags	The hit test flags. See Scene and Node Hit Testing Flags for details.
p	The screen point to test.
vpt	An interface pointer that may be used to call methods associated with the viewports.

Returns:: Nonzero if the item was hit; otherwise 0.

Reimplemented from BaseObject.

CoreExport int Display	(	TimeValue	t,
		INode *	inode,
		ViewExp *	vpt,
		int	flags
	)		`[virtual]`

Search for all occurrences

This is called by the system to have the item display itself (perform a quick render in viewport, using the current TM).

Note: For this method to be called the object's validity interval must be invalid at the specified time t. If the interval is valid, the system may not call this method since it thinks the display is already valid.

Parameters:

t	The time to display the object.
inode	The node to display.
vpt	An interface pointer that may be used to call methods associated with the viewports.
flags	See Display Flags.

Returns:: The return value is not currently used.

Reimplemented from BaseObject.

CoreExport IParamArray* GetParamBlock ( ) [virtual]

Search for all occurrences

An object or modifier should implement this method if it wishes to make its parameter block available for other plug-ins to access it.

The system itself doesn't actually call this method. This method is optional.

Returns:: A pointer to the item's parameter block. See Class IParamArray.

Reimplemented from BaseObject.

CoreExport int GetParamBlockIndex ( int id ) [virtual]

Search for all occurrences

If a plug-in makes its parameter block available (using GetParamBlock()) then it will need to provide #defines for indices into the parameter block.

These defines should not be directly used with the parameter block but instead converted by this function that the plug-in implements. This way if a parameter moves around in a future version of the plug-in the #define can be remapped. A return value of -1 indicates an invalid parameter id.

Parameters:

id	The parameter block id. See Parameter Block IDs.

Returns:: The parameter block index or -1 if it is invalid.

Reimplemented from BaseObject.

int DoOwnSelectHilite ( ) [inline, virtual]

Search for all occurrences

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.

Returns:: 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.

Reimplemented from Object.

{return TRUE;}

CoreExport ObjectState Eval ( TimeValue t ) [virtual]

Search for all occurrences

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:

t	Specifies the time to evaluate the object.

Returns:: The result of evaluating the object as an ObjectState.

Sample Code:

Typically this method is implemented as follows:

    { return ObjectState(this); }

Implements Object.

void InitNodeName ( MSTR & s ) [inline, virtual]

Search for all occurrences

This is the default name of the node when it is created.

Parameters:

s	The default name of the node is stored here.

Reimplemented from GeomObject.

{s = GetObjectName();}

CoreExport Interval ObjectValidity ( TimeValue t ) [virtual]

Search for all occurrences

This method returns the validity interval of the object as a whole at the specified time.

Parameters:

t	The time to compute the validity interval.

Default Implementation:: { return FOREVER; }

Returns:: The validity interval of the object.

Reimplemented from Object.

CoreExport int CanConvertToType ( Class_ID obtype ) [virtual]

Search for all occurrences

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().

See also:: Class ObjectConverter for additional details on converting objects between types.

Parameters:

obtype The Class_ID of the type of object to convert to. See Class Class_ID, List of Class_IDs.

Returns:: Nonzero if the object can be converted to the specified type; otherwise 0.

Default Implementation:: { return 0; }

Reimplemented from Object.

CoreExport Object* ConvertToType	(	TimeValue	t,
		Class_ID	obtype
	)		`[virtual]`

Search for all occurrences

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.

See also:: 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:

t	The time at which to convert.
obtype	The Class_ID of the type of object to convert to. See Class Class_ID, List of Class_IDs.

Returns:: 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;
        }
    }

Reimplemented from Object.

CoreExport Object* MakeShallowCopy ( ChannelMask channels ) [virtual]

Search for all occurrences

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:

channels The channels to copy.

Returns:: A pointer to the shallow copy of the object.

Reimplemented from Object.

void WSStateInvalidate ( ) [inline, virtual]

Search for all occurrences

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.

Reimplemented from Object.

{valid = FALSE;}

BOOL IsWorldSpaceObject ( ) [inline, virtual]

Search for all occurrences

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.

Reimplemented from Object.

{return TRUE;}

CoreExport void GetWorldBoundBox	(	TimeValue	t,
		INode *	inode,
		ViewExp *	vp,
		Box3 &	box
	)		`[virtual]`

Search for all occurrences

This method returns the world space bounding box for Objects (see below for the Sub-object gizmo or Modifiers gizmo version).

The bounding box returned by this method does not need to be precise. It should however be calculated rapidly. The object can handle this by transforming the 8 points of its local bounding box into world space and take the minimums and maximums of the result. Although this isn't necessarily the tightest bounding box of the objects points in world space, it is close enough.

Parameters:

t	The time to compute the bounding box.
inode	The node to calculate the bounding box for.
vp	An interface pointer that can be used to call methods associated with the viewports.
box	Contains the returned bounding box.

Reimplemented from BaseObject.

CoreExport void GetLocalBoundBox	(	TimeValue	t,
		INode *	inode,
		ViewExp *	vp,
		Box3 &	box
	)		`[virtual]`

Search for all occurrences

This is the object space bounding box, the box in the object's local coordinates.

The system expects that requesting the object space bounding box will be fast.

Parameters:

t	The time to retrieve the bounding box.
inode	The node to calculate the bounding box for.
vp	An interface pointer that may be used to call methods associated with the viewports.
box	Contains the returned bounding box.

Reimplemented from BaseObject.

CoreExport void GetDeformBBox	(	TimeValue	t,
		Box3 &	box,
		Matrix3 *	tm,
		BOOL	useSel
	)		`[virtual]`

Search for all occurrences

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:

t	The time to compute the box.
box	A reference to a box the result is stored in.
tm	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.
useSel	If TRUE, the bounding box of selected sub-elements should be computed; otherwise the entire object should be used.

Reimplemented from Object.

CoreExport void ApplyForceField ( ForceField * ff ) [virtual]

Search for all occurrences

This method is called to add the force field object passed to the list of force field objects operating on this particle system.

Parameters:

ff	Points to an instance of a ForceField object.

Sample Code:

    void SimpleParticle::ApplyForceField(ForceField *ff)
    {
        fields.Append(1,&ff);
    }

Implements ParticleObject.

CoreExport BOOL ApplyCollisionObject ( CollisionObject * co ) [virtual]

Search for all occurrences

This method is called to add the collision object passed to the list of collision objects operating on this particle system.

Parameters:

co	Points to an instance of a collision object.

Returns:: If a particle does not support this method it should return FALSE; otherwise return TRUE.

Sample Code:

    BOOL SimpleParticle::ApplyCollisionObject(CollisionObject *co)
    {
        cobjs.Append(1,&co);
        return TRUE;
    }

Implements ParticleObject.

CoreExport TimeValue ParticleAge	(	TimeValue	t,
		int	i
	)		`[virtual]`

Search for all occurrences

Returns the age of the specified particle -- the length of time it has been 'alive'.

The Particle Age texture map and the Particle Motion Blur texture map use this method.

Parameters:

t	Specifies the time to compute the particle age.
i	The index of the particle.

Reimplemented from ParticleObject.

CoreExport void SetParticlePosition	(	TimeValue	t,
		int	i,
		Point3	pos
	)

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

Sets the position of the specified particle at the specified time.

Parameters:: TimeValue t

The time at which to set the particle position.

int i

The zero based index of the particle to set.

Point3 pos

The position to set.

CoreExport void SetParticleVelocity	(	TimeValue	t,
		int	i,
		Point3	vel
	)

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

Sets the velocity of the specified particle at the specified time (in 3ds Max units per tick).

Parameters:: TimeValue t

The time at which to set the particle velocity.

int i

The zero based index of the particle to set.

Point3 vel

The velocity to set.

CoreExport void SetParticleAge	(	TimeValue	t,
		int	i,
		TimeValue	age
	)

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

Sets the age of the specified particle at the specified time.

Parameters:: TimeValue t

The time at which to set the particle age.

int i

The zero based index of the particle to set.

TimeValue age

The age to set.

void GetClassName ( MSTR & s ) [inline, virtual]

Search for all occurrences

Retrieves the name of the plugin class.

This name is usually used internally for debugging purposes. For Material plug-ins this method is used to put up the material "type" name in the Material Editor.

Parameters:

s	Reference to a string filled in with the name of the plugin class

Reimplemented from ReferenceTarget.

{s = GetObjectName();}

int NumSubs ( ) [inline, virtual]

Search for all occurrences

Remarks:: The system uses a virtual array mechanism to access the sub-anims of a plug-in. This method returns the total number of sub-anims maintained by the plug-in. If a plug-in is using a parameter block to manage its parameters it should just return 1 for all the parameters directed by the parameter block.

Returns:: The number of sub-anims used by the plug-in.

Default Implementation:: { return 0; }

Reimplemented from Animatable.

{return 1;}

Animatable* SubAnim ( int i ) [inline, virtual]

Search for all occurrences

Remarks:: This method returns a pointer to the 'i-th' sub-anim. If a plug-in is using a parameter block to manage all its parameters it should just return a pointer to the parameter block itself from this method. This method may return NULL so developers need to check the return value before calling other sub anim methods (such as SubAnimName()).

Parameters:

i	This is the index of the sub-anim to return.

Default Implementation:: { return NULL };

Reimplemented from Animatable.

{ return (Animatable*)pblock; }

CoreExport MSTR SubAnimName ( int i ) [virtual]

Search for all occurrences

Remarks:: This method returns the name of the 'i-th' sub-anim to appear in track view. The system has no idea what name to assign to the sub-anim (it only knows it by the virtual array index), so this method is called to retrieve the name to display. Developer need to make sure the 'i-th' SubAnim() is non-NULL or this method will fail.

Parameters:

i	The index of the parameter name to return

Returns:: The name of the 'i-th' parameter.

Reimplemented from Animatable.

CoreExport void* GetInterface ( ULONG id ) [virtual]

Search for all occurrences

Inherited from Animatable.

Returns a pointer to the interface.

Parameters:

id	- The id of the interface.

Returns:: A Pointer to the Interface

Reimplemented from Object.

int NumRefs ( ) [inline, virtual]

Search for all occurrences

Returns the total number of references this ReferenceMaker can hold.

The plugin implements this method to indicate the total number of of references it can make. This includes all references whether they are NULL (inactive) or non-NULL (active) at the time when this method is called. A plugin can hold a variable number of references, thus the return value of this method is not to be cached and reused by client code.

Returns:: The total number of references this plugin can hold. The default implementation is return 0.

Reimplemented from ReferenceMaker.

{return 1;}

RefTargetHandle GetReference ( int i ) [inline, virtual]

Search for all occurrences

Returns the 'i-th' reference.

The plugin implements this method to return its 'i-th' reference. The plug-in simply keeps track of its references using an integer index for each one. This method is normally called by the system.

Parameters:

i	- The index of the reference to retrieve. Valid values are from 0 to NumRefs()-1.

Returns:: The reference handle of the 'i-th' reference. Note that different calls to this method with the same 'i' value can result in different reference handles being retrieved, as the plugin changes the scene objects it references as its 'i-th' reference.

Reimplemented from ReferenceMaker.

{return (RefTargetHandle)pblock;}

virtual void SetReference	(	int	i,
		RefTargetHandle	rtarg
	)		`[inline, protected, virtual]`

Search for all occurrences

Stores a ReferenceTarget as its 'i-th' reference`.

The plugin implements this method to store the reference handle passed to it as its 'i-th' reference. In its implementation of this method, the plugin should simply assign the reference handle passed in as a parameter to the member variable that holds the 'i-th' reference. Other reference handling methods such as ReferenceMaker::DeleteReference(), or ReferenceMaker::ReplaceReference() should not be called from within this method. The plugin itself or other plugins should not call this method directly. The system will call this method when a new reference is created or an existing one is replaced by calling ReferenceMaker::ReplaceReference().

Parameters:

i	- The index of the reference to store. Valid values are from 0 to NumRefs()-1.
rtarg	- The reference handle to store.

Reimplemented from ReferenceMaker.

{pblock=(IParamBlock*)rtarg;}

CoreExport RefResult NotifyRefChanged	(	Interval	changeInt,
		RefTargetHandle	hTarget,
		PartID &	partID,
		RefMessage	message
	)		`[virtual]`

Search for all occurrences

Receives and responds to messages.

A plugin which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged(). The plugin developer usually implements this method as a switch statement where each case is one of the messages the plugin needs to respond to. The Method StdNotifyRefChanged calls this, which can change the partID to new value. If it doesn't depend on the particular message& partID, it should return REF_DONTCARE.

For developer that need to update a dialog box with data about an object you reference note the following related to this method: This method may be called many times. For instance, say you have a dialog box that displays data about an object you reference. This method will get called many time during the drag operations on that object. If you updated the display every time you'd wind up with a lot of 'flicker' in the dialog box. Rather than updating the dialog box each time, you should just invalidate the window in response to the NotifyRefChanged() call. Then, as the user drags the mouse your window will still receive paint messages. If the scene is complex the user may have to pause (but not let up on the mouse) to allow the paint message to go through since they have a low priority. This is the way many windows in 3ds Max work.

Parameters:

changeInt	- This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.
hTarget	- This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message.
partID	- This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages.
message	- The message parameters passed into this method is the specific message which needs to be handled.

Returns:: The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.

Implements ReferenceMaker.

virtual void UpdateParticles	(	TimeValue	t,
		INode *	node
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This method is called so the particle system can update its state to reflect the current time passed. This may involve generating new particle that are born, eliminating old particles that have expired, computing the impact of collisions or force field effects, and modify the positions and velocities of the particles.

Parameters:: TimeValue t

The particles should be updated to reflect this time.

INode *node

This is the emitter node. Particles system are world space objects so they are not instanced. This means that the particle system can depend on the node's world space position.

Sample Code:: For example code see /MAXSDK/SAMPLES/OBJECTS/RAIN.CPP.

virtual void BuildEmitter	(	TimeValue	t,
		Mesh &	amesh
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This method is called to allow the plug-in to provide a representation of its emitter in the 3D viewports.

Parameters:: TimeValue t

Specifies the time to build the emitter.

Mesh& amesh

Store the built mesh representation here.

virtual Interval GetValidity ( TimeValue t ) [pure virtual]

Search for all occurrences

Remarks:: This method is called to retrieve the validity time of the particle system emitter.

Parameters:: TimeValue t

The time to compute the validity interval.

Returns:: The validity interval of the particle system emitter at the specified time.

virtual MarkerType GetMarkerType ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns one of the defined marker types to use when displaying particles.

Returns:: One of the following values:

See Marker Types.

Default Implementation:: {return POINT_MRKR;}

{return POINT_MRKR;}

virtual BOOL OKtoDisplay ( TimeValue t ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called to determine if the particle emitter is okay to display at the specified time. If at certain times it is not okay to display this method should return FALSE. This might occur if a size goes to 0. Normally however it is always okay to display so the default implementation returns TRUE.

Parameters:: TimeValue t

The time to display the emitter.

Returns:: TRUE if it is okay to display, FALSE otherwise.

Default Implementation:: {return TRUE;}

{return TRUE;}

virtual BOOL EmitterVisible ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called to determine if the particle emitter is visible in the viewports. If the plug-in provides a UI control to toggle the emitter on and off, this method should return the state of this control.

Returns:: TRUE if the emitter is visible; otherwise FALSE.

Default Implementation:: {return TRUE;}

{return TRUE;}

virtual void InvalidateUI ( ) [inline, virtual]

Search for all occurrences

Remarks:: It is important the user interface controls display values that reflect the current time. This method is called if the user interface parameters needs to be updated because the user moved to a new time.

Example:: If the plug-in uses a parameter map for handling its UI, it may call a method of the parameter map to handle this: pmapParam->Invalidate();

If the plug-in does not use parameter maps, it should call the SetValue() method on each of its controls that display a value, for example the spinner controls. This will cause to the control to update the value displayed. The code below shows how this may be done for a spinner control. Note that ip and pblock are assumed to be initialized interface and parameter block pointers

(IObjParam *ip, IParamBlock *pblock).

float newval;

Interval valid=FOREVER;

TimeValue t=ip->GetTime();

// Get the value from the parameter block at the current time.

pblock->GetValue( PB_ANGLE, t, newval, valid );

// Set the value. Note that the notify argument is passed as FALSE.

// This ensures no messages are sent when the value changes.

angleSpin->SetValue( newval, FALSE );