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.


Top
 

rUsesFuncs


   MRY_INTERFACE rUsesFuncs;

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


Top
 

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


Top
 

hController


   long hController;

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


Top
 

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


Top
 

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


Top
 

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.

See Also

MarkElements, GetNumMarked, MRY_SCN_VIEWINFO


Top
 

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


Top
 

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


Top
 

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


Top
 

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


Top
 

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:

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:


Top
 

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:

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


Top
 

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.

See Also

PaintLines, PaintUnmarkedDots, PaintMarkedDots, PaintOpenGLExtra


Top
 

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:

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.

See Also

PaintOpenGL, PaintMarkedDots, PaintLines, PaintOpenGLExtra


Top
 

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:

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.

See Also

PaintOpenGL, PaintUnmarkedDots, PaintLines, PaintOpenGLExtra


Top
 

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:

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.

See Also

PaintOpenGL, PaintUnmarkedDots, PaintMarkedDots, PaintOpenGLExtra


Top
 

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:

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

See Also

PaintLines, PaintUnmarkedDots, PaintMarkedDots, PaintOpenGL


Top
 

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.


Top
 

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


Top
 

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


Top