Moray Plugin SDK Documentation

This release of the Plugin SDK can be used by Moray V3.5 (Build 9065) and later.

Scene Interface	Files Interface	Menu Interface	Import Interface
Export Interface	Object Interface	Controller Interface	External Interface
Data Structures	C++ Support	Compiler Settings

What's New

Controller Interface

The Controller Interface allows the plugin to implement an interface that can be used to manipulate other plugin objects.

The controller can be used to allow the user to use the normal Moray manipulations (select, scale, rotate, translate) to work with specific elements of a plugin object that are not always visible. For example, an object that is defined by a spline may want to allow the user to manipulate the spline using the same functionality as the sweep editor. This is possible with the Controller interface.

The plugin can use functions to draw lines and points (or it can use raw OpenGL for its display) and can register hotkeys that it would like to service.

Moray hides all the complexity of dealing with the viewports and its projections, whether it's a 2D or 3D viewport and so on.

A controller is activated and deactivated by calling the ActivateController function of the Scene Interface.

Reference List of Functions
By Function Group	Alphabetically
rInterface rUsesFuncs pObjectFuncs hController CalcPixelDistFromCursor PointInRect MarkClosestElement MarkElements GetMarkedCenter GetNumMarked UnMarkAll Notification TransformPoints PaintOpenGL PaintUnmarkedDots PaintMarkedDots PaintLines PaintOpenGLExtra GetPaintFlags RegisterHotkeys Command	CalcPixelDistFromCursor Command GetMarkedCenter GetNumMarked GetPaintFlags MarkClosestElement MarkElements Notification PaintLines PaintMarkedDots PaintOpenGL PaintOpenGLExtra PaintUnmarkedDots PointInRect RegisterHotkeys TransformPoints UnMarkAll hController pObjectFuncs rInterface rUsesFuncs

rInterface

MRY_INTERFACE rInterface;

The variable rInterface contains the identifier of this interface.

rUsesFuncs

MRY_INTERFACE rUsesFuncs;

The variable rUsesFuncs contains the identifier of the Object Interface that this controller can manipulate.

pObjectFuncs

LPMRY_OBJECTFUNCS pObjectFuncs;

The variable pObjectFuncs contains a pointer to the Object Functions of the Object Interface that this controller can manipulate.

See Also

MRY_OBJECTFUNCS

hController

long hController;

The variable hController contains a handle to the controller that Moray needs to identify this controller.

CalcPixelDistFromCursor

The function CalcPixelDistFromCursor can be used to determine how far away a 2D point in the view is from a 3D point.

long WINAPI fnCalcPixelDistFromCursor(long hController, long hView, MRY_VECTOR* vPt, MRY_POINTS2D *rPt, double *pdDist);

Parameters

hController	contains Moray's handle to the controller.
hView	contains Moray's handle to the view where the 2D point is referenced.
vPt	contains the 3D point that we want to determine the distance to.
rPt	contains the 2D coordinate (in the view referenced by hView) of the point to check.
pdDist	is a pointer to where the distance should be written.

Return Values

MRY_ERR_NULL_POINTER	if any of the first four parameters are NULL.
MRY_CTRL_POINT_IN_RANGE	if the 3D point is within a certain range of the 2D point.
MRY_CTRL_POINT_OUT_OF_RANGE	if the 3D point is outside a certain range of the 2D point.

Remarks

The function can be used to determine whether a mouse position over a view is near a 3D point. For example, to determine the closest control point in the MarkClosestElement function. Moray takes care of 2D and 3D projections so that you do not need to worry about what type of view, etc. it is.

See Also

MarkClosestElement

PointInRect

The function PointInRect can be used to determine whether a 3D point is inside a rectangle defined in the views coordinate system.

long WINAPI fnPointInRect(long hController, long hView, MRY_VECTOR* vPt, MRY_RECT *rSelRect);

Parameters

hController	contains Moray's handle to the controller.
hView	contains Moray's handle to the view where the rectangle is referenced.
vPt	contains the 3D point that we want to determine the distance to.
rSelRect	contains the 2D coordinates (in the view referenced by hView) of the rectangle we want to test the point against.

Return Values

MRY_ERR_NULL_POINTER	if any of the four parameters are NULL.
MRY_CTRL_POINT_IN_RANGE	if the projection of the 3D point falls inside the 2D rectangle defined by rSelRect.
MRY_CTRL_POINT_OUT_OF_RANGE	if the projection of the 3D point falls outside the 2D rectangle defined by rSelRect.

Remarks

The function can be used to determine whether the projection of a 3D point into the view falls within a certain rectangle defined in the views coordiante system. For example, to determine whether a point is inside the rectangle in the MarkElements fucntion. Moray takes care of 2D and 3D projections so that you do not need to worry about what type of view, etc. it is.

See Also

MarkElements

MarkClosestElement

The function MarkClosestElement is called by Moray when the closest point that can be manipulated, needs to be found.

void WINAPI fnMarkClosestElement(long hObj, LPMRY_SCN_VIEWINFO pView, int nWhereX, int nWhereY);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct containing the details of the view in which the coordinates are defined
nWhereX,nWhereY	contains the X,Y coordinates of the position in the view described by pView to which the closest element should be found.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

The function is called by Moray when the user depresses the left mouse button to manipulate the elements of the object and no elements are marked (GetNumMarked returns 0).
If this function finds an element that is close enough to the position passed, it should remember the element and (GetNumMarked should return 1).

Note that this function should only mark 1 element, even if others are exactly as close, otherwise it would not be possible to move elements that are exactly at the same position to be moved apart.

MarkElements

The function MarkElements is called by Moray when any points inside an area that can be manipulated need to be found.

long WINAPI fnMarkElements(long hObj, LPMRY_SCN_VIEWINFO pView, MRY_VECTOR* v1, MRY_VECTOR* v2, MRY_RECT* rSelRect);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct containing the details of the view in which the coordinates are defined.
v1,v2	contains the 3D coordinates of the selection rectangle. These are only valid in 2D viewports.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

The function is called by Moray when the user has used the mouse to define a selection rectangle.
If this function finds elements that are inside the selection rectangle, it should toggle the marked state of the elements.

It is recommended you use the supplied PointInRect function to test your points against the 2D selection rectangle.

See Also

GetNumMarked

GetMarkedCenter

The function GetMarkedCenter is called by Moray to determine the center of all marked elements.

long WINAPI fnGetMarkedCenter(long hObj, MRY_VECTOR *pCenter);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
pCenter	contains a pointer to where the center of gravity of the marked elements should be written.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

When the user wants to scale or rotate marked elements, Moray needs to know where the center of the marked elements is located and calls this function to determine this.

See Also

GetNumMarked

The function GetNumMarked is called by Moray to retrieve the number of marked elements of the object.

long WINAPI fnGetNumMarked(long hObj);

Parameters

hObj

contains the handle of the plugin object associated with this controller.

Return Values

the number of marked elements.

Remarks

This function must return the number of currently marked elements. Moray uses this to determine whether elements are marked and operations can take place. For example, scaling and rotation are only allowed if two or more elements are marked. Translation is always allowed, if no elements are marked when Moray wants to translate something, MarkClosestElement is called.

See Also

MarkClosestElement

UnMarkAll

The function UnMarkAll is called by Moray to unmark all elements.

long WINAPI fnUnMarkAll(long hObj);

Parameters

hObj

contains the handle of the plugin object associated with this controller.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

The marked state of all elements should be reset. Moray calls this after a translation if MarkClosestElement was called and marked one element.

See Also

MarkClosestElement

Notification

The function Notification is called by Moray to let the plugin know that the elements are being manipulated.

long WINAPI fnNotification(long hObj, int nEvent);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
nEvent	contains the event that is occurring (see Remarks).

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

When the user starts a scale, rotate or translate manipulation, Moray calls this function with a corresponding event code.

nEvent is a bit field that can contain a combination the following values:

MRY_CTRL_NOTIFY_START_MANIPULATION - the manipulation is about to start.
MRY_CTRL_NOTIFY_MANIPULATION - one step of the manipulation has just taken place.
MRY_CTRL_NOTIFY_END_MANIPULATION - the manipulation is done.
MRY_CTRL_NOTIFY_ACTIVATING - the controller is being activated.
MRY_CTRL_NOTIFY_DEACTIVATING - the controller is being deactivated.

To determine whether it's a notification of manipulation, AND nEvent with MRY_CTRL_NOTIFY_ACTION_MASK and compare the result to the first three values above. If one of them is set, you can AND nEvent with MRY_CTRL_NOTIFY_TYPE_MASK to find the type of manipulation, which will be one of the following:

MRY_CTRL_NOTIFY_SCALE - The elements are being scaled.
MRY_CTRL_NOTIFY_ROTATE - The elements are being rotated.
MRY_CTRL_NOTIFY_TRANSLATE - The elements are being translated.

TransformPoints

The function TransformPoints is called by Moray to transform the marked elements.

long WINAPI fnTransformPoints(long hObj, pfnTransformCallback fnTransform);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
fnTransform	is a callback function that transforms an individual 3D point.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

Moray calls this function every time the mouse is moved during a manipulation. The plugin should call the supplied callback function as many times as neccessary to transform all marked elements.

The supplied callback function will transform each point according to the mode and the mouse movement. It has the following prototype:

void fnTransformCallback(MRY_VECTOR* pPos);

The passed vector will be changed to reflect the manipulation the user is doing with the mouse.

Moray takes care of the coordinate system and projections in the different viewports.

Moray calls Notification with a MRY_CTRL_NOTIFY_MANIPULATION event immediately after this function.

See Also

Notification

PaintOpenGL

The function PaintOpenGL is called when this controller is active and a view is redrawn.

long WINAPI fnPaintOpenGL(long hObj, LPMRY_SCN_VIEWINFO pView);

Parameters

hObj	contains the handle of the plugin object associated with this controller and currently being redrawn.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct describing the view.

Return Values

MRY_CTRL_PAINT_HIGH_LEVEL	should be returned if the controller would like to use the high-level paint functions (see Remarks).
MRY_CTRL_PAINT_HIGH_LEVEL_PLUS_EXTRA	should be returned if the controller would like to use the high-level paint functions and subsequently issue OpenGL calls (see Remarks).
MRY_SUCCESS	should be return if the controller painted the objects special elements.

Remarks

A controller can paint extra things on the screen. Moray already draws the wireframe (or polygon) representation of the object on the screen, but the controller can additionally paint to the screen.

For example, if the controller plugin allows the user to manipulate a spline, this function can either draw the entire spline itself, or can return MRY_CTRL_PAINT_HIGH_LEVEL, in which case Moray will call the three functions PaintLines, PaintUnmarkedDots and PaintMarkedDots. These can then simply feed 3D data to Moray and Moray will draw the corresponding elements in the same style as in the other editors (sweep, mesh and bezier).

If the controller interface has special needs in drawing OpenGL stuff, they should be done in this function. Make sure you leave the OpenGL engine in the same state when you're done.

If you would like to take advantage of the highlevel drawing code and still issue additional OpenGL commands, then return MRY_CTRL_PAINT_HIGH_LEVEL_PLUS_EXTRA, in which case Moray will call the three functions PaintLines, PaintUnmarkedDots and PaintMarkedDots and then the PaintOpenGLExtra function. You can do paint any additional painting in that function.

PaintUnmarkedDots

The function PaintUnmarkedDots is called by Moray to draw points at the locations of unmarked elements.

long WINAPI fnPaintUnmarkedDots(long hObj, LPMRY_SCN_VIEWINFO pView, pfnPaintVertexCallback fnDraw);

Parameters

hObj	contains the handle of the plugin object associated with this controller and currently being redrawn.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct describing the view.
fnDraw	is a pointer to a callback function that paints an individual 3D point.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

If PaintOpenGL returns MRY_CTRL_PAINT_HIGH_LEVEL, Moray calls this function, expecting the plugin to call the supplied callback function to draw unmarked points.
The callback function has the following prototype:

void fnPaintVertexCallback(double dX,double dY,double dZ,int nFlags);

nFlags must be set to 0 during the callbacks.

Note: Moray has setup OpenGL so that lighting and depth testing is disabled and has issued color and size commands, as well as the glBegin(GL_POINTS) command, so it is not recommended that other OpenGL commands are issued here.

PaintMarkedDots

The function PaintMarkedDots is called by Moray to draw points at the locations of marked elements.

long WINAPI fnPaintMarkedDots(long hObj, LPMRY_SCN_VIEWINFO pView, pfnPaintVertexCallback fnDraw);

Parameters

hObj	contains the handle of the plugin object associated with this controller and currently being redrawn.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct describing the view.
fnDraw	is a pointer to a callback function that paints an individual 3D point.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

If PaintOpenGL returns MRY_CTRL_PAINT_HIGH_LEVEL, Moray calls this function, expecting the plugin to call the supplied callback function to draw marked points.
The callback function has the following prototype:

void fnPaintVertexCallback(double dX,double dY,double dZ,int nFlags);

PaintLines

The function PaintLines is called by Moray to draw lines.

long WINAPI fnPaintLines(long hObj, LPMRY_SCN_VIEWINFO pView, pfnPaintVertexCallback fnDraw);

Parameters

hObj	contains the handle of the plugin object associated with this controller and currently being redrawn.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct describing the view.
fnDraw	is a pointer to a callback function that paints the lines.

Return Values

MRY_SUCCESS

should be returned if the function was successful. The return code is currently ignored.

Remarks

If PaintOpenGL returns MRY_CTRL_PAINT_HIGH_LEVEL, Moray calls this function, expecting the plugin to call the supplied callback function to draw lines.
The callback function has the following prototype:

void fnPaintVertexCallback(double dX,double dY,double dZ,int nFlags);

To draw a line, the plugin should provide point pairs. To ease the drawing of connected lines and to reduce the calling overhead for this case, nFlags can be MRY_CTRL_DRAW_CONNECT_TO_LAST if a line should be drawn from the previous point to the passed point.
The first two times the plugin calls PaintLines it can pass 0 in nFlags. This will draw a line between those two points. The third and subsequent calls can pass MRY_CTRL_DRAW_CONNECT_TO_LAST in nFlags and this will connect the previous point to the current point. Thus, the plugin does not have to pass pairs into the function.

If the plugin wants to start a new (or second) line segment, it should pass o in nFlags and proceed from the start as above.

Note: Moray has setup OpenGL so that lighting and depth testing is disabled and has issued color and size commands, as well as the glBegin(GL_LINES) command, so it is not recommended that other OpenGL commands are issued here.

PaintOpenGLExtra

The function PaintOpenGLExtra is called when this controller is active, a view is redrawn and the plugin requested extra painting in PaintOpenGL.

long WINAPI fnPaintOpenGLExtra(long hObj, LPMRY_SCN_VIEWINFO pView, pfnTransformCallback fnTransform);

Parameters

hObj	contains the handle of the plugin object associated with this controller and currently being redrawn.
pView	contains a pointer to a MRY_SCN_VIEWINFO struct describing the view being redrawn.
fnTransform	contains a pointer to a function that can be used to transform 3D points in the objects local coordinate system to the world coordinate system.

Return Values

MRY_SUCCESS

should be returned (value currently ignored).

Remarks

This function is only called if PaintOpenGL returned MRY_CTRL_PAINT_HIGH_LEVEL_PLUS_EXTRA. After Moray has called the three functions PaintLines, PaintUnmarkedDots and PaintMarkedDots, it calls this function to allow you to do any additional painting. You need to make sure that the OpenGL state is left as it was when the function was entered.

To take into account the objects transformations, the callback is provided to convert from objecy space to world space. The prototype for the function is:

void fnTransform(MRY_VECTOR *pVec);

After the function returns the 3D point that was pointed to by pVec has been transformed to world space.

GetPaintFlags

The function GetPaintFlags is called by Moray to determine whether the object should be painted in the view.

long WINAPI fnGetPaintFlags(long hObj, int *pnDisplayFlags);

Parameters

hObj	contains the handle of the object being queried.
pnDisplayFlags	contains a pointer to the paint flags that are active.

Return Values

MRY_CTRL_SKIP_OBJECT	if the object should not be rendered.
MRY_CTRL_PAINT_OBJECT	if the object should be rendered normally.

Remarks

This function can determine whether other objects should be rendered when this controller is active.

RegisterHotkeys

The function RegisterHotkeys is called during the loading of the plugins to allow a plugin to register hotkeys.

long WINAPI fnRegisterHotkeys(int nIndex, LPMRY_MENU_COMMAND pCommand);

Parameters

nIndex	is the index of the hotkey being registered.
pCommand	contains a pointer to the MRY_MENU_COMMAND struct that contains the definition of the hotkey.

Return Values

MRY_SUCCESS	should be returned if a pCommand contains details of a hotkey to be registered.
MRY_ERR_NO_MORE_ITEMS	should be returned when no more hotkeys need to be registered.

Remarks

Moray calls this function during the loading of plugins as many times as the plugin returns MRY_SUCCESS, increasing nIndex by one for each call (zero-based).

If the controller is active and the user presses the corresponding key, Moray calls the controllers Command function.

See Also

Command, Menu Interface

Command

The function Command is called when a previously registered hotkey is pressed.

long WINAPI fnCommand(long hObj, long nID);

Parameters

hObj	contains the handle of the plugin object associated with this controller.
nID	contains the ID of the hotkey (defined in the nID member of the MRY_MENU_COMMAND struct used in RegisterHotkeys.

Return Values

MRY_SUCCESS	must be returned if the hotkey was processed.
MRY_ERR_NOT_HANDLED	must be returned if the hotkey was not handled.

Remarks

This function is called by Moray when a user presses a hotkey that was registered with the RegisterHotkeys function.
It allows the definition of hotkeys associated only with this controller and without needing to implement a Menu Interface.

See Also

RegisterHotkeys, Menu Interface