Public Member Functions | Protected Member Functions | Protected Attributes | Friends

Osnap Class Reference

This reference page is linked to from the following overview topics: Miscellaneous Samples and Plug-ins, Plug-in Base Classes, Snapping.

Search for all occurrences

Detailed Description

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

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.

#include <osnap.h>

Inheritance diagram for Osnap:
Inheritance graph
[legend]

List of all members.

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

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

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]
Search for all occurrences
DllExport Point3 _ReEvaluate ( TimeValue  t,
OsnapHit *  hit 
) [protected]
Search for all occurrences
DllExport boolean IsActive ( ) [protected]
Search for all occurrences
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]
Search for all occurrences
Remarks:
Implemented by the system.

Sets the indexed sub-snap to the specified state.
DllExport boolean GetActive ( int  index ) [protected]
Search for all occurrences
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]
Search for all occurrences
DllExport Point3* GetCandidatePoint ( int  index ) [protected]
Search for all occurrences
DllExport void GetCandidateMesh ( int  index,
HitMesh *  m 
) [protected]
Search for all occurrences
DllExport int GetCandidateType ( int  index ) [protected]
Search for all occurrences
DllExport void ClearCandidates ( ) [protected]
Search for all occurrences
DllExport int NumCandidates ( ) [inline, protected]
Search for all occurrences
{return point_candidates.Count();}
virtual DllExport Point3 ReEvaluate ( TimeValue  t,
OsnapHit *  hit,
Object *  pobj 
) [protected, virtual]
Search for all occurrences
DllExport BOOL CheckPotentialHit ( int  ptindex,
Point2  cursor 
) [protected]
Search for all occurrences
DllExport BOOL CheckPotentialHit ( Point3 *  p,
int  ptindex,
Point2  cursor 
) [protected]
Search for all occurrences
DllExport void Init ( )
Search for all occurrences
virtual int numsubs ( ) [inline, virtual]
Search for all occurrences
Remarks:
Returns the number of sub-snaps this plug-in provides.
Default Implementation:
{return 1;}

Reimplemented in OSnapDecorator.

{return 1;}; //the number of subsnaps this guy has
virtual DllExport MCHAR* Category ( ) [virtual]
Search for all occurrences
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;}

Reimplemented in OSnapDecorator.

virtual Class_ID ClassID ( ) [inline, virtual]
Search for all occurrences
Remarks:
Returns the Class_ID for this plug-in.
Default Implementation:
{ return Class_ID( 0, 0); }

Reimplemented in OSnapDecorator.

{ return Class_ID( 0, 0); }
virtual BOOL UseCallbacks ( ) [inline, virtual]
Search for all occurrences
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;}

Reimplemented in OSnapDecorator.

{return FALSE;}
virtual int NumCallbacks ( ) [inline, virtual]
Search for all occurrences
Remarks:
Returns the number of callbacks used.
Default Implementation:
{return 0;}

Reimplemented in OSnapDecorator.

{return 0;}
virtual DllExport BOOL GetSupportedObject ( INode *  iNode,
TimeValue  t,
ObjectState *  os 
) [virtual]
Search for all occurrences
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]
Search for all occurrences
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 ) [inline, virtual]
Search for all occurrences
Remarks:
Reserved for future use.
Parameters:
int index

The index of the sub-snap whose name is returned.
Default Implementation:
{return NULL;}
{return NULL;} // the snaps name to be displayed in the UI
virtual boolean ValidInput ( SClass_ID  scid,
Class_ID  cid 
) [pure virtual]
Search for all occurrences
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]
Search for all occurrences
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 ( ) [inline, virtual]
Search for all occurrences
Remarks:
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.
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 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;}
{return HILITE_NORMAL;}
virtual boolean BeginUI ( HWND  hwnd ) [inline, virtual]
Search for all occurrences
Remarks:
This method is reserved for future use.
Default Implementation:
{return TRUE;}

Reimplemented in OSnapDecorator.

{return TRUE;}
virtual void EndUI ( HWND  hwnd ) [inline, virtual]
Search for all occurrences
Remarks:
This method is reserved for future use.
Default Implementation:
{}

Reimplemented in OSnapDecorator.

{};
virtual HBITMAP getTools ( ) [pure virtual]
Search for all occurrences
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]
Search for all occurrences
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 
) [inline, virtual]
Search for all occurrences
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.

{};
virtual BOOL HitTest ( Object *  pobj,
IPoint2 *  p,
TimeValue  t 
) [inline, virtual]
Search for all occurrences
Remarks:
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.
Returns:
Returns TRUE if the object is being hit and should be considered for snapping.
Default Implementation:
{return TRUE;}

Reimplemented in OSnapDecorator.

{return TRUE;}
virtual SnapCallback GetSnapCallback ( int  sub ) [inline, virtual]
Search for all occurrences
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.

{ return NULL;}
virtual WORD AccelKey ( int  index ) [pure virtual]
Search for all occurrences
Remarks:
This method is no longer used.

Implemented in OSnapDecorator.

Friends And Related Function Documentation

friend class OsnapHit [friend]
Search for all occurrences
friend class MXS_IOsnap [friend]
Search for all occurrences
friend class OsnapManager [friend]
Search for all occurrences
friend class OSnapDecorator [friend]
Search for all occurrences

Member Data Documentation

BOOL* m_active [protected]
Search for all occurrences
GraphicsWindow* m_hitgw [protected]
Search for all occurrences
int m_baseindex [protected]
Search for all occurrences
IOsnapManager* theman [protected]
Search for all occurrences
CandidateTab point_candidates [protected]
Search for all occurrences
Generated on Fri Sep 23 2011 17:51:48 by doxygen 1.7.3
Please send us your comment about this page

Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap
Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap Osnap