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

Object Interface



The Object Interface implements the interface to a new object type. The Interface is responsible for creating new instances of the object, and handling the dialog to be placed in the Modify Tab for this type of object.


Reference List of Functions

By Function Group Alphabetically
achObjName
achObjMask
lAttributes
nObjectBitmapID
hDialog
CreateObject
InitObject
LoadObject
SaveObject
GetStreamSize
CopyObject
DestroyObject
GetInside
GetBitmapHandle
GetWireFrameInfo
BuildWireframe
BuildLazyWireframe
BuildMeshWireframe
GetTextureName
PrintObject
PostPrintObject
ChangeState
SetAttributes
GetAttributes
GetTransforms
SetTransforms
Redraw
GetDlgResource
FreeDlgResource
GetControlInfo
ValueChanged
Notify
WindowProc
GetCDialog
FreeCDialog
InitCDialog
BuildLazyWireframe
BuildMeshWireframe
BuildWireframe
ChangeState
CopyObject
CreateObject
DestroyObject
FreeCDialog
FreeDlgResource
GetAttributes
GetBitmapHandle
GetCDialog
GetControlInfo
GetDlgResource
GetInside
GetStreamSize
GetTextureName
GetTransforms
GetWireFrameInfo
InitCDialog
InitObject
LoadObject
Notify
PostPrintObject
PrintObject
Redraw
SaveObject
SetAttributes
SetTransforms
ValueChanged
WindowProc
achObjMask
achObjName
hDialog
lAttributes
nObjectBitmapID



 

achObjName


   char achObjName[MRY_MAX_OD_NAMELEN+1];

The variable achObjName should contain a plain english description of the object type, e.g. 'Torus'.

See Also

MRY_OBJECTFUNCS


Top
 

achObjMask


   char achObjMask[MRY_MAX_OD_NAMELEN+1];

The variable achObjMask should contain a C-like mask for the name of newly created objects of this type.

The name must contain a percent sign followed by a 'd', e.g. 'Torus%03d'. ;%

See Also

MRY_OBJECTFUNCS


Top
 

lAttributes


   long lAttributes;

The variable lAttributes should contain a set of attributes that these objects have. The following attributes are available:


If the object does not specify the MRY_ATTR_HAS_OBJ_PARAMS, but does specify the MRY_ATTR_CAN_BE_TEXTURED flag, Moray will display the Texture Dialog part of the Object Params Dialog.

To allow an interface to determine whether an object is being created or loaded, this variable has a read-only flag MRY_ATTR_OBJ_LOADING. It is valid for the duration of the calls to CreateObject and LoadObject. It is set if the interface is loading objects from a file. If the interface needs to create an instance in response to the user requesting it the flag will not be set.

See Also

MRY_OBJECTFUNCS


Top
 

nObjectBitmapID


   UINT nObjectBitmapID;

The variable nObjectBitmapID should contain the ID of the 16, 24 or 32-bit 20x20 bitmap that is associated with this object type. The bitmap is used in the Create menu, the Create Tab, the Select Tab and the Object Browser. Moray internally converts and resizes as appropriate.

Note that any pixels of the color 0,128,128 will be rendered transparent. You are strongly encouraged to use this color so that your objects are non-square.

See Also

GetBitmapHandle, MRY_OBJECTFUNCS


Top
 

hDialog


   HWND hDialog;

The variable hDialog contains the HWND of the dialog associated with this object.

Note that this is a read-only variable.
NEW!V1.13 and higher

See Also

MRY_OBJECTFUNCS


Top
 

CreateObject

The function CreateObject creates an object instance of the object type this interface handles.

    long WINAPI fnCreateObject();

Return Values

The handle of (pointer to) the object created. If the creation fails, the function should return 0.

Remarks

If this function returns a valid handle (non-zero), Moray will immediately call InitObject if creating the object due to a menu command or CopyObject if creating the object due to duplication or it will call LoadObject if the object is being loaded from file.

See Also

InitObject, LoadObject


Top
 

InitObject

The function InitObject initializes an object.

    void WINAPI fnInitObject(long hObject);

Parameters

hObject

Contains the handle of the object to be initialized.

Remarks

This function is called immediately after CreateObject when an object has been created. This can be as a result of the user clicking on the corresponding entry in the Create menu or Create Tab or if a plugin is used to create a plugin object.

See Also

CreateObject, LoadObject, CopyObject


Top
 

LoadObject

The function LoadObject loads an object from a MDL file.

    void WINAPI fnLoadObject(long hObject, pfnStreamIO fnIO, long lStreamID, int nVersion);

Parameters

hObject

Contains the handle of the object to load from file.

fnIO

Contains a pointer to the function that must be used to read the data of the object.

lStreamID

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

nVersion

Contains the version number of the file.

Remarks

This function is called immediately after CreateObject when the object is being loaded from file. 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 LoadObject function.

The nVersion contains the version of the MDL file being read. This will probably not be of much use at the moment.

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

See Also

CreateObject, CopyObject, SaveObject


Top
 

SaveObject

The function SaveObject saves an object to file.

    void WINAPI fnSaveObject(long hObject, pfnStreamIO, long lStreamID);

Parameters

hObject

Contains the handle of the object to save to a MDL file.

fnIO

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

lStreamID

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

Remarks

This function is called immediately after GetStreamSize to save the object to a MDL file. To write data to the MDL 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 SaveObject function.

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

LoadObject, CopyObject, CreateObject


Top
 

GetStreamSize

The function GetStreamSize calculates the number of bytes this object requires.

    long WINAPI fnGetStreamSize(long hObject);

Parameters

hObject

Contains the handle of the object to query.

Return Values

The number of bytes this plugin object needs to store itself to a MDL file.

Remarks

This function is called just before the plugin object is stored to file. It is required because Moray will write the object to the MDL file in such a way that should the plugin not be available when attempting to load the MDL file, Moray can skip this object and continue loading the rest of the file.

See Also

SaveObject


Top
 

CopyObject

The function CopyObject copies the settings of one object to another.

    void WINAPI fnCopyObject(long hToObject, long hFromObject);

Parameters

hToObject

Contains the handle of the object to be copied to.

hFromObject

Contains the handle of the object to be copied from.

Remarks

This function is called whenever a plugin object is copied. The plugin should copy all internal data of the object.


Top
 

DestroyObject

The function DestroyObject destroys an instance of an object and releases all memory required by the object instance.

    void WINAPI fnDestroyObject(long hObject);

Parameters

hObject

Contains the handle of the object to destroy.

Remarks

Use this function to release any dynamic memory the object has allocated during its lifetime.

See Also

CreateObject


Top
 

GetInside

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

    void WINAPI fnGetInside(long hObject, double *px, double *py, double *pz, int *pnSign, double *pdValue);

Parameters

hObject

Contains the handle of the object whose inside to test.

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

GetBitmapHandle

The function GetBitmapHandle returns a HBITMAP handle to the 16, 24 or 32-bit 20x20 bitmap that is associated with this object.

    long WINAPI fnGetBitmapHandle();

Remarks

This is an function that serves as an alternative to the nObjectBitmapID variable. If you want to generate the bitmap at initialization and cannot provide a resource ID in nObjectBitmapID, then you should set nObjectBitmapID to 0 and implement this function.

The bitmap is used in the Create menu, the Create Tab, the Select Tab and the Object Browser. Moray internally converts and resizes as appropriate.

Note that any pixels of the color 0,128,128 will be rendered transparent. You are strongly encouraged to use this color for the background so that your objects are non-square.

See Also

nObjectBitmapID, MRY_OBJECTFUNCS


Top
 

GetWireFrameInfo

The function GetWireFrameInfo returns the number of vertices and edges required for the wireframe representation of this object.

    void WINAPI fnGetWireFrameInfo(long hObject, long *pVertNum, long *pEdgeNum);

Parameters

hObject

Contains the handle of the object being queried.

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 function is called by Moray for a plugin object to request information about the objects wireframe representation.

Special values for pVertNum and pEdgeNum:


If you want the plugin to provide a solid representation (a shaded objects in the OpenGL views), you must use one of the two new values (MRY_OBJ_MESH_WIREFRAME or MRY_OBJ_TRIANGLE_WIREFRAME). The other values are still supported for backwards compatibility.

If at all possible, the plugin should use the MRY_OBJ_MESH_WIREFRAME method to provide the number of vertices, UV coords, normals and edges in response to this function. This is the fastest way.

Using MRY_OBJ_TRIANGLE_WIREFRAME is probably the slowest way of building the wireframe data, but is fine for smaller wireframes (less than 250 vertices for example).

See Also

BuildWireframe, BuildLazyWireframe, BuildMeshWireframe


Top
 

BuildWireframe

The function BuildWireframe builds the wireframe representation of this object.

    void WINAPI fnBuildWireframe(long hObject, long lObjID, pfnAddVertex fnAddVertex, pfnAddEdge fnAddEdge);

Parameters

hObject

Contains the handle of the object whose wireframe is to be built.

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 function is called immediately after GetWireFrameInfo if the plugin set the number of vertices and edges in response to the GetWireFrameInfo function.

Moray provides 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 from a plugin.

See Also

BuildLazyWireframe, GetWireFrameInfo


Top
 

BuildLazyWireframe

The function BuildLazyWireframe can be used to build the wireframe of an object.

    void WINAPI fnBuildLazyWireframe(long hObject, long lObjID, pfnAddVertexEdge fnAddVertexEdge);

Parameters

hObject

Contains the handle of the object whose wireframe is to be built.

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

BuildMeshWireframe

The function BuildMeshWireframe can be used to build the wireframe of an object.

    void WINAPI fnBuildMeshWireframe(long hObject, long hObjID, LPMRY_WIREFRAME_BUILDING pMeshBuilder);

Parameters

hObject

Contains the handle of the plugin object whose wireframe is to be built.

hObjID

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

pMeshBuilder

Contains a pointer to a MRY_WIREFRAME_BUILDING struct that can be used to define the wireframe of the object.

Remarks

The hObjID parameter is no longer needed by Moray for building the wireframe since the hWireFrameID member of the MRY_WIREFRAME_BUILDING struct pointed to by pMeshBuilder contains the handle of the wireframe being modified. This wireframe handle needs to be passed to all the member functions of the MRY_WIREFRAME_BUILDING struct, so that Moray knows what wireframe you are working on.

See Also

BuildWireframe, GetWireFrameInfo


Top
 

GetTextureName

The function GetTextureName is called by Moray to retrieve the names of the textures an object is using if it using multiple textures.

    long WINAPI fnGetTextureName(long hObject, int nIndex, char *pszTextureName);

Parameters

hObject

Contains the handle of the object being queried.

nIndex

Contains the index of the texture name being retrieved.

pszTextureName

Contains a pointer to where the name of the texture should be written.

Return Values

MRY_SUCCESS

should be returned if the function successfully wrote a texture name to the location polinted to by pszTextureName.

MRY_ERR_NO_MORE_ITEMS

should be returned if no more textures are used by this object (nIndex is too high).

Remarks

The function GetTextureName is called by Moray when a user selects the 'Delete Unused Textures' function, or the 'Used By' function in the Material Editor. If the object does not support or require multiple textures, this function need not be implemented (and can be NULL).

Moray will call this function until it no longer returns MRY_SUCCESS. For the first call, nIndex is zero and is incremented by one for each subsequent call. The texture name that the plugin writes to pszTextureName is then marked as being in use and will not be deleted (or will be listed as in use).

Note that this function is not used for objects that do not support the MRY_ATTR_CAN_BE_MULTI_TEXTURED flag. For objects that can only use one texture, the normal method using GetAttributes will be used.

See Also

GetAttributes, MRY_OBJ_ATTRIBUTES


Top
 

PrintObject

The function PrintObject exports an object to either a POV-Ray or Polyray script.

    long WINAPI fnPrintObjectXXXX(long hObject, long lFileID, const char *pszName, pfnOutput fnOut);

Parameters

hObject

Contains the handle of the object to export.

lFileID

Contains the ID of the file being written. See Remarks.

pszName

Contains the name of this object.

fnOut

Contains a pointer to the function that should be called to export a line of text to the script.

Return Values

MRY_SUCCESS

should be returned if the function was successful.

MRY_EXPORT_XFORM_N_TXTR

if Moray should export transformation and texture settings.

Remarks

The function PrintObjectPOV is called to write the object to a POV-Ray script file, the function PrintObjectPolyray is called to write the object to a Polyray script file. The lFileID is an ID associated with the file being written and must be passed back to Moray via any calls to fnOut.
The function fnOut must be used to write a line of text to the file. The prototype is:

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

The name of the object is passed in via the pszName parameter.

If the plugin implements a normal object, it should keep track of certain states that are set by Moray just prior to exporting by calls to ChangeState. These states allow the object to determine whether it is textured, has a parent, has already been exported, etc. and to base export decisions like should the object be declared or instantiated on.

If this function returns MRY_EXPORT_XFORM_N_TXTR, Moray will export the transformations and textures of this object and will then write a closing brace. The plugin must leave the closing brace off in this case!

See Also

ChangeState, PostPrintObject


Top
 

PostPrintObject

The function PostPrintObject is called after an object has been exported to the script.

    void WINAPI fnPostPrintObject(long hObject, long lFileID, pfnOutput fnOut);

Parameters

hObject

Contains the handle of the object that was exported.

lFileID

Contains the ID of the file being written. See Remarks.

fnOut

Contains a pointer to the function that should be called to export a line of text to the script.

Remarks

The plugin can use this function to export anything else needed after the actual object has been exported.

The function fnOut must be used to write a line of text to the file. The prototype is:

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

The lFileID is an ID associated with the file being written and must be passed back to Moray via any calls to fnOut.

See Also

PrintObject, ChangeState


Top
 

ChangeState

The function ChangeState changes a state associated with an object.

    void WINAPI fnChangeState(long hObject, long lAndMask, long lOrMask);

Parameters

hObject

Contains the handle of the object whose state to change.

lAndMask

Contains the bitfield to be AND'ed with the state of the object.

lOrMask

Contains the bitfield to be OR'ed with the state of the object.

Remarks

This function is called by Moray once before exporting the scene and 3 times just prior to calling PrintObject to set the following state flags:

See Also

PrintObject, PostPrintObject


Top
 

SetAttributes

The function SetAttributes sets attributes and other information of an object.

    long WINAPI fnSetAttributes(long hObjID, LPMRY_OBJ_ATTRIBUTES pAttribs, int nFlags);

Parameters

hObjID

Contains a handle to the object whose attributes are to be set.

pAttribs

Contains a pointer to a MRY_OBJ_ATTRIBUTES attributes struct that Moray will read the settings from.

nFlags

Contains flags that determine what attributes to update. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the hObjID is NULL or if the object specific pointer is NULL but object specific handling was requested or if MRY_SCN_USE_LAYER_INFO was specified and pObjectLayer is NULL.

MRY_ERR_NOT_VALID_OBJECT

if the hObjID is not a valid object handle.

MRY_ERR_BLOCK_TOO_SMALL

if the size of the attributes struct is too small.

MRY_ERR_VERSION_NOT_SUPPORTED

if the version of the attribute struct differs in the major version number.

MRY_ERR_INVALID_ATTRIB_BLOCK

if the nObjectType member of the attribute struct does not match the type of hObjID.

MRY_ERR_LAYER_ID_ILLEGAL

if one of the IDs specified in the pObjectLayers struct does not reference a valid layer.

Remarks

This function can be used to configure attributes of the passed object.

The nFlags parameter can be a combination of the following values:


If you want to have Moray handle the redraws for you, set the MRY_SCN_HANDLE_REDRAWS flag. In this case the object is erased, the attributes changed, the object redrawn and the menu updated. If you plan to update many objects at once, you shouldn't use this flag, use the RedrawScene function in the Scene Interface to disable redraws until you're done and then call it again to enable them.

If nFlags contains MRY_SCN_USE_OBJECT_SPECIFIC, the wireframe for the object will be re-constructed (i.e. BuildWireFrame or BuildLazyWireFrame will be called).

NEW!The three flags used in previous versions of the SDK (MRY_SCN_USE_HOLLOW, MRY_SCN_USE_NOSHADOW and MRY_SCN_USE_EXPORT) are now obsolete. Since so many new flags were added with support for V3.5 it was no longer practical to use individual flags to set each one. Therefore in this SDK, the flag value MRY_SCN_USE_FLAGS determines that Moray will set ALL attributes from the nAttributes member. Therefore you should either make sure that all desired bits are set, or retrieve the value in a GetAttributes call first and then set or clear the corresponding attribute.

See Also

GetAttributes, SetTransforms, RedrawScene


Top
 

GetAttributes

The function GetAttributes retrieves the attributes of and other information about the object.

    long WINAPI fnGetAttributes(long hObjID, LPMRY_OBJ_ATTRIBUTES pAttribs);

Parameters

hObjID

Contains a handle to the object whose attributes are to be retrieved.

pAttribs

Contains a pointer to a MRY_OBJ_ATTRIBUTES attributes that Moray will write the settings to.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the hObjID is NULL or if the pAttribs pointer is NULL.

MRY_ERR_NOT_VALID_OBJECT

if the hObjID is not a valid object handle.

MRY_ERR_BLOCK_TOO_SMALL

if the size of the attributes struct is too small.

MRY_ERR_VERSION_NOT_SUPPORTED

if the version of the attribute struct differs in the major version number.

Remarks

This function fills out the attribute struct with information about the object.

If hObjID identifies an object and the object-specific pointer (see MRY_OBJ_ATTRIBUTES) is non-NULL, the object-specific information is also written out.

If hObjID identifies an object and the layer info pointer pObjectLayers (see MRY_OBJ_LAYERS) is non-NULL, the layer information is also written to this struct.
Note that transformations can also be retrieved by the GetTransforms function of the Scene Interface.

See Also

SetAttributes, GetTransforms, MRY_OBJ_ATTRIBUTES


Top
 

GetTransforms

The function GetTransforms retrieves the transformation parameters of an object.

    long WINAPI fnGetTransforms(long hObj, LPMRY_OBJ_TRANSFORMS pXForms);

Parameters

hObj

Contains the plugins handle to the object whose transformations are to be retrieved.

pXForms

Contains a pointer to a MRY_OBJ_TRANSFORMS transformation struct that Moray will fill with the transformations.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the hObjID is NULL.

MRY_ERR_NOT_VALID_OBJECT

if the hObjID is not a valid object handle.

Remarks

This can be used to get the transformation settings of a plugin object. The hObjID is the plugins handle to the object.

See Also

SetTransforms, GetAttributes, SetAttributes


Top
 

SetTransforms

The function SetTransforms sets the transformations of the object.

    long WINAPI fnSetTransforms(long hObj, LPMRY_OBJ_TRANSFORMS pXForms, int nFlags);

Parameters

hObj

Contains a plugins handle to the object whose transformations are to be set.

pXForms

Contains a pointer to a MRY_OBJ_TRANSFORMS transformation struct that Moray will read the settings from.

nFlags

Contains flags that determine what transformations to update. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the passed object is NULL.

MRY_ERR_NOT_VALID_OBJECT

if the passed object is not a valid object handle.

Remarks

This function sets the transformations values for the passed object.

The nFlags parameter can be a combination of the following values:


If you want to have Moray handle the redraws for you, set the MRY_SCN_HANDLE_REDRAWS flag. In this case the object is erased, the transformations changed, the object redrawn and the menu updated.
If you plan to update many objects at once, you shouldn't use this flag, use the RedrawScene function to disable redraws until you're done and then call it again to enable them.

See Also

GetTransforms, GetAttributes, SetAttributes


Top
 

Redraw

The function Redraw can be called by the plugin to make Moray redraw the wireframe of this object.

    long WINAPI fnRedraw(long hObject, int nFlags);

Parameters

hObject

Contains the handle of the object to redraw.

nFlags

Contains the flags that specify what to do.
This can be a combination of the following values:

  • MRY_SCN_DRW_REINIT - This will cause the objects wireframe to be reinitialized.
  • MRY_SCN_DRW_REDRAW - This will cause the object to be erased before it is reinitialized and drawn after it is reinitialized. This flag only makes sense if the MRY_SCN_DRW_REINIT flag is also set.
  • MRY_SCN_DRW_DOMENU - This will cause the objects edit menu on the Modify Tab to be updated (but only if the hObject is the selected object).

Return Values

MRY_ERR_OBJ_NOT_FOUND

will be returned if hObject is invalid.

MRY_ERR_NULL_POINTER

if you pass a NULL hObj.

MRY_ERR_NOT_VALID_OBJECT

if hObj is not a valid object.

MRY_SUCCESS

if the operation was successful.

Remarks

If nFlags is zero, this function does nothing.

This function can be useful if you want the wireframe of the object to change and want to update the display.

See Also

RedrawObject


Top
 

GetDlgResource

The function GetDlgResource returns a dialog template of the object type this interface handles for use with non-MFC plugins.

    HGLOBAL WINAPI fnGetDlgResource();

Return Values

A locked HDLGTEMPLATE to be used as the object dialog in the Mofify Tab.

Remarks

This function must be provided by the plugin interface if the object requires a dialog to be added to the Modify Tab of Moray when this object is selected and the plugin does not use the MFC (see GetCDialog for MFC-based dialogs).

Moray uses the template to instantiate a dialog and will then call FreeDlgResource immediately after this to release the memory.

If the plugin does not require a dialog, this function should either be set to NULL or should return NULL.

See Also

FreeDlgResource, GetCDialog


Top
 

FreeDlgResource

The function FreeDlgResource frees the dialog template that was allocated by GetDlgResource.

    void WINAPI fnFreeDlgResource(HGLOBAL hTemplate);

Parameters

hTemplate

Contains the locked dialog template to free.

Remarks

This function is called immediately after the call to GetDlgResource (if a valid dialog template was returned) to free the dialog template.

See Also

GetDlgResource, GetCDialog


Top
 

GetControlInfo

The function GetControlInfo determines whether Moray should handle the control with a certain ID.

    LRESULT WINAPI fnGetControlInfo(long hObject, int nID, LPMRY_CONTROL_INFO pCtrl);

Parameters

hObject

Contains the handle of the object to query for the dialog control.

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

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

See Also

ValueChanged


Top
 

ValueChanged

The function ValueChanged is called when the value associated with a control changes.

    LRESULT WINAPI fnValueChanged(long hObject, int nID, double dValue);

Parameters

hObject

Contains the handle of the object instance currently associated with the dialog.

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

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

Remarks

Note that this function gets called for every change to the value.


Top
 

Notify

The function Notify is called when events related to objects of this interface occur.

    long WINAPI fnNotify(long hObject, long lEvent);

Parameters

hObject

Contains the handle of the object instance currently associated with the dialog.

lEvent

Contains the ID of the event that has occurred.

Return Values

MRY_SUCCESS

should be returned (currently ignored by Moray).

Remarks

This function can be supplied by the interface if it requires to be notified when an object of its type is selected or deselected.
The lEvent parameter indicates what is being signalled and can be one of the following values:

See Also

Event


Top
 

WindowProc

The function WindowProc is the WindowProc procedure for the non-MFC dialog of this interface.

    LRESULT fnWindowProc(UINT message, WPARAM wParam, LPARAM lParam);

Parameters

message

Contains the standard message ID of a Windows message.

wParam

Contains the standard WPARAM of a Windows message.

lParam

Contains the standard LPARAM of a Windows message.

Return Values

Depends on the message being handled. See the Windows API documentation for the message being handled.

Remarks

For non-MFC-based dialogs, the plugin can supply a WindowProc that will receive all Windows messages directed at the dialog that Moray does not intercept. The dialog will not receive WM_LBUTTONDOWN, WM_MOUSEMOVE and WM_LBUTTONUP messages. These are handled by Moray to scroll the Modify Tab.

See Also

GetDlgResource


Top
 

GetCDialog

The function GetCDialog can be used to return an MFC-based dialog for use in the Modify Tab.

    long WINAPI fnGetCDialog(long hParent);

Parameters

hParent

Contains the window handle of the parent dialog.

Return Values

A pointer to the CPluginDialog-derived dialog to be used in the Modify Tab.

Remarks

If the plugin is not MFC-based, the plugin should not supply this function, but should rather supply the GetDlgResource function.

See Also

FreeCDialog, GetDlgResource


Top
 

FreeCDialog

The function FreeCDialog destroys the CPluginDialog derived dialog that was being used in the Modify Tab.

    long WINAPI fnFreeCDialog(long pCDialog);

Parameters

pCDialog

Contains a pointer to the CPluginDialog-derived dialog.

Return Values

MRY_SUCCESS

should be returned if the function was successful. Moray currently ignores this return value.

See Also

GetCDialog


Top
 

InitCDialog

The function InitCDialog initializes the controls of the dialog from an object instance.

    long WINAPI fnInitCDialog(long hObject);

Parameters

hObject

Contains the handle of the object instance which is has been selected.

Return Values

MRY_SUCCESS

should be returned if the function was successful. Moray currently ignores this return value.

Remarks

Moray will call this function whenever the user selects an object of the type associated with this Object Interface. The plugin should initialize any members that it is handling itself.

For member variables that are being handled by Moray (see GetControlInfo), Moray will call the GetControlInfo function immediately after returning from this function, so this function can ignore those controls.

See Also

GetControlInfo


Top