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.

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.

m_lState

long m_lState; [protected]

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

m_pFunctions

LPMRY_OBJECTFUNCS m_pFunctions; [protected]

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

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.

~CPluginObject

The function ~CPluginObject is the destructor of this class

virtual ~CPluginObject();

Remarks

The destructor does nothing in this base class.

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.

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.

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

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

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.

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.

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.

-1 if the point is inside the object.
+1 if the point is outside the object.

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.

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.

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.

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.

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

See Also

CPluginDialog, OnValueChanged

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:

MRY_OBJ_SELECTED - the object has just been selected.
MRY_OBJ_DESELECTED - the object has just been deselected.

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.

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

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. 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

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

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

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

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

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

PostPrintPolyray

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

virtual void PostPrintPolyray()=0;

Remarks

See Also

PrintFormat

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

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

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

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

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

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

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

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

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

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

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.

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

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

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:

MRY_ATTR_CAN_BE_TEXTURED - indicates the object can have a single textured.
MRY_ATTR_CAN_BE_MULTI_TEXTURED - indicates the object can have multiple textures.
MRY_ATTR_CAN_BE_XFORMED - indicates the object can be transformed.
MRY_ATTR_CAN_BE_GROUPED - indicates the object can be grouped
MRY_ATTR_CAN_BE_CSGD - indicates the object can be safely be used in a CSG object.
MRY_ATTR_CAN_BE_REFERENCED - indicates that references of this object can be safely created.
MRY_ATTR_CAN_REFERENCE_OBJECTS - indicates that this object can reference other objects.
MRY_ATTR_HAS_OBJ_PARAMS - indicates that the object has normal object parameters (texture, visibility, etc.)
MRY_ATTR_NO_DIRECT_CREATION - indicates that the object should not be created directly. This suppresses the buttons on the Create Tab and the menu item in the Create menu.
MRY_ATTR_HAS_ELEM_PARAMS - the object has normal parameters, but cannot be textured.

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

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

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