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

CSceneInterface CFilesInterface CMenuInterface CImportInterface
CExportInterface CObjectInterface CExternalInterface
CPluginDialog CPluginObject
CAttributes CProgressBar C support Compiler Settings

What's New

CSceneInterface

This class encapsulates the Scene Interface in a C++ wrapper.

Reference List of Functions

By Function Group Alphabetically
m_pFunctions
CSceneInterface
Init
OnEvent
OnLoadSaveEvent
OnPrintEvent
OnRequiredStreamSize
OnWriteToStream
OnReadFromStream
OnRedrawEvent
OnGet3DWireframeData
OnBuildSceneWireframe
OnBuildSceneLazyWireframe
CheckCursorShape
OnExecuteUndo
OnReleaseUndo
GetFunctions
GetSceneFunctions
DECLARE_SCENE_STATIC
DEFINE_SCENE_STATIC
CSceneInterface
CheckCursorShape
DECLARE_SCENE_STATIC
DEFINE_SCENE_STATIC
GetFunctions
GetSceneFunctions
Init
OnBuildSceneLazyWireframe
OnBuildSceneWireframe
OnEvent
OnExecuteUndo
OnGet3DWireframeData
OnLoadSaveEvent
OnPrintEvent
OnReadFromStream
OnRedrawEvent
OnReleaseUndo
OnRequiredStreamSize
OnWriteToStream
m_pFunctions



 

m_pFunctions


   LPMRY_SCENEFUNCS m_pFunctions; [protected]

The member variable m_pFunctions is a pointer to the MRY_SCENEFUNCS structure that this class encapsulates.


Top
 

CSceneInterface

The function CSceneInterface is the constructor of this interface.

    CSceneInterface(LPMRY_INTERFACEID pUID);

Parameters

pUID

Contains a pointer to the MRY_INTERFACEID that uniquely identifies this interface.

Remarks

The interface ID that pUID points to should be generated with the MKUID.EXE program that comes with the Plugin SDK.

Note that classes derived from this class may not define their constructor, since this is done in a macro. However, the constructor calls the Init function once the object has been setup.

See Also

Init


Top
 

Init

The function Init is a initialization function that is called in the constructor of this interface. Since the constructor is

    virtual void Init();

Parameters

pUID

Contains a pointer to the MRY_INTERFACEID that uniquely identifies this interface.

Remarks

The interface ID that pUID points to should be generated with the MKUID.EXE program that comes with the Plugin SDK.

See Also

CSceneInterface


Top
 

OnEvent

The function OnEvent is called when certain events in Moray take place.

    virtual long OnEvent(long hObjID, int nFlags);

Parameters

hObjID

Contains a handle to the object that the event relates to.

nFlags

Contains the event that is being relayed.

Return Values

MRY_SUCCESS

should be returned by the function.

MRY_NTC_REQ_RECALC

can be returned (see Remarks).

Remarks

Moray will call the function with the following values of nFlags:


The plugin should respond to these events if it references objects in a scene. For example, the lensflare plugin needs to have a reference to a light and a camera. If either of these are deleted by the user, the lensflare plugin must also release its reference. To do this, the plugin watches for MRY_NTC_OBJ_DELETED. When this event occurs, it checks whether it is using the object as a light or camera reference and releases the reference if so.

NEW!Note: MRY_NTC_SCENE_LOADED is no longer sent to this function! See OnLoadSaveEvent.

The plugin can return MRY_NTC_REQ_RECALC in response to the MRY_NTC_OBJ_SELECTED if the plugin requires that the objects be recalculated.

See Also

OnLoadSaveEvent, OnPrintEvent


Top
 

NEW!OnLoadSaveEvent

The function OnLoadSaveEvent is called by Moray when certain events related to loading, saving and pasting occur.

    virtual long OnLoadSaveEvent(long hObjID, int nFlags, long lParam1, long lParam2);

Parameters

hObjID

Contains the handle of the object that the event pertains to.

nFlags

Contains the event that is being relayed.

lParam1

Contains parameters that vary depending on the event.

lParam2

Contains parameters that vary depending on the event.

Return Values

MRY_SUCCESS

should be returned by the function.

Remarks

This function can be derived by the class. The default implementation does nothing. Moray will call the function with the following values of nFlags:

This function should be overridden in derived classes if the plugin needs to keep track of objects in a scene and wants to be notified of these events.

See Also

OnEvent, OnPrintEvent


Top
 

OnPrintEvent

The function OnPrintEvent is called by Moray when certain output events have occurred.

    virtual long OnPrintEvent(long lFileID, int nEvent, pfnOutput fnOut);

Parameters

lFileID

Contains the handle to the file that is used to identify the file to Moray and is passed back to Moray in the call to the fnOut function.

nEvent

Contains the output event that is occurring.

fnOut

Contains a pointer to the function that the plugin must call if it wants to write something to the output stream. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

Remarks

Moray will call this functions at various times while writing the scene file for the raytracer.

nEvent can be one of the following values:


Note that a plugin that implements a plugin object using the Object Interface should not use any of these events to determine when to export itself, since its Export function should be used to do that. If the object requires that something be written to the scene file once, no matter how many instances of that object are created, then this function would be the right place to do that.

The prototype for the fnOut function is:

    void WINAPI fnOutput(long lFileID,const char *pLine);

The lFileID parameter passed to this function must be the one passed in via the lFileID argument.

See Also

OnEvent, OnLoadSaveEvent


Top
 

OnRequiredStreamSize

The function OnRequiredStreamSize is called when Moray is about to save the scene.

    virtual long OnRequiredStreamSize(long hObjID);

Parameters

hObjID

Contains a handle to the object being saved.

Return Values

The

number of bytes that the plugin wants to save must be returned by the function.

Remarks

Moray will call this function when it is saving a scene or an object. It can be used to store data in the MDL file that is scene-dependant, i.e. not related to a plugin object (Plugin Object need to save their data when they are asked to do so by a call to the correspnding function of the Object Interface).

If hObjID is NULL, then Moray is currently saving the whole scene in a file. The plugin should return the number of bytes to store.

See Also

OnWriteToStream, OnReadFromStream


Top
 

OnWriteToStream

The function OnWriteToStream is called by Moray when the interface can write data to the file.

    virtual long OnWriteToStream(long hObjID, pfnStreamIO fnIO, long lStreamID);

Parameters

hObID

Reserved, currently is NULL.

fnIO

Contains a pointer to the function that must be used to write the data to the file.

lStreamID

Contains the ID of the MDL file that is being written.

Return Values

The function should return MRY_SUCCESS. The return value is currently ignored.

Remarks

The function is only called if the OnRequiredStreamSize function returns a size greater 0.
The function is called after the entire scene has been written by Moray.
To write data to the file use the fnIO function that is provided by Moray.
The prototype for this function is:

    void WINAPI fnIO(long lStreamID,void *pData,unsigned int nLength);

The lStreamID that is passed to this function must be the lStreamID that was passed to the OnWriteToStream function.

See Also

OnRequiredStreamSize, OnReadFromStream


Top
 

OnReadFromStream

The function OnReadFromStream is called by Moray when the scene interface should read data from the MDL file.

    virtual long OnReadFromStream(long lDataLength, pfnStreamIO fnIO, long lStreamID);

Parameters

lDataLength

Contains the number of bytes this function is allowed to read.

fnIO

Contains a pointer to the function that must be used to read the data from the file.

lStreamID

Contains the ID of the MDL file that is being read.

Return Values

The function should return MRY_SUCCESS. The return value is currently ignored.

Remarks

The function is only called if the OnRequiredStreamSize function returns a size greater 0.
The function is called after the entire scene has been read by Moray. If you need to work with the objects in the scene immediately after loading a scene, use the OnEvent function and listen for the MRY_NTC_SCENE_LOADED event. When this event is signaled the entire scene has been loaded and all objects, references, cameras and views have been setup.
To read data from the file use the fnIO function that is provided by Moray.
The prototype for this function is:

    void WINAPI fnIO(long lStreamID,void *pData,unsigned int nLength);

The lStreamID that is passed to this function must be the lStreamID that was passed to the OnReadFromStream function.

See Also

OnRequiredStreamSize, OnWriteToStream


Top
 

OnRedrawEvent

The function OnRedrawEvent is called by Moray to inform the plugin of redraw events occurring in specific views.

    virtual long OnRedrawEvent(int nEventID, LPMRY_SCN_VIEWINFO pViewInfo);

Parameters

nEventID

The event that is being signalled.

pViewInfo

a pointer to a MRY_SCN_VIEWINFO struct that is already filled out.

Return Values

MRY_SUCCESS

should be returned (currently ignored by Moray).

Remarks

The nEventID indicates at what stage of the drawing process we are at. It can be one of the following values:



Note that the MRY_SCN_VIEWINFO struct pointed to by pViewInfo is already valid and the plugin does not need to call GetViewInfo to obtain this information.

See Also

MRY_SCN_VIEWINFO


Top
 

OnGet3DWireframeData

The function OnGet3DWireframeData is called by Moray when the plugin can create wireframes for things not implemented by an Object Interface.

    virtual long OnGet3DWireframeData(long *pnNumVects, long *pnNumEdges, long* nReserved);

Parameters

pnNumVects

Contains a pointer to a variable where the plugin should store the number of 3D vertices it needs to create for the wireframe. See Remarks.

pnNumEdges

Contains a pointer to a variable where the plugin should store the number of 3D edges it needs to create for the wireframe. See Remarks.

nReserved

is reserved for future use.

Return Values

MRY_SUCCESS

always (currently ignored by Moray).

Remarks

If the plugin does not know ahead of time how many vertices and edges it will require, it should write MRY_OBJ_LAZY_WIREFRAME to both locations pointed to by pnNumVects and pnNumEdges. In this case Moray will then call the OnBuildSceneLazyWireframe functions to let the plugin create the wireframe.

If the plugin knows ahead of time how many vertices and edges it will require, it should set the locations pointed to by pnNumVects and pnNumEdges accordingly. In this case Moray will then call OnBuildSceneWireframe function to let the plugin create the wireframe.

See Also

OnBuildSceneWireframe, OnBuildSceneLazyWireframe


Top
 

OnBuildSceneWireframe

The function OnBuildSceneWireframe is called by Moray when the plugin can create wireframes for things not implemented by an Object Interface.

    virtual void OnBuildSceneWireframe(pfnAddSceneVertex fnAddVertex, pfnAddSceneEdge fnAddEdge);

Parameters

fnAddVertex

Contains a pointer to a function that should be called to create a vertex.

fnAddEdge

Contains a pointer to a function that should be called to create an edge.

Remarks

If the plugin knows ahead of time how many vertices and edges it will require, it should set the locations pointed to by pnNumVects and pnNumEdges in the call to OnGet3DWireframeData accordingly. In this case Moray will then call this function to let the plugin create the wireframe. The function is passed two pointers to functions that can be used to create vertices and edges. The functions that are passed to the plugin to let it create vertices and edges are defined as follows:

See Also

OnGet3DWireframeData, OnBuildSceneLazyWireframe


Top
 

OnBuildSceneLazyWireframe

The function OnBuildSceneLazyWireframe is called by Moray when the plugin can create wireframes for things not implemented by an Object Interface.

    virtual void OnBuildSceneLazyWireframe(pfnAddSceneVertexEdge fnAddVertexEdge);

Parameters

fnAddVertexEdge

Contains a pointer to a function that should be called to create an edge.

Remarks

If the plugin does not know ahead of time how many vertices and edges it will require, it should write MRY_OBJ_LAZY_WIREFRAME to both locations pointed to by pnNumVects and pnNumEdges in the call to OnGet3DWireframeData.
In this case Moray will then call this functions to let the plugin create the wireframe. The function is passed a pointer to a function that can be used to create an edge. Moray will collect the edges and will then merge the vertices and create its own vertex and edge list. This also means that using this form of wireframe generation is slower than if the plugin knows ahead of time how many vertices and edges it will require. Since this function can be called regularly, try to avoid using the lazy method. The function that is passed to the plugin to let it create an edge is defined as follows:

See Also

OnGet3DWireframeData, OnBuildSceneWireframe


Top
 

CheckCursorShape

The function CheckCursorShape is called by Moray to allow the plugin to make Moray display a different mouse cursor over a specific view.

    virtual long OnCheckCursorShape(long hView, long *lShape);

Parameters

hView

contains the handle of the view that is currently being queried about mouse cursor shape.

lShape

contains a pointer to the custom mouse cursor or the idnetifier of the built-in cursor.

Return Values

This function can return either of the following values to make Moray respond accordingly:

MRY_CRS_CUSTOM

if Moray should display a cursor that is provided by the plugin.

MRY_CRS_BUILT_IN

if Moray should display one of the built-in cursors.

MRY_CRS_DONT_CARE

if the plugin does not want to override the cursor being displayed by Moray.

Remarks

Moray will query the plugin if it wants to display a different cursor when the mouse if over a specific view.

The plugin can make Moray display a cursor that is built-in to Moray by returning MRY_CRS_BUILT_IN and setting lShape to one of the following values:


The plugin can also load its own cursor (using Win32 API function LoadCursor) and write the HCURSOR value into the long pointed to by lShape.


Top
 

OnExecuteUndo

The function OnExecuteUndo indicates that the undo action that the plugin previously created should be executed.

    virtual long OnExecuteUndo(LPMRY_SCN_UNDO_INFO pUndoInfo);

Parameters

pUndoInfo

contains a pointer to the MRY_SCN_UNDO_INFO structure that specifies the undo action and was passed to the PushOntoUndoStack function.

Return Values

This function can return any combination of the following flags to make Moray do the required action(s):

MRY_SCN_UNDO_RECALC

- if the wireframe display has changed (e.g. an object has been deleted). Moray will recalculate the wireframe display. Mostly this flag will be combined with the MRY_SCN_UNDO_REDRAW flag.

MRY_SCN_UNDO_REDRAW

- to make Moray redraw all the views.

MRY_SCN_UNDO_DOMENU

- to make Moray update the menu of the currently selected object.

MRY_SCN_UNDO_UPDATETREE

- to make Moray update the Object tree (i.e. Browser and Select Tab).

Remarks

Note that the plugin should not release any data that it may have created for this undo action. Even though once the action has been undone it is no longer needed, the plugin should only delete this when the OnReleaseUndo function is called. This function is called when the user undoes an action.

See Also

PushOntoUndoStack, MRY_SCN_UNDO_INFO


Top
 

OnReleaseUndo

The function OnReleaseUndo indicates that the undo action that the plugin previously created should be released.

    virtual void OnReleaseUndo(LPMRY_SCN_UNDO_INFO pUndoInfo);

Parameters

pUndoInfo

contains a pointer to the MRY_SCN_UNDO_INFO structure that specifies the undo action and was passed to the PushOntoUndoStack function.

Return Values

This

function should return MRY_SUCCESS.

Remarks

This function is called when the user undoes an action or when the user clears the Undo Buffer or the undo action is removed from the bottom of the Undo stack. The plugin should release any data it has associated with this undo action.

See Also

PushOntoUndoStack, MRY_SCN_UNDO_INFO


Top
 

GetFunctions

The function GetFunctions returns the interface pointer to a MRY_INTERFACE struct.

    LPMRY_INTERFACE GetFunctions();
Top
 

GetSceneFunctions

The function GetSceneFunctions returns the pointer to this interfaces function block (a MRY_SCENEFUNCS struct).

    LPMRY_SCENEFUNCS GetSceneFunctions();
Top
 

DECLARE_SCENE_STATIC

The function DECLARE_SCENE_STATIC (a macro) must be used in classes derived from CSceneInterface.

    DECLARE_SCENE_STATIC(X)

Parameters

X

Contains the name of the derived class.

Remarks

In order to connect the C++ class to the C-based interface, a number of static variables need to be created. This macro declares them and should be placed in the H file in the class declaration of the new CSceneInterface-derived class the plugin is implementing.

See Also

DEFINE_SCENE_STATIC


Top
 

DEFINE_SCENE_STATIC

The function DEFINE_SCENE_STATIC (a macro) must be used in classes derived from CSceneInterface.

    DEFINE_SCENE_STATIC(X, UID)

Parameters

X

Contains the name of the derived class.

UID

Contains the unique ID identifying this interface (a MRY_INTERFACEID struct).

Remarks

In order to connect the C++ class to the C-based interface, a number of static variables need to be created. This macro defines them and should be placed in the CPP file of the new CSceneInterface-derived class the plugin is implementing.

See Also

DECLARE_SCENE_STATIC


Top