#include <xtcobject.h>

Class Description

See also: Class InterfaceServer, Class Class_ID, Class ModContext, Class ObjectState, Class INode, Class Object, Class Modifier, Class GraphicsWindow, Class FPInterface, List of Channel Bits, Class XTCContainer, Class IXTCAccess

Description:: This is the base class for an Extension Channel plug-in. These plug-ins are used to allow a developer defined object to flow down the geometry pipeline. This class provides an interface to the extension object. This is the virtual base class that developers can derive objects from, that should be inserted into the extension channel of the object flowing up the stack. Extension Channels will expand the geometry pipeline by allowing one to add a custom object to the pipeline object that can flow down the pipeline. This object will get notified whenever something in the pipeline changes. For example, if you want to indicate when a certain object becomes invalid for export to their game engine, invalid skin-vertex assignments, bound patches etc. By inserting an Extension Channel Object (XTCObject, for short) into the pipeline you can accomplish this, by constantly checking the structure of the object and displaying wrong faces/vertices etc. in the viewport.

You can specify which other channels it depends on using DependsOn(). The extension object has callback methods that get called before and after a modifier modifies a channel that the extension object depends on using PreChanChangedNotify() and PostChanChangedNotify(). The extension object can declare additional channels that it modifies using ChannelsChanged(), so that it can make any changes to the mesh before and after the modification by the modifier.

In general, the Extension Channel is a transient data structure that gets recreated on every pipeline evaluation. So the object that adds an extension channel to the modifier stack automatically makes it persistent. However, when the user collapses the stack, the user might want the Extension Channel to be preserved as well. In order to accomplish that, please refer to the Class BaseObject and the methods NotifyPreCollapse() and NotifyPostCollapse(). These methods will be called by the collapse code. It will give the modifier or BaseObject, that adds an XTC object to the stack the possibility to apply a modifier, that inserts these XTC objects onto the stack after the collapse. Through this mechanism, the XTC will survive a stack collapse. The Pre and Post notifications will be called through a pipeline enumeration downstream (for more info see Class GeomPipelineEnumProc). Developers, who are collapsing the stack programmatically, have to call this method. In case this method is not called, the XTC objects will by default be copied as well, since they are part of the object in the wsCache. However, they won't survive a save/load operation. In addition to all this, XTC objects also have the possibility to display their data in the viewports. Any Extension Channel Object can disable the display of the object itself and take over the entire display itself, by returning true in the method SuspendObjectDisplay().

Note: Modifiers which change the type of object that flows up the stack have to copy the Extension Channel from the old object into the new one using CopyAdditionalChannels() (e.g. the extrude modifier has to copy the XTC from the incoming spline to the Mesh, Patch or NURBS object).

Note: Compound objects have to merge the Extension Channel of the branched pipelines into the resulting pipeline. This is in general a simple copy of the Extension Channel Object into the new Extension Channel. When the CompoundObject evaluates is branches it would call CopyAdditionalChannels(os->obj), so that the Extension Channels of the branches are copied over. In the ConvertToType() method it then has to copy the Extension Channels from itself to the converted object using obj->CopyAdditionalChannels(this).

Also note that the Extension Channel itself is implemented in Class Object. This means, that it will be available for all pipeline objects that get implemented in 3ds Max. For additional methods related to extension objects see the methods in Class Object -> Extension Channel Access.

All methods of this class are virtual. Default implementations are shown.

Inheritance diagram for XTCObject:

Public Member Functions
virtual Class_ID	ExtensionID ()=0

virtual XTCObject *	Clone ()=0

virtual ChannelMask	DependsOn ()

virtual ChannelMask	ChannelsChanged ()

virtual ChannelMask	ChannelsUsed ()

virtual int	Display (TimeValue t, INode inode, ViewExp vpt, int flags, Object *pObj)

virtual void	PreChanChangedNotify (TimeValue t, ModContext &mc, ObjectState os, INode node, Modifier *mod, bool bEndOfPipeline)

virtual void	PostChanChangedNotify (TimeValue t, ModContext &mc, ObjectState os, INode node, Modifier *mod, bool bEndOfPipeline)

virtual BOOL	SuspendObjectDisplay ()

virtual void	DeleteThis ()=0

virtual void	MaybeEnlargeViewportRect (GraphicsWindow *gw, Rect &rect)

virtual bool	RemoveXTCObjectOnMergeBranches (Object obFrom, Object obTo)

virtual bool	MergeXTCObject (Object obFrom, Object obTo, int prio, int branchID)

virtual bool	RemoveXTCObjectOnBranchDeleted (Object *ComObj, int branchID, bool branchWillBeReordered)

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...

static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...

static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void ptr, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void ptr, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, int block_type, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void ptr, const std::nothrow_t &e, const char filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...

static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...

static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...

static UtilExport void	operator delete (void ptr, void placement_ptr)
	Placement delete operator. More...

static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...

static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...

static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Member Function Documentation

virtual Class_ID ExtensionID ( )

pure virtual

Remarks: This method returns the unique identifier for the object.

Implemented in TriObjectNormalXTC.

virtual XTCObject* Clone ( )

pure virtual

Remarks: This method is called to create a cloned copy of the object. The object should create a copy of itself and return a pointer to it.

Implemented in TriObjectNormalXTC.

virtual ChannelMask DependsOn ( )

inlinevirtual

Remarks: This method returns a ChannelMask which specifies the channels that the XTCObject depends on. If a modifier changes a channel that a XTCObject depends on, its PreChanChangedNotify() and PostChanChangedNotify() methods will be called.

Returns: See Object Channels.

Default Implementation:: { return 0; }

Reimplemented in TriObjectNormalXTC.

110 {return 0;}

virtual ChannelMask ChannelsChanged ( )

inlinevirtual

Remarks: This method returns a ChannelMask which specifies the channels that the extension object changes in the PreChanChangedNotify() and PostChanChangedNotify() methods.

Returns: See Object Channels.

Default Implementation:: { return 0; }

Reimplemented in TriObjectNormalXTC.

120 {return 0;}

virtual ChannelMask ChannelsUsed ( )

inlinevirtual

Remarks: This method returns a ChannelMask which specifies the channels that the extension object uses in the PreChanChangedNotify() and PostChanChangedNotify() methods.

Returns: See Object Channels.

Default Implementation:: { return 0; }

130 {return 0;}

virtual int Display	(	TimeValue	t,
		INode *	inode,
		ViewExp *	vpt,
		int	flags,
		Object *	pObj
	)

inlinevirtual

Remarks: If an XTCObject wants to display itself in the viewport it can overwrite this method.

Parameters:: TimeValue t

The time at which the object is to be displayed.

INode* inode

Points to the node for the object.

ViewExp *vpt

Points to the viewport interface for the object.

int flags

See Display Flags.

Object *pObj

Points to the object that the extension object is a part of.

Returns: The return value is not currently used.

Default Implementation:: { return 0; }

152 {return 0;};

virtual void PreChanChangedNotify	(	TimeValue	t,
		ModContext &	mc,
		ObjectState *	os,
		INode *	node,
		Modifier *	mod,
		bool	bEndOfPipeline
	)

inlinevirtual

Remarks: This method is called before a modifier is applied that changes a channel that the XTCObject depends on.

Parameters:: TimeValue t

The time at which the channel will be modified.

ModContext &mc

The modifier context.

ObjectState* os

The objectstate of the object.

INode *node

A pointer to the node.

Modifier *mod

A pointer to the modifier being applied.

bool bEndOfPipeline

TRUE to indicate that this is the last change before the wsCache.

Default Implementation:: { }

Reimplemented in TriObjectNormalXTC.

176 {};

virtual void PostChanChangedNotify	(	TimeValue	t,
		ModContext &	mc,
		ObjectState *	os,
		INode *	node,
		Modifier *	mod,
		bool	bEndOfPipeline
	)

inlinevirtual

Remarks: This method will be called after a modifier is applied that changes a channel that the XTC object depends on.

Parameters:: TimeValue t

The time at which the channel will be modified.

ModContext &mc

The modifier context.

ObjectState* os

The objectstate of the object.

INode *node

A pointer to the node.

Modifier *mod

A pointer to the modifier being applied.

bool bEndOfPipeline

TRUE to indicate that this is the last change before the wsCache.

Default Implementation:: { }

Reimplemented in TriObjectNormalXTC.

199 {};

virtual BOOL SuspendObjectDisplay ( )

inlinevirtual

Remarks: If the XTCObject returns TRUE from this method the object is not displayed in the viewport; if FALSE is returned the Display() method will be called to display the object.

Default Implementation:: { return false; }

208 { return false; }

virtual void DeleteThis ( )

pure virtual

Remarks: This method is called to delete the extension object.

Implemented in TriObjectNormalXTC.

virtual void MaybeEnlargeViewportRect	(	GraphicsWindow *	gw,
		Rect &	rect
	)

inlinevirtual

Remarks: This method allows the object to enlarge its viewport rectangle if it wants to. The system will call this method for all XTCObjects when calculating the viewport rectangle; the XTCObject can enlarge the rectangle if desired.

Parameters:: GraphicsWindow *gw

Points to the GraphicsWindow instance associated with the viewport the object is displayed in.

Rect &rect

The viewport rectangle for the object which may be modified.

Default Implementation:: { }

228 {}

virtual bool RemoveXTCObjectOnMergeBranches	(	Object *	obFrom,
		Object *	obTo
	)

inlinevirtual

Remarks: By default the existing XTCObjects will be deleted if a branch updates In case the XTCObject wants to do more intelligent branching (not simply delete and add), it can return false from this method so that it can later (see MergeXTCObject() below) copy the data from this and other branches into an existing XTCObject.

Parameters:: Object *obFrom

Points to the source object.

Object *obTo

Points to the destination object.

Returns: Returns true if the object will be deleted; false to do more processing via MergeXTCObject.

Default Implementation:: { return true; }

249 { return true; }

virtual bool MergeXTCObject	(	Object *	obFrom,
		Object *	obTo,
		int	prio,
		int	branchID
	)

inlinevirtual

Remarks: The default implementation just adds the XTCObject to the to object. In case the XTCObject should do a more intelligent merge with already existing XTCObjects in the obTo, it has to overwrite this method.

Parameters:: Object *obFrom

Points to the source object.

Object *obTo

Points to the destination object.

int prio

The priority to set.

int branchID

The branch identifier to set.

Returns: TRUE if successful, otherwise FALSE.

Default Implementation:: { obTo->AddXTCObject(this,prio,branchID); return true;}

270 { obTo->AddXTCObject(this,prio,branchID); return true;}

Object::AddXTCObject

CoreExport void AddXTCObject(XTCObject *pObj, int priority=0, int branchID=-1)

This method adds an extension object into the pipeline.

virtual bool RemoveXTCObjectOnBranchDeleted	(	Object *	ComObj,
		int	branchID,
		bool	branchWillBeReordered
	)

inlinevirtual

Remarks: In case a branch of a compound object is deleted the XTCObject will be asked if the XTCObject should be deleted as well. In case the XTCObject represents a merge of all branches the XTCObject might want to return false to this method and reassign itself to another branch, so that the merged information is not lost.

Parameters:: Object *ComObj

A pointer to the compound object.

int branchID

The branch identifier to set.

bool branchWillBeReordered

TRUE if the branch should be reordered, otherwise FALSE.

Returns: TRUE if successful, otherwise FALSE.

Default Implementation:: { return true; }

292 { return true; }

XTCObject Class Reference

Class Description

Public Member Functions

Additional Inherited Members

Member Function Documentation