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

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

lAttributes

long lAttributes;

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

MRY_ATTR_CAN_BE_TEXTURED - the object can be textured. This makes Moray query the object about the texture it is using.
MRY_ATTR_CAN_BE_MULTI_TEXTURED - the object can have more than one texture. See also GetTextureName.
MRY_ATTR_CAN_BE_XFORMED - the object can be transformed (scaled, rotated, moved).
MRY_ATTR_CAN_BE_GROUPED - the object can be part of a group.
MRY_ATTR_CAN_BE_CSGD - the object can be part of a CSG.
MRY_ATTR_CAN_HAVE_PARENT - the object can have a parent. This one results from the above two.
MRY_ATTR_CAN_BE_REFERENCED - the object can be duplicated with referencing.
MRY_ATTR_CAN_REFERENCE_OBJECTS - the object can reference other objects.
MRY_ATTR_CAN_USE_PHOTONS - the object can use photons.
MRY_ATTR_HAS_OBJ_PARAMS - the object supports the normal object parameters (texture, bounding box, visibility, etc.).
MRY_ATTR_NO_DIRECT_CREATION - the object cannot be directly created. This prevents Moray from placing an item in the Create Tab and Create submenu.
MRY_ATTR_OBJ_LOADING - this is a flag that Moray sets (see below).
MRY_ATTR_HAS_ELEM_PARAMS - the object has normal parameters, but cannot be textured.

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

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

hDialog

HWND hDialog;

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

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

See Also

MRY_OBJECTFUNCS

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

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

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

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

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

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.

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

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.

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

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

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:

0 - Setting both locations pointed to by pVertNum and pEdgeNum to this means the object has no wireframe.
n - Setting both locations pointed to by pVertNum and pEdgeNum to a non-zero number, means the object has that many vertices and edges. Note that in this case, the object will have no solid representation and will be rendered as wireframe in the OpenGL views.
MRY_OBJ_LAZY_WIREFRAME - Setting both locations pointed to by pVertNum and pEdgeNum to this means the object does not know the number of vertices and edges ahead of time. 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.
MRY_OBJ_MESH_WIREFRAME - Setting both locations pointed to by pVertNum and pEdgeNum to this means you want to define everything yourself and know exactly how many vertices, edges, normals and UV coordinates you will need. Moray will call BuildMeshWireframe to allow the plugin the build the wireframe.
MRY_OBJ_TRIANGLE_WIREFRAME - Setting both locations pointed to by pVertNum and pEdgeNum to this means you simply want to feed Moray with triangles and Moray should figure out the rest. Moray will call BuildMeshWireframe to allow the plugin the build the wireframe.

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

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

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.

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

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

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

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

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:

MRY_OBJ_PRINTED - this flag is cleared before exporting a scene. Ideally the plugin object should set the flag in its PostPrintObject function to remember that it has printed itself.
MRY_OBJ_HASPARENT - this flag is set just prior to the call to PrintObject if the object has a parent.
MRY_OBJ_ISTEXTURED - this flag is set just prior to the call to PrintObject if the object has a texture assigned to it.
MRY_OBJ_ISBOUNDED - this flag is set just prior to the call to PrintObject if the object is bounded.

See Also

PrintObject, PostPrintObject

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:

MRY_SCN_USE_OBJECT_SPECIFIC - determines that the object specific parameters and attributes are correctly setup and should be used to set the objects properties.
MRY_SCN_USE_TEXTURE - determines that Moray should assign the texture to the object as specified in the struct.
MRY_SCN_USE_LEVEL - determines that the visibility levels of the object should be set from the struct.
MRY_SCN_USE_FLAGS - determines that the flags of the object will be set according for the bits set in the nAttributes member of the MRY_OBJ_ATTRIBUTES struct.
MRY_SCN_USE_TEXTURESPACE - determines that the texture space of the object should be set according to the struct.
MRY_SCN_USE_TEXTURE_XFORMS - determines that the transformations of the texture attached to the object should be set to the values in vTextureScale, vTextureRot and vTextureTrans.
MRY_SCN_USE_LAYER_INFO - determines that the layer information of the object should be set according to the pObjectLayers member.
MRY_SCN_USE_COLOR - determines that the wireframe color of the object should be set to the value of the nWireframeColor color.
MRY_SCN_HANDLE_REDRAWS - determines that Moray can handle the redraw for this action. See Remarks below.

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

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.

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.

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.

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:

MRY_SCN_USE_XFORMS - determines that Moray should update all transformation parameters (i.e. scaling, rotation and translation).
MRY_SCN_USE_XFORMS_EXTRA - determines that Moray should update all extra transformation parameters (i.e. scaling, rotation and translation of the local coordinates).
MRY_SCN_USE_SCALE - determines that Moray should only update the scaling values of the object from the transformation struct.
MRY_SCN_USE_ROT - determines that Moray should only update the rotation values of the object from the transformation struct.
MRY_SCN_USE_TRANS - determines that Moray should only update the translation values of the object from the transformation struct.
MRY_SCN_HANDLE_REDRAWS - determines that Moray can handle the redraw for this action.
MRY_SCN_DO_FULL_REDRAW - determines that Moray should do a full redraw of the views. Only used when the object being transformed is a camera. This flag must be used in conjunction with the MRY_SCN_HANDLE_REDRAWS flag.
MRY_SCN_USE_IK_SOLVER - determines that Moray should use the Inverse Kinematic solver to move the object to the position specified in the dTransX, dTransX and dTransZ members of the MRY_OBJ_TRANSFORMS transformation struct. Note that this flag can only be used together with the MRY_SCN_HANDLE_REDRAWS flag, all others are not taken into account.

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.

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

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

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

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

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.

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:

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

See Also

Event

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

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

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

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