Class Osnap
See Also: Class OsnapHit, Class IOsnapManager, Class OsnapMarker, Structure SnapInfo The Advanced Topics section on Snapping.
class Osnap
Description:
This class is available in release 2.0 and later only.
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.
Friend Classes:
friend class OsnapHit;
friend class OsnapManager;
Methods:
Prototype:
Osnap();
Remarks:
Constructor. The OsnapManger interface pointer is initialized.
Prototype:
virtual ~Osnap();
Remarks:
Destructor. Internal data structure to the class are freed.
Prototype:
virtual int numsubs();
Remarks:
Returns the number of sub-snaps this plug-in provides.
Default Implementation:
{return 1;}
Prototype:
virtual BOOL IsActive();
Remarks:
Implemented by the system.
Returns TRUE if any of the sub-snaps are active; otherwise FALSE.
Prototype:
virtual BOOL GetActive(int index);
Remarks:
Implemented by the system.
Returns TRUE if any of the indexed sub-snap is active.
Prototype:
virtual void SetActive(int index, BOOL state);
Remarks:
Implemented by the system.
Sets the indexed sub-snap to the specified state.
Prototype:
virtual TCHAR *Category();
Remarks:
Returns the category string for this plug-in. If the plug-in fails to overide this method, the snap will be added to the "standard" page of the UI.
Default Implementation:
{return NULL;}
Prototype:
virtual Class_ID ClassID();
Remarks:
Returns the Class_ID for this plug-in.
Default Implementation:
{ return Class_ID( 0, 0); }
Prototype:
virtual boolean ValidInput(SClass_ID scid, Class_ID cid)=0;
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.
Return Value:
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;
}
Prototype:
virtual void Snap(Object* pobj, IPoint2 *p, TimeValue t);
Remarks:
Implemented by the Plug-In.
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:
{}
Prototype:
virtual BOOL UseCallbacks();
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 overide this method to return TRUE. Note: if callbacks are used, the Snap() method is not called.
Default Implementation:
{return FALSE;}
Prototype:
virtual int NumCallbacks();
Remarks:
Returns the number of callbacks used.
Default Implementation:
{return 0;}
Prototype:
virtual SnapCallback GetSnapCallback(int sub);
Remarks:
Returns the specified callback to be used for snapping.
Parameters:
int sub
The sub-snap index.
Return Value:
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;}
Prototype:
virtual BOOL GetSupportedObject(INode *iNode, TimeValue t, ObjectState *os);
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;
}
Prototype:
virtual TSTR *snapname(int index)=0;
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.
Prototype:
virtual TSTR *tooltip(int index);
Remarks:
Reserved for future use.
Parameters:
int index
The index of the sub-snap whose name is returned.
Default Implementation:
{return NULL;}
Prototype:
virtual OsnapMarker *GetMarker(int index)=0;
Remarks:
Implemented by the Plug-In.
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.
Return Value:
A pointer to an OsnapMarker. If this method returns NULL, a default marker will be displayed.
Prototype:
virtual WORD HiliteMode();
Remarks:
Implemented by the Plug-In.
Returns a value to indicate the type of highlighting to be done for this snap. Typically, some part of the objects geometry is illumintated. 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.
Return Value:
One or more of the following values:
HILITE_NORMAL
This is the default and indicates that some part of the objects geometry will be hilited. 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;}
Prototype:
virtual boolean BeginUI(HWND hwnd);
Remarks:
This method is reserved for future use.
Default Implementation:
{return TRUE;}
Prototype:
virtual void EndUI(HWND hwnd);
Remarks:
This method is reserved for future use.
Default Implementation:
{}
Prototype:
virtual HBITMAP getTools()=0;
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.
Prototype:
virtual HBITMAP getMasks()=0;
Remarks:
Returns a handle to a bitmap that contains the masks for the UI icons for this snap plug-in.
Prototype:
virtual BOOL HitTest(Object* pobj, IPoint2 *p, TimeValue t);
Remarks:
Implemented by the Plug-In.
Developers may overide 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.
Return Value:
Returns TRUE if the object is being hit and should be considered for snapping.
Default Implementation:
{return TRUE;}
Prototype:
virtual WORD AccelKey(int index)=0;
Remarks:
This method is no longer used.