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

CPluginObject

The CPluginObject is a base class implementation of an plugin object that uses the C++ Object Interface.

Reference List of Functions

By Function Group Alphabetically
m_bCounting
m_nVersion
m_lState
m_pFunctions
CPluginObject
~CPluginObject
Init
CopyFrom
GetWireFrameInfo
BuildWireframe
BuildLazyWireframe
BuildMeshWireframe
GetInside
GetAttributes
SetAttributes
GetTransforms
SetTransforms
OnValueChanged
OnNotification
GetControlInfo
GetStreamSize
IsValid
Load
Save
PrintPOV
PostPrintPOV
PrintPolyray
PostPrintPolyray
ReadDouble
ReadLong
ReadByte
Read
WriteDouble
WriteLong
WriteByte
Write
PrintLine
PrintFormat
DECLARE_FUNCTIONS
DECLARE_STATICS
DECLARE_MFC_STATICS
DEFINE_STATICS
DEFINE_MFC_STATICS
CREATE_FUNCTIONS
BuildLazyWireframe
BuildMeshWireframe
BuildWireframe
CPluginObject
CREATE_FUNCTIONS
CopyFrom
DECLARE_FUNCTIONS
DECLARE_MFC_STATICS
DECLARE_STATICS
DEFINE_MFC_STATICS
DEFINE_STATICS
GetAttributes
GetControlInfo
GetInside
GetStreamSize
GetTransforms
GetWireFrameInfo
Init
IsValid
Load
OnNotification
OnValueChanged
PostPrintPOV
PostPrintPolyray
PrintFormat
PrintLine
PrintPOV
PrintPolyray
Read
ReadByte
ReadDouble
ReadLong
Save
SetAttributes
SetTransforms
Write
WriteByte
WriteDouble
WriteLong
m_bCounting
m_lState
m_nVersion
m_pFunctions
~CPluginObject



 

m_bCounting


   bool m_bCounting; [protected]

The member variable m_bCounting is a boolean flag that indicates whether the object is currently counting the bytes for the output stream. See Save and GetStreamSize.


Top
 

m_nVersion


   int m_nVersion; [protected]

The member variable m_nVersion is an integer containing the version of the MDL file being loaded or saved.


Top
 

m_lState


   long m_lState; [protected]

The member variable m_lState is a long integer containing flags that indicate certain object states.


Top
 

m_pFunctions


   LPMRY_OBJECTFUNCS m_pFunctions; [protected]

The member variable m_pFunctions is a pointer to the Object Interface.


Top
 

CPluginObject

The function CPluginObject is the constructor of this class.

    CPluginObject(LPMRY_OBJECTFUNCS pFuncs);

Parameters

pFuncs

contains a pointer to the Object interface functions.

Remarks

The constructor simply sets the member variables to an initialized state.

A derived class should place all member initialization into the Init function and should call Init from this constructor.


Top
 

~CPluginObject

The function ~CPluginObject is the destructor of this class

    virtual ~CPluginObject();

Remarks

The destructor does nothing in this base class.


Top
 

Init

The function Init is a pure virtual function that is called when a plugin object is being created or loaded.

    virtual void Init()=0;

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function should initialize all member variables to a valid default state.


Top
 

CopyFrom

The function CopyFrom must be implemented by derived classes.

    void CopyFrom(const X* pX)

Remarks

This base class does not declare or implement this function, but any derived objects must implement this function, replacing the X with the name of the plugin objects class.

This function should then copy the members of the instance pointed to by pX to its own member variables. If it does not make sense to copy the members, they must then be set to default values.


Top
 

GetWireFrameInfo

The function GetWireFrameInfo is called to retrieve the wireframe information of a plugin object before the wireframe is generated.

    virtual void GetWireFrameInfo(long *vertNum, long *edgeNum)=0;

Parameters

pVertNum

Contains a pointer to where the number of vertices required should be stored.

pEdgeNum

Contains a pointer to where the number of edges required should be stored.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is called for a plugin object to request information about its wireframe representation.

If the object has no wireframe, set both locations pointed to by pVertNum and pEdgeNum to zero.

If the number of vertices and edges is not known ahead of time, set both the locations pointed to by pVertNum and pEdgeNum to MRY_OBJ_LAZY_WIREFRAME.
Doing this will allow the plugin to simply provide edges to Moray in response to the BuildLazyWireframe function. Moray will collect the edges and will then extract the vertices from the edges provided.

If at all possible, the plugin should provide the number of vertices and edges in response to this function and then provide the vertices and edges in the BuildWireframe function. Using the alternative way of specifying the wireframe (using the BuildLazyWireframe function) is much slower.

See Also

BuildWireframe, BuildLazyWireframe


Top
 

BuildWireframe

The function BuildWireframe may be called when a plugin object needs to generate its wireframe. See GetWireFrameInfo.

    virtual void BuildWireframe(long lObjID, pfnAddVertex fnAddVertex, pfnAddEdge fnAddEdge)=0;

Parameters

lObjID

Contains the handle that Moray associates with this object. See Remarks.

fnAddVertex

Contains a pointer to the function that should be called to add a vertex.

fnAddEdge

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

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is called immediately after GetWireFrameInfo if the plugin set the number of vertices and edges in response to the GetWireFrameInfo function.

Moray provides pointers to two functions that the plugin must use to create the wireframe. The first function must be used to add vertices and the second one to add edges.
The prototypes of the functions are:

    void WINAPI fnAddVertex(long lObjID,double dX,double dY,double dZ);
    void WINAPI fnAddEdge(long lObjID,long nVertex1, long nVertex2);

The plugin can call fnAddEdge before the corresponding fnAddVertex call has been made (when the wireframe has been built, the vertices must obviously have been added, though!). Note that the order of the calls to each function determines the zero-based index of the element being added. So the first call to fnAddVertex adds the vertex with the index zero, the second call adds the vertex with index one, etc. The same applies to the calls to fnAddEdge.

The nVertex1 and nVertex2 parameters are zero-based indeces to the vertices that were (or will be) added by calls to fnAddVertex.

The lObjID that is passed to this function must be passed through to the fnAddVertex and fnAddEdge function, so that Moray knows which object to add the vertices to. Do not attempt to pass a different lObjID to the functions as this will crash Moray.

Note that the plugin can only determine the wireframe of a plugin object, the wireframe of other objects cannot be set or changed from a plugin.

See Also

BuildLazyWireframe, GetWireFrameInfo


Top
 

BuildLazyWireframe

The function BuildLazyWireframe may be called when a plugin object needs to generate its wireframe. See GetWireFrameInfo.

    virtual void BuildLazyWireframe(long lObjID, pfnAddVertexEdge fnAddVertexEdge)=0;

Parameters

lObjID

Contains the handle that Moray associates with this object. See Remarks.

fnAddVertexEdge

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

Remarks

This base class does not implement this function, any derived objects must implement this function.

This method is an alternative way of building the wireframe of the plugin object. The plugin should try to use the BuildWireframe method if possible.

This function should only be used if the plugin cannot determine the number of vertices and edges ahead of actually building the wireframe.

The prototype for the function to add an edge is:

    void WINAPI fnAddVertexEdge(long lObjID,LPMRY_VERTEXEDGE pEdge);

The lObjID that is passed to this function must be passed through to the fnAddVertexEdge function, so that Moray knows which object to add the edge to. Do not attempt to pass a different lObjID to the function as this will crash Moray. The pEdge parameter points to a MRY_VERTEXEDGE structure.

See Also

BuildWireframe, GetWireFrameInfo, MRY_VERTEXEDGE


Top
 

NEW!BuildMeshWireframe

The function BuildMeshWireframe may be called when a plugin object needs to generate its wireframe. See GetWireFrameInfo.

    virtual void BuildMeshWireframe(long lObjID, LPMRY_WIREFRAME_BUILDING pBuilder)=0;

Parameters

lObjID

Contains the handle that Moray associates with this object. See Remarks.

pBuilder

Contains a pointer to a wireframe building MRY_WIREFRAME_BUILDING struct which makes functions available that allow the plugin to create solid wireframes.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This method is a new way of building the wireframe of the plugin object. The plugin should try to use this method if possible. See the documentation of the MRY_WIREFRAME_BUILDING structure for details.

See Also

BuildWireframe, GetWireFrameInfo, MRY_WIREFRAME_BUILDING


Top
 

GetInside

The function GetInside determines whether a point is inside or outside the plugin object.

    virtual void GetInside(double *px, double *py, double *pz, int *nSign, double *dValue)=0;

Parameters

px, py, pz

Contains the coordinate of the point to test for inside/outside.

pnSign

Contains the sign of the result. See Remarks.

pdValue

Currently not used.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is called when the user attempts to evaluate a CSG object. If the plugin object is part of a CSG object, it will be queried whether certain points lie inside or outside the object.

pnSign should be set to one of the following values.


Top
 

NEW!GetAttributes

The function GetAttributes retrieves the attributes of the object.

    virtual long GetAttributes(LPMRY_OBJ_ATTRIBUTES pAttribs)=0;

Parameters

pAttribs

contains a pointer to the MRY_OBJ_ATTRIBUTE struct that is to receive the attributes.

Remarks

See the GetAttributes function of the Scene Interface for details.


Top
 

NEW!SetAttributes

The function SetAttributes sets certain attributes of the object.

    virtual long SetAttributes(LPMRY_OBJ_ATTRIBUTES pAttribs, int nFlags)=0;

Parameters

pAttribs

contains a pointer to the MRY_OBJ_ATTRIBUTE struct that contains the attributes to be set.

Remarks

See the SetAttributes function of the Scene Interface for details.


Top
 

NEW!GetTransforms

The function GetTransforms retrieves the transformations of the object.

    virtual long GetTransforms(LPMRY_OBJ_TRANSFORMS pXForms)=0;

Parameters

pAttribs

contains a pointer to the MRY_OBJ_TRANSFORMS struct that is to receive the transformations.

Remarks

See the GetTransforms function of the Scene Interface for details.


Top
 

NEW!SetTransforms

The function SetTransforms sets the transformations of the object

    virtual long SetTransforms(LPMRY_OBJ_TRANSFORMS pXForms, int nFlags)=0;

Parameters

pAttribs

contains a pointer to the MRY_OBJ_TRANSFORMS struct that contains the transformations to be set.

Remarks

See the SetTransforms function of the Scene Interface for details.


Top
 

OnValueChanged

The function OnValueChanged is called when the value of a control of the plugin objects dialog has changed.

    virtual long OnValueChanged(int nID, double dValue)=0;

Parameters

nID

Contains the ID of the control that has changed.

dValue

Contains the new value of the control.

Return Values

The function should return a combination of the following flags:

MRY_STAT_CHANGED

if the scene has changed due to the value being changed. This is used to mark the scene as "dirty", i.e. the user will be prompted to save the scene when exiting.

MRY_STAT_REDRAW_SEL

if the object should be redrawn, since its wireframe representation has changed.

MRY_STAT_REDRAW_TEXTURE

if the texture of the object should be redrawn.

MRY_STAT_REDRAW_BROWSER

if the browser should be refreshed.

MRY_STAT_REDRAW_ALL

if the whole scene should be redrawn.

MRY_STAT_REINIT_ALL

if all objects should recalculate their wireframes. There should be no need to use this flag.

MRY_STAT_REDRAW_3D

if only 3D views should be redrawn.

MRY_STAT_TEXTURE_CHANGED

if the wireframe representation of a texture changed. There should be no need to use this flag.

MRY_STAT_REINIT_CTRLS

all the controls of this dialog should be reinitialized. Moray will call GetControlInfo for all IDs of this dialog. If the dialog contains dependencies between values, this flag should be useful.

MRY_STAT_REINIT_PLUGIN_WIREFRAMES$NEW$

if the wireframes of a plugin should be redrawn. This applies to wireframes that are generated by a scene interface, not by an plugin object.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is only called if the plugin objects dialog is based on CPluginDialog and only if the default routing hasn't been overriden in that class. See OnValueChanged of the CPluginDialog class.

See Also

CPluginDialog, OnValueChanged


Top
 

NEW!OnNotification

The function OnNotification is called when events related to this object occur.

    virtual long OnNotification(long lEvent);

Parameters

lEvent

Contains the ID of the event that has occurred.

Return Values

MRY_SUCCESS

should be returned (currently ignored by Moray).

Remarks

This function is called when the object is selected or deselected.
The lEvent parameter indicates what is being signalled and can be one of the following values:


Top
 

GetControlInfo

The function GetControlInfo is called to determine whether a control of a plugin objects dialog should use one of Morays spinners or sliders.

    virtual bool GetControlInfo(int nID, LPMRY_CONTROL_INFO pCtrl)=0;

Parameters

nID

Contains the ID of the control of this objects dialog on the Modify Tab.

pCtrl

Contains a pointer to a MRY_CONTROL_INFO struct that holds the control information.

Return Values

TRUE

should be returned if the control associated with the ID should use Morays spinners or sliders.

FALSE

should be returned if the control associated with the ID will be handled by the plugin.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is only called if the plugin objects dialog is based on CPluginDialog and only if the default routing hasn't been overriden in that class. See GetControlInfo of the CPluginDialog class.

Moray allows a plugin to use its spinners and sliders in any custom dialogs it adds to the Modify Tab. This is recommended for all floating point and integer values that are present on the Modify Tab. The spinners are basically an edit box with an up and down arrow that allows the user to increment, decrement or drag the value with the mouse.
When the user changes the spinners or sliders, Moray calls the OnValueChanged function.

See Also

CPluginDialog, GetControlInfo, OnValueChanged


Top
 

GetStreamSize

The function GetStreamSize is called when Moray needs to know how many bytes a plugin object requires to store itself to a MDL file.

    virtual long GetStreamSize();

Remarks

This function probably does not need to be overriden.

The default implementation sets the m_bCounting flag and calls Save. Since all I/O goes through the Read... functions, these functions count the number of bytes that would be saved.

See Also

Save, m_bCounting


Top
 

IsValid

The function IsValid determines whether the object is valid.

    virtual long IsValid();

Return Values

TRUE

if the object could be properly created.

FALSE

if the object could not be properly created.

Remarks

This function probably does not need to be overriden.

This function is called immediately after the objects constructor has run. It can be used to signal that the creation of the object failed. For example, if the object requires some external files and these cannot be found, this function can be overridden and can return FALSE.

The default implementation returns TRUE. NEW!You can determine whether the object is being created or loaded by checking the lAttributes member of the Object Interface pointed to by m_pFunctions.

If lAttributes has the MRY_ATTR_OBJ_LOADING flag set, the object is being loaded. If it is clear the object is being created in response to the user requesting it.

See Also

Load


Top
 

Load

The function Load is called when a plugin object needs to be loaded from a MDL file.

    virtual void Load()=0; [protected]

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function is called immediately after the object has been constructed when the object is being loaded from file.

To read data from the file use the Read... functions that are provided by this class.

A plugin object should save its own version number as the first byte in the Save function, so that later versions of the plugin can handle older MDL files.

See Also

CPluginObject, IsValid, Copy, Save


Top
 

Save

The function Save is called when a plugin object needs to save itself to a MDL file.

    virtual void Save()=0; [protected]

Remarks

This base class does not implement this function, any derived objects must implement this function.

To write data to the MDL file use the Write... functions that are provided by this class.

This function is actually called twice, the first time with the m_bCounting flag set. During the first run the Write... functions simply count the number of bytes that this Save function generates. During the second run, the bytes are actually written to file.
Make sure that both runs call the Write.. functions in exactly the same way.

A plugin object should save a version number as the first byte in the MDL file. This will make sure that a later version of the plugin can handle MDL files that were saved with this plugin.

A plugin object must be able to read earlier versions of itself and degrade gracefully, using sensible defaults for values that were previously not saved in the MDL file. If you find that older versions of the object cannot degrade gracefully, you must create a different plugin object instead and implement both objects in this plugin.

See Also

Load, GetStreamSize


Top
 

PrintPOV

The function PrintPOV is called when a plugin object needs to be exported to a POV file.

    virtual long PrintPOV(const char * pszName)=0; [protected]

Parameters

pszName

Contains the name of the object.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function must use the PrintFormat function to export text to the POV file.

See Also

PrintFormat


Top
 

PostPrintPOV

The function PostPrintPOV is called when a plugin object has been exported to a POV file.

    virtual void PostPrintPOV()=0; [protected]

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function can use the PrintFormat function to export more text to the POV file. It should also set the MRY_OBJ_PRINTED flag of the m_lState member variable.

See Also

PrintFormat


Top
 

PrintPolyray

The function PrintPolyray is called when a plugin object needs to be exported to a PI file.

    virtual long PrintPolyray(const char * pszName)=0; [protected]

Parameters

pszName

Contains the name of the object.

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function must use the PrintFormat function to export text to the PI file.

See Also

PrintFormat


Top
 

PostPrintPolyray

The function PostPrintPolyray is called when a plugin object has been exported to a POV file.

    virtual void PostPrintPolyray()=0;

Remarks

This base class does not implement this function, any derived objects must implement this function.

This function can use the PrintFormat function to export more text to the POV file. It should also set the MRY_OBJ_PRINTED flag of the m_lState member variable.

See Also

PrintFormat


Top
 

ReadDouble

The function ReadDouble can be used to read a double from a MDL file.

    void ReadDouble(double & dValue); [protected]

Parameters

dValue

Contains a reference to the double being read.

Remarks

This function may only be used inside the Load function.

See Also

ReadByte, ReadLong, Read


Top
 

ReadLong

The function ReadLong can be used to read a long from a MDL file.

    void ReadLong(long & lValue); [protected]

Parameters

lValue

Contains a reference to the long being read.

Remarks

This function may only be used inside the Load function.

See Also

ReadByte, ReadDouble, Read


Top
 

ReadByte

The function ReadByte can be used to read a byte from a MDL file.

    void ReadByte(unsigned char& nValue); [protected]

Parameters

nValue

Contains a reference to the byte being read.

Remarks

This function may only be used inside the Load function.

See Also

ReadLong, ReadDouble, Read


Top
 

Read

The function Read can be used to read data from a MDL file.

    void Read(void* pData, long lDataSize); [protected]

Parameters

pData

Contains the address where to place the data being read.

lDataSize

Contains the number of bytes to read.

Remarks

This function may only be used inside the Load function.

See Also

ReadByte, ReadLong, ReadDouble


Top
 

WriteDouble

The function WriteDouble can be used to write a double to a MDL file.

    void WriteDouble(double & dValue); [protected]

Parameters

dValue

Contains a reference to the double to be written.

Remarks

This function may only be used inside the Save function.

See Also

WriteByte, WriteLong, Write


Top
 

WriteLong

The function WriteLong can be used to write a long to a MDL file.

    void WriteLong(long& lValue); [protected]

Parameters

dValue

Contains a reference to the long to be written.

Remarks

This function may only be used inside the Save function.

See Also

WriteByte, WriteDouble, Write


Top
 

WriteByte

The function WriteByte can be used to write a byte to a MDL file.

    void WriteByte(unsigned char& nValue); [protected]

Parameters

nValue

Contains a reference to the byte to be written.

Remarks

This function may only be used inside the Save function.

See Also

WriteLong, WriteDouble, Write


Top
 

Write

The function Write can be used to write data to a MDL file.

    void Write(void* pData, long lDataSize); [protected]

Parameters

pData

Contains the address of the data to be written to file.

lDataSize

Contains the number of bytes to write.

Remarks

This function may only be used inside the Save function.

See Also

WriteByte, WriteLong, WriteDouble


Top
 

PrintLine

The function PrintLine can be called to write a string to the exported file (POV or PI).

    static void PrintLine(const char* pLine); [protected]

Parameters

pLine

Contains the string to be printed.

Remarks

This function may only be called from the PrintPOV or PrintPolyray functions.

See Also

PrintFormat


Top
 

PrintFormat

The function PrintFormat can be called to write a printf() style string to the exported file (POV or PI).

    static void PrintFormat(const char* pszFormat, ...); [protected]

Parameters

pszFormat

Contains a printf()-style format string that determines how the line is to be formatted.

Remarks

This function may only be called from the PrintPOV or PrintPolyray functions.

The resulting buffer may not be longer than 2048 bytes.

See Also

PrintLine


Top
 

DECLARE_FUNCTIONS

The function DECLARE_FUNCTIONS is a macro that declares the statics that a class derived from CPluginObject requires if

    DECLARE_FUNCTIONS(X);

Parameters

X

Contains the name of the class whose functions are to be defined.

Remarks

This function should be used in the header file after the class declaration.

If the plugin is MFC-based this macro is not required.


Top
 

DECLARE_STATICS

The macro DECLARE_STATICS declares the statics that a class derived from CPluginObject and not using MFC requires.

This function should be used in a public area of the class declaration.

If the plugin is MFC-based this macro is not required.

See Also

DEFINE_STATICS


Top
 

DECLARE_MFC_STATICS

The macro DECLARE_MFC_STATICS declares the statics that a class derived from CPluginObject and using MFC requires.

This function should be used in a public area of the class declaration.

If the plugin is MFC-based this macro is required.

See Also

DEFINE_MFC_STATICS


Top
 

DEFINE_STATICS

The function DEFINE_STATICS defines the statics that a class derived from CPluginObject requires.

    DEFINE_STATICS(X, pszName, pszMask, nAttr)

Parameters

X

contains the name of the new class being created.

pszName

contains the name of the object type.

pszName

contains the mask for the name that should be used when creating new objects of this object type.

nAttr

contains flags that indicate what type of object this is.

Remarks

The nAttr parameter can be a combination of the following flags:



Note that MRY_ATTR_CAN_BE_TEXTURED and MRY_ATTR_CAN_BE_MULTI_TEXTURED are mutually exclusive and should not be used together.

This function should be used in a public area of the class declaration.

If the plugin is MFC-based this macro is not required.

See Also

DECLARE_STATICS


Top
 

DEFINE_MFC_STATICS

The macro DEFINE_MFC_STATICS defines the statics that a class derived from CPluginObject requires.

This function should be used in a public area of the class declaration.

If the plugin is MFC-based this macro is required.

See Also

DECLARE_STATICS


Top
 

CREATE_FUNCTIONS

The function CREATE_FUNCTIONS defines the statics that a class derived from CPluginObject requires.

    CREATE_FUNCTIONS(X)

Parameters

X

contains the name of the new class being created.

Remarks

This function should be used in a public area of the class declaration.

If the plugin is MFC-based this macro is required.

See Also

DECLARE_STATICS


Top