CSceneInterface

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

The function CSceneInterface is the constructor of this interface.

Parameters

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

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

Parameters

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

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

Parameters

Return Values

Remarks

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

• MRY_NTC_OBJ_DELETED - the object whose handle is hObjID is about to be deleted.
• MRY_NTC_OBJ_SELECTED - the object whose handle is hObjID has just been selected.
• MRY_NTC_OBJ_CREATED - the object whose handle is hObjID has just been created.
• MRY_NTC_OBJ_TRANSFORMED - the object whose handle is hObjID has just been transformed.
• MRY_NTC_SCENENAME_CHANGED - the name of the current scene has changed. In this case hObjID is zero.
• MRY_NTC_MORAY_BOOTED - Moray has just started and everything is loaded and ready to go.
• MRY_NTC_MORAY_SHUTDOWN - Moray is about to shutdown.
• MRY_NTC_RESIZED - Moray has been resized.
• MRY_NTC_OBJ_CHANGED - the object whose handle is hObjID has just been changed.
• MRY_NTC_OBJ_RENAMED - the object whose handle is hObjID has just been renamed.
• MRY_NTC_TEX_CHANGED - the texture item whose handle is hObjID has just been changed.

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.

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

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

Parameters

Return Values

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:

• MRY_NTC_SCENE_LOADED - a new scene has been loaded.
• MRY_NTC_PASTING_OBJECT - a paste operation is about to start.
• MRY_NTC_OBJECT_PASTED - the paste operation has ended.
• MRY_NTC_MERGING_SCENE - a scene is about to be merged from file.
• MRY_NTC_MERGED_OBJ_RENAMED - an object has been renamed, due to a merge operation. hObj contains the handle of the object and lParam1 points to a zero-terminated string containing the name before the rename operation and lParam2 points to a zero-terminated string containing the name after the rename operation.
• MRY_NTC_SCENE_MERGED - the scene has been merged.

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

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

Parameters

Return Values

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:

• MRY_NTC_BEGIN_POVINI - the INI file for POV-Ray has just been opened.
• MRY_NTC_END_POVINI - the INI file for POV-Ray is about to be closed.
• MRY_NTC_BEGIN_POLYINI - the INI file for Polyray has just been opened.
• MRY_NTC_END_POLYINI - the INI file for Polyray is about to be closed.
• MRY_NTC_BEGIN_POVEXPORT - the POV scene file for POV-Ray has just been opened.
• MRY_NTC_BEGIN_POLYEXPORT - the PI scene file for Polyray has just been opened.
• MRY_NTC_END_EXPORT - the scene file for the raytracer is about to be closed.
• MRY_NTC_BEGIN_CAMERAS - the cameras are about to be written to the scene file.
• MRY_NTC_END_CAMERAS - the cameras have just been written to the scene file.
• MRY_NTC_BEGIN_LIGHTS - the lights are about to be written to the scene file.
• MRY_NTC_END_LIGHTS - the lights have just been written to the scene file.
• MRY_NTC_BEGIN_TEXTURES - the textures are about to be written to the scene include file.
• MRY_NTC_END_TEXTURES - the cameras have just been written to the scene include file.
• MRY_NTC_BEGIN_REFERENCED_OBJS - the referenced objects are about to be written to the scene file.
• MRY_NTC_END_REFERENCED_OBJS - the referenced objects have just been written to the scene file.
• MRY_NTC_BEGIN_OBJECTS - the objects are about to be written to the scene file.
• MRY_NTC_END_OBJECTS - the objects just been written to the scene file.

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

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

Parameters

Return Values

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

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

Parameters

Return Values

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

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

Parameters

Return Values

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

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

Parameters

Return Values

Remarks

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

• MRY_NTC_VIEW_CLEARED - the views bitmap has been cleared, if the view has a backdrop, it has been painted. Since the drawing is buffered, the screen still shows the previous view.
• MRY_NTC_STARTING_REDRAW - the grid and viewport labels have been drawn, Moray is about to start drawing wireframe lines.
• MRY_NTC_TIME_SLICE_OVER - Moray is done drawing a number of lines, but there are still some more left. Immediately after this call, the buffer is updated to the screen. This event can come multiple times, each time more wireframes lines will have been drawn.
• MRY_NTC_WINDOW_UPDATED - Moray has updated the screen.
• MRY_NTC_REDRAW_DONE - Moray is done drawing all the lines.

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

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

Parameters

Return Values

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

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

Parameters

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:

• fnAddSceneVertex(double dX,double dY,double dZ) - creates a vertex at the location specifies.
• fnAddSceneEdge(long nVertex1, long nVertex2,long lColor) - nVertex1 contains the zero-based index of the first vertex of this edge. nVertex2 contains the zero-based index of the second vertex of this edge. lColor should be set the color that the edge should display in (in the format 0x00RRGGBB).

See Also

OnGet3DWireframeData, OnBuildSceneLazyWireframe

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

Parameters

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:

• fnAddSceneVertexEdge(LPMRY_VERTEXEDGE pEdge,long lColor) - See MRY_VERTEXEDGE for details of the structure. lColor should be set the color that the edge should display in (in the format 0x00RRGGBB).

See Also

OnGet3DWireframeData, OnBuildSceneWireframe

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

Parameters

Return Values

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:

• MRY_CRSSHAPE_ARROW - the standard arrow-shaped cursor.
• MRY_CRSSHAPE_TIMER - the standard hourglass cursor.
• MRY_CRSSHAPE_CROSSHAIR - the crosshair cursor (displayed when selecting objects).
• MRY_CRSSHAPE_CROSSHAIR_UNLOCKED - the crosshair cursor with the open padlock (displayed when selecting objects and holding Shift-Ctrl).
• MRY_CRSSHAPE_ZOOM - the Zoom cursor.
• MRY_CRSSHAPE_PAN - the Pan cursor.
• MRY_CRSSHAPE_TRACK - the Track cursor.
• MRY_CRSSHAPE_REGION - the Region cursor (when selecting a render region in the 3D views).
• MRY_CRSSHAPE_INSERT - the Insert cursor.
• MRY_CRSSHAPE_DELETE - the Delete cursor.
• MRY_CRSSHAPE_SMOOTH - the Smooth cursor.
• MRY_CRSSHAPE_FROM - the From cursor.
• MRY_CRSSHAPE_TO - the To cursor.
• MRY_CRSSHAPE_TRANSLATE - the Translate cursor.
• MRY_CRSSHAPE_TRANSLATE_IK - the Translate cursor with the IK letters.
• MRY_CRSSHAPE_SCALE - the Scale cursor.
• MRY_CRSSHAPE_ROTATE - the Rotate cursor.
• MRY_CRSSHAPE_HAND - the Hand cursor (the grabber displayed in the browser).
• MRY_CRSSHAPE_HAND_Y - the Hand cursor with a vertical arrow.
• MRY_CRSSHAPE_HAND_XY - the Hand cursor with a vertical and horizontal arrow.
• MRY_CRSSHAPE_URL - the Hand cursor with a pointed finger (displayed by most browsers when hovering over a URL).

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.

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

Parameters

Return Values

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

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

Parameters

Return Values

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

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

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

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

Parameters

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

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

Parameters

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