#include <osnap.h>

Class Description

See also: Class OsnapHit, Class IOsnapManager, Class OsnapMarker, Structure SnapInfo, The Advanced Topics section on Snapping.

Description:: This is the base class for the derivation of a new object snap plug-ins.

Conceptually, the osnap class represents a "rule" for locating points in an object's local space. Typically, an instance of this class will only make sense for certain object types. It's the job of the ValidInput() method to filter out uninteresting nodes in the scene. When the scene is traversed, each object which passes the input test will be passed into the Snap() method. This method is the workhorse of object snap plug-ins and is responsible for computing, allocating and recording its hits.

For convenience, an object snap plug-in may encompass multiple sub-rules. For example, the shape snap contains rules for computing both tangents and perpendicular points on splines. Therefore many of the methods have an index argument which identifies which sub-snap it applies to.

For sample code see /MAXSDK/SAMPLES/SNAPS/SPHERE/SPHERE.CPP.

Inheritance diagram for Osnap:

Public Member Functions
DllExport	Osnap ()

virtual DllExport	~Osnap ()

DllExport void	Init ()

virtual int	numsubs ()

virtual DllExport MCHAR *	Category ()

virtual Class_ID	ClassID ()

virtual BOOL	UseCallbacks ()

virtual int	NumCallbacks ()

virtual DllExport BOOL	GetSupportedObject (INode iNode, TimeValue t, ObjectState os)

virtual MSTR *	snapname (int index)=0

virtual MSTR *	tooltip (int index)

virtual boolean	ValidInput (SClass_ID scid, Class_ID cid)=0

virtual OsnapMarker *	GetMarker (int index)=0

virtual WORD	HiliteMode ()

virtual boolean	BeginUI (HWND hwnd)

virtual void	EndUI (HWND hwnd)

virtual HBITMAP	getTools ()=0

virtual HBITMAP	getMasks ()=0

virtual void	Snap (Object pobj, IPoint2 p, TimeValue t)

virtual BOOL	HitTest (Object pobj, IPoint2 p, TimeValue t)

virtual SnapCallback	GetSnapCallback (int sub)

virtual WORD	AccelKey (int index)=0

virtual MSTR	iconName (int index) const =0

Protected Member Functions
DllExport void	_Snap (INode inode, TimeValue t, ViewExp vpt, IPoint2 p, SnapInfo snap)

DllExport Point3	_ReEvaluate (TimeValue t, OsnapHit *hit)

DllExport boolean	IsActive ()

DllExport void	SetActive (int index, boolean state)

DllExport boolean	GetActive (int index)

DllExport void	AddCandidate (Point3 *pt, int type=-1, int num=0,...)

DllExport Point3 *	GetCandidatePoint (int index)

DllExport void	GetCandidateMesh (int index, HitMesh *m)

DllExport int	GetCandidateType (int index)

DllExport void	ClearCandidates ()

DllExport int	NumCandidates ()

virtual DllExport Point3	ReEvaluate (TimeValue t, OsnapHit hit, Object pobj)

DllExport BOOL	CheckPotentialHit (int ptindex, Point2 cursor)

DllExport BOOL	CheckPotentialHit (Point3 *p, int ptindex, Point2 cursor)

Protected Attributes
BOOL *	m_active

GraphicsWindow *	m_hitgw

int	m_baseindex

IOsnapManager *	theman

CandidateTab	point_candidates

Friends
class	OsnapHit

class	MXS_IOsnap

class	OsnapManager

class	OSnapDecorator

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

Constructor & Destructor Documentation

DllExport Osnap ( )

Remarks: Constructor. The OsnapManger interface pointer is initialized.

virtual DllExport ~Osnap ( )

virtual

Remarks: Destructor. Internal data structure to the class are freed.

Member Function Documentation

DllExport void _Snap	(	INode *	inode,
		TimeValue	t,
		ViewExp *	vpt,
		IPoint2 *	p,
		SnapInfo *	snap
	)

protected

DllExport Point3 _ReEvaluate	(	TimeValue	t,
		OsnapHit *	hit
	)

protected

DllExport boolean IsActive ( )

protected

Remarks: Implemented by the system.

Returns TRUE if any of the sub-snaps are active; otherwise FALSE.

DllExport void SetActive	(	int	index,
		boolean	state
	)

protected

Remarks: Implemented by the system.

Sets the indexed sub-snap to the specified state.

DllExport boolean GetActive ( int index )

protected

Remarks: Implemented by the system.

Returns TRUE if any of the indexed sub-snap is active.

DllExport void AddCandidate	(	Point3 *	pt,
		int	type = `-1`,
		int	num = `0`,
			...
	)

protected

DllExport Point3* GetCandidatePoint ( int index )

protected

DllExport void GetCandidateMesh	(	int	index,
		HitMesh *	m
	)

protected

DllExport int GetCandidateType ( int index )

protected

DllExport void ClearCandidates ( )

protected

DllExport int NumCandidates ( )

inlineprotected

115 {return point_candidates.Count();}

Tab::Count

int Count() const

Retrieves the number of items in the Tab.

Definition: tab.h:219

Osnap::point_candidates

CandidateTab point_candidates

Definition: osnap.h:315

virtual DllExport Point3 ReEvaluate	(	TimeValue	t,
		OsnapHit *	hit,
		Object *	pobj
	)

protectedvirtual

DllExport BOOL CheckPotentialHit	(	int	ptindex,
		Point2	cursor
	)

protected

DllExport BOOL CheckPotentialHit	(	Point3 *	p,
		int	ptindex,
		Point2	cursor
	)

protected

DllExport void Init ( )

virtual int numsubs ( )

inlinevirtual

Remarks: Returns the number of sub-snaps this plug-in provides.

Default Implementation:: {return 1;}

Reimplemented in OSnapDecorator.

137 {return 1;}; //the number of subsnaps this guy has

virtual DllExport MCHAR* Category ( )

virtual

Remarks: Returns the category string for this plug-in. If the plug-in fails to override this method, the snap will be added to the "standard" page of the UI.

Default Implementation:: {return NULL;}

Reimplemented in OSnapDecorator.

virtual Class_ID ClassID ( )

inlinevirtual

Remarks: Returns the Class_ID for this plug-in.

Default Implementation:: { return Class_ID( 0, 0); }

Reimplemented in OSnapDecorator.

147 { return Class_ID( 0, 0); }

Class_ID

Definition: maxtypes.h:140

virtual BOOL UseCallbacks ( )

inlinevirtual

Remarks: Developers have the option of placing all their code in a single Snap() method or of breaking it up into multiple callbacks. Developers wishing to use callbacks should override this method to return TRUE. Note: if callbacks are used, the Snap() method is not called.

Default Implementation:: {return FALSE;}

Reimplemented in OSnapDecorator.

155 {return FALSE;}

virtual int NumCallbacks ( )

inlinevirtual

Remarks: Returns the number of callbacks used.

Default Implementation:: {return 0;}

Reimplemented in OSnapDecorator.

159 {return 0;}

virtual DllExport BOOL GetSupportedObject	(	INode *	iNode,
		TimeValue	t,
		ObjectState *	os
	)

virtual

Remarks: This method is provided for future use so that snaps can evaluate the object at arbitrary points in the pipeline. Returns TRUE if the object associated with the node passed is supported; otherwise FALSE. The default implementation calls ValidInput() and fills the storage pointed to by os with the object state at the end of the geometry pipeline. This is the same object state returned by EvalWorldState.

Parameters:: INode *iNode

The node whose object being checked.

TimeValue t

The time at which to check the object.

ObjectState *os

This pointer should be updated to the ObjectState of the object associated with the node by calling INode::EvalWorldState().

Default Implementation:: BOOL Osnap::GetSupportedObject(INode *inode, TimeValue t, ObjectState os) {

*os = inode->EvalWorldState(t);

assert(os);

Class_ID thistype = os->obj->ClassID();

unsigned long supertype = os->obj->SuperClassID();

return ValidInput(supertype,thistype)?TRUE:FALSE;

}

Reimplemented in OSnapDecorator.

virtual MSTR* snapname ( int index )

pure virtual

Remarks: Returns a pointer to the snap's name to be displayed in the user interface.

Parameters:: int index

The index of the sub-snap whose name is returned.

Implemented in OSnapDecorator.

virtual MSTR* tooltip ( int index )

inlinevirtual

Remarks: Reserved for future use.

Parameters:: int index

The index of the sub-snap whose name is returned.

Default Implementation:: {return NULL;}

197 {return NULL;} // the snaps name to be displayed in the UI

NULL

#define NULL

Definition: autoptr.h:18

virtual boolean ValidInput	(	SClass_ID	scid,
		Class_ID	cid
	)

pure virtual

Remarks: This method is used to check if the object whose super class ID and class ID are passed is valid input for this object snap plug-in to snap to.

Parameters:: SClass_ID scid

The Super Class ID to check.

Class_ID cid

The Class ID to check.

Returns: Returns TRUE if the object is OK to snap to; otherwise FALSE.

Sample Code:: boolean SphereSnap::ValidInput(SClass_ID scid, Class_ID cid){

boolean c_ok = FALSE, sc_ok = FALSE;

sc_ok |= (scid == GEOMOBJECT_CLASS_ID)? TRUE : FALSE;

c_ok |= (cid == Class_ID(SPHERE_CLASS_ID,0))? TRUE : FALSE;

return sc_ok && c_ok;

}

Implemented in OSnapDecorator.

virtual OsnapMarker* GetMarker ( int index )

pure virtual

Remarks: This method should return a pointer to a (typically static) OsnapMarker. These markers define the identifying markers which get displayed in the viewports.

Parameters:: int index

The subsnap whose marker the system requires.

Returns: A pointer to an OsnapMarker. If this method returns NULL, a default marker will be displayed.

Implemented in OSnapDecorator.

virtual WORD HiliteMode ( )

inlinevirtual

Remarks: Returns a value to indicate the type of highlighting to be done for this snap. Typically, some part of the objects geometry is illuminated. In some cases it is desirable to illuminate the objects bounding box and occasionally to draw a world space crosshair. The default implementations should normally be used.

Returns: One or more of the following values:

HILITE_NORMAL

This is the default and indicates that some part of the objects geometry will be highlighted. The description of this geometry is recorded in the hitmesh member of the class OsnapHit.

HILITE_BOX

This is return value indicates that the objects bounding box should be drawn as the result of a hit on this object.

HILITE_CROSSHAIR

Reserved for grid snapping. This return value indicates that a world space crosshair should be drawn through the hitpoint.

Default Implementation:: {return HILITE_NORMAL;}

243 {return HILITE_NORMAL;}

HILITE_NORMAL

#define HILITE_NORMAL

Definition: osnap.h:35

virtual boolean BeginUI ( HWND hwnd )

inlinevirtual

Remarks: This method is reserved for future use.

Default Implementation:: {return TRUE;}

Reimplemented in OSnapDecorator.

248 {return TRUE;}

virtual void EndUI ( HWND hwnd )

inlinevirtual

Remarks: This method is reserved for future use.

Default Implementation:: {}

Reimplemented in OSnapDecorator.

252 {};

virtual HBITMAP getTools ( )

pure virtual

Remarks: Returns a handle to a bitmap that contains the icons to be displayed for this snap. If there are N subsnaps, this bitmap should contain N icons. The size of an individual icon is 16x15 or 16x16.

Implemented in OSnapDecorator.

virtual HBITMAP getMasks ( )

pure virtual

Remarks: Returns a handle to a bitmap that contains the masks for the UI icons for this snap plug-in.

Implemented in OSnapDecorator.

virtual void Snap	(	Object *	pobj,
		IPoint2 *	p,
		TimeValue	t
	)

inlinevirtual

Remarks: This is the workhorse of a snap plug-in. This method should compute and record hits on the given object.

Parameters:: Object* pobj

A pointer to an object which passed the valid input test. Note that if this method is called, you can make certain assumption about the class of the object and do appropriate casting as needed.

IPoint2 *p

The cursor position.

TimeValue t

The time at which to check.

Default Implementation:: {}

Reimplemented in OSnapDecorator.

273 {};

virtual BOOL HitTest	(	Object *	pobj,
		IPoint2 *	p,
		TimeValue	t
	)

inlinevirtual

Remarks: Developers may override this method to do additional hit testing on each object as an additional rejection criteria. The default implementation returns TRUE and consequently filters nothing. Note that if this method returns FALSE for a given object, the snap method will never be called for it.

Note: Nodes are always trivially rejected if the cursor position does not fall within the screen space bounding box of the node.

Parameters:: Object* pobj

A pointer to the object returned by GetSupportedObject.

IPoint2 *p

The cursor position.

TimeValue t

The time at which to hittest.

Returns: Returns TRUE if the object is being hit and should be considered for snapping.

Default Implementation:: {return TRUE;}

Reimplemented in OSnapDecorator.

292 {return TRUE;}

virtual SnapCallback GetSnapCallback ( int sub )

inlinevirtual

Remarks: Returns the specified callback to be used for snapping.

Parameters:: int sub

The sub-snap index.

Returns: Note the following typedef – a SnapCallback is simply a pointer to a function passed two arguments:

typedef void (SnapCallback) (Object pobj, IPoint2 *p) ;

Default Implementation:: { return NULL;}

Reimplemented in OSnapDecorator.

302 { return NULL;}

NULL

#define NULL

Definition: autoptr.h:18

virtual WORD AccelKey ( int index )

pure virtual

Remarks: This method is no longer used.

Implemented in OSnapDecorator.

virtual MSTR iconName ( int index ) const

pure virtual

Remarks: Returns the reference to the snap's icon name

Parameters:: int index

The index of the sub-snap whose icon name is returned.

Implemented in OSnapDecorator.

Friends And Related Function Documentation

friend class OsnapHit

friend

friend class MXS_IOsnap

friend

friend class OsnapManager

friend

friend class OSnapDecorator

friend

Member Data Documentation

BOOL* m_active

protected

GraphicsWindow* m_hitgw

protected

int m_baseindex

protected

IOsnapManager* theman

protected

CandidateTab point_candidates

protected

Osnap Class Reference

Class Description

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation