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

Scene Interface

The Scene Interface allows the plugin to hook into many aspects of Moray.
This interface allows the plugin to:



Reference List of Functions

By Function Group Alphabetically
SetSelectedObject
GetSelectedObject
GetObjectByName
CreateObject
CopyObject
DeleteObject
AddToGroup
RemoveFromGroup
SetTransforms
GetTransforms
SetTransformLocks
GetTransformLocks
SetAttributes
GetAttributes
OpenEnumObject
EnumObjects
CloseEnumObject
RedrawScene
SelectTexture
RedrawObject
RedrawEvent
RequestScreenSpace
ActivateController
MakeLegalPOVName
ProgressFunction
YieldIdleTime
CheckCursorShape
Get3DWireframeData
BuildWireframe
BuildLazyWireframe
ExportScene
RenderScene
MergeScene
GetConfigVar
SetConfigVar
SendEvent
GetViewInfo
ReleaseBackdrop
AllocateBackdrop
RenderBackdrop
RenderBackdropPixel
InvalidateBackdrop
GetRenderOptions
RefreshTextureEditor
GetSettings
SetSettings
SetViewInfo
DrawOpenGLView
PushOntoUndoStack
UndoStackPopped
GetPluginDLLInfo
GetInterfaceInfo
QueryInterfaceByUID
PromptForFilename
QualifyFilename
DecomposeMatrix
RetrieveWireframeInfo
Event
LoadSaveEvent
PrintEvent
PrintEventObject
RequiredStreamSize
WriteToStream
ReadFromStream
ActivateController
AddToGroup
AllocateBackdrop
BuildLazyWireframe
BuildWireframe
CheckCursorShape
CloseEnumObject
CopyObject
CreateObject
DecomposeMatrix
DeleteObject
DrawOpenGLView
EnumObjects
Event
ExportScene
Get3DWireframeData
GetAttributes
GetConfigVar
GetInterfaceInfo
GetObjectByName
GetPluginDLLInfo
GetRenderOptions
GetSelectedObject
GetSettings
GetTransformLocks
GetTransforms
GetViewInfo
InvalidateBackdrop
LoadSaveEvent
MakeLegalPOVName
MergeScene
OpenEnumObject
PrintEvent
PrintEventObject
ProgressFunction
PromptForFilename
PushOntoUndoStack
QualifyFilename
QueryInterfaceByUID
ReadFromStream
RedrawEvent
RedrawObject
RedrawScene
RefreshTextureEditor
ReleaseBackdrop
RemoveFromGroup
RenderBackdrop
RenderBackdropPixel
RenderScene
RequestScreenSpace
RequiredStreamSize
RetrieveWireframeInfo
SelectTexture
SendEvent
SetAttributes
SetConfigVar
SetSelectedObject
SetSettings
SetTransformLocks
SetTransforms
SetViewInfo
UndoStackPopped
WriteToStream
YieldIdleTime



 

SetSelectedObject

The function SetSelectedObject selects an object.

    long WINAPI fnSetSelectedObject(long hObj);

Parameters

hObj

The handle of the object to be selected. If hObj is 0, no object will be selected and the selected object will be deselected.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NOT_VALID_OBJECT

if hObj is not a valid object handle or texture link.

Remarks

Moray will redraw the scene and update the menu to reflect the selection change.

See Also

GetSelectedObject, GetObjectByName


Top
 

GetSelectedObject

The function GetSelectedObject retrieves the handle of the currently selected object.

    long WINAPI fnGetSelectedObject(long *phObj);

Parameters

phObj

Pointer to the location where the handle of the currently selected object is to be stored.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULLPOINTER

if phObj is NULL.


Top
 

GetObjectByName

The function GetObjectByName retrieves the handle of an object.

    long WINAPI fnGetObjectByName(const char *pszName, long *phObj);

Parameters

pszName

Contains a null-terminated string that is the name of the object whose handle is to be retrieved.

phObj

Points to the location where the handle is to be stored.

Return Values

MRY_SUCCESS

if the function was successful, i.e. the object was found.

MRY_ERR_OBJ_NOT_FOUND

if the object with the passed name could not be found.

MRY_ERR_NULLPOINTER

if hObj is NULL.

MRY_ERR_NULLSTRING

if pszName is an empty string.

Remarks

The function does not search for textures. Use the Enumeration functions to retrieve textures.

See Also

GetSelectedObject, OpenEnumObject


Top
 

CreateObject

The function CreateObject Creates a new object or texture node.

    long WINAPI fnCreateObject(int nType, void *pInfo, long *phObj);

Parameters

nType

The type of object to create. See remarks.

pInfo

Points to data that is relevant for certain types of objects or textures. See Remarks for details.

phObj

Points to the location where the handle of the newly created object is to be stored.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if something unexpected occurred.

MRY_ERR_NULL_POINTER

if pInfo is NULL for objects where it is required (see Remarks).

MRY_ERR_NOT_VALID_OBJECT

if pInfo does not point to a valid object when creating a reference object.

MRY_ERR_PARENT_NOT_NULL

if a material node (texture) was being created with a non-null parent.

MRY_ERR_INVALID_TEXTURE_NAME

if a material node (texture) was being created and no name was given.

MRY_ERR_INVALID_TEXTURE_TYPE

if the nType variable is out of range.

MRY_ERR_INVALID_PARENT

if a textures parent is not a valid texture node.

MRY_ERR_OUT_OF_MEMORY

if no memory is available to create the object or if the object could not be created for some other reason.

MRY_ERR_APPEND_DENIED

if the texture node cannot be added to the specified parent.

Remarks

The nType variable can be one of the following values:



The action is stored in Morays Undo buffer if the created element is not a texture.

See Also

CopyObject, DeleteObject


Top
 

CopyObject

The function CopyObject makes a copy of the passed object.

    long WINAPI fnCopyObject(long hObj, long *phNewObj);

Parameters

hObj

Handle of the object to be copied.

phNewObj

Pointer to the location where the handle of the new object is to be stored.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if either hObj is zero or phNewObj is NULL.

MRY_ERR_NOT_VALID_OBJECT

if hObj is not a handle to a valid object.

Remarks

Neither textures nor texture linkd cannot be copied with this function.

The action is stored in Morays Undo buffer.

See Also

CreateObject, DeleteObject


Top
 

DeleteObject

The function DeleteObject deletes the passed object or texture.

    long WINAPI fnDeleteObject(long hObj);

Parameters

hObj

Contains the handle of the object or texture to be deleted.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if hObj is zero.

MRY_ERR_NOT_VALID_OBJECT

if hObj is not a handle to a valid object.

MRY_ERR_TEX_TEXTURE_IN_USE

if hObj is a handle to a texture that is still being used by an object.

MRY_ERR_INTERNAL_ERROR

if Moray is not stable.

Remarks

Objects and texture nodes can be deleted. Note that the tree display of the Texture Editor is updated after each call, so this could be a bit slow.

Note that texture links cannot be deleted. To delete a texture link, you need to use SetAttributes on the links parent object instead. Plugins will receive a notification that the link was deleted with that method.

The action is only stored in Morays Undo buffer if hObj is an object.

See Also

CreateObject


Top
 

AddToGroup

The function AddToGroup adds an object to a group or CSG object.

    long WINAPI fnAddToGroup(long hParentID, long hChildID, int bAddInPlace);

Parameters

hParentID

Contains a handle to the parent object, which must be either a group or a CSG object.

hChildID

Contains a handle to the object which is to be added to the parent object.

bAddInPlace

Determines whether the child object is to remain where it currently is after being added to the parent object.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if either the hParentID or hChildID is zero.

MRY_ERR_NOT_VALID_OBJECT

if hParentID is not the handle of a group or a CSG object, or if hChildID is not a valid object handle.

Remarks

Note that the function will popup messageboxes if you attempt to add objects to a CSG that is not valid. For example, you cannot add a camera to a CSG object.

See Also

RemoveFromGroup


Top
 

RemoveFromGroup

The function RemoveFromGroup removes a child object from a group or CSG object.

    long WINAPI fnRemoveFromGroup(long hParentID, long hChildID, int bUngroupInPlace);

Parameters

hParentID

Contains a handle to the parent object, which must be either a group or a CSG object.

hChildID

Contains a handle to the object which is to be removed from the parent object.

bUngroupInPlace

Determines whether the child object is to remain where it currently is after being removed from the parent object.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NOT_RELATED

if hChildID is not the handle of a child of the object whose handle is hParentID.

MRY_ERR_NULL_POINTER

if either hParentID or hChildID is zero.

MRY_ERR_NOT_VALID_OBJECT

if hParentID is not the handle of a group or a CSG object, or if hChildID is not a valid object handle.

Remarks

The action is stored in Morays Undo buffer

See Also

AddToGroup


Top
 

SetTransforms

The function SetTransforms sets the transformations of the object.

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

Parameters

hObjID

Contains a handle to the object or texture link 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 or texture link handle.

Remarks

This function sets the transformations values for the passed object.

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


Note that if the object is a spotcamera, this function will have no effect.
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.

If hObjID identifies a texture link, the MRY_SCN_USE_XFORMS_EXTRA is ignored. Only the transformation settings have an effect.

See Also

GetTransforms, SetTransformLocks, GetTransformLocks, GetAttributes, SetAttributes, RedrawScene


Top
 

GetTransforms

The function GetTransforms retrieves the transformation parameters of an object.

    long WINAPI fnGetTransforms(long hObjID, LPMRY_OBJ_TRANSFORMS pXForms);

Parameters

hObjID

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

If the object is a camera, the translation values contain the position of the camera, and the rotation values contain the coordinates of the lookat point of the camera. To get other camera parameters, use the GetAttributes function.

See Also

SetTransforms, SetTransformLocks, GetTransformLocks, GetAttributes, SetAttributes


Top
 

SetTransformLocks

The function SetTransformLocks sets the transformation locks of an object or texture link.

    long WINAPI fnSetTransformLocks(long hObjID, LPMRY_OBJ_TRANSFORM_LOCKS pXFormLocks, int nFlags);

Parameters

hObjID

Contains a handle to the object whose transformation locks are to be set.

pXFormLocks

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

nFlags

Reserved, not used, set to zero.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_CANNOT_SET_LOCKS

if the object is a camera.

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.

MRY_ERR_OUT_OF_MEMORY

if the lock cannot be created.

Remarks

This function sets the transformation lock values for the passed object or texture link.

See Also

GetTransformLocks, SetTransforms, GetTransforms, GetAttributes, SetAttributes


Top
 

GetTransformLocks

The function GetTransformLocks retrieves the transformation locks of an object.

    long WINAPI fnGetTransformLocks(long hObjID, LPMRY_OBJ_TRANSFORM_LOCKS pXFormLocks);

Parameters

hObjID

Contains a handle to the object whose transformation locks are to be retrieved.

pXFormLocks

Contains a pointer to a MRY_OBJ_TRANSFORM_LOCKS transformation locks struct that Moray will fill with the transformation lock data.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NO_LOCKS

if the object does not have lock information (always the case for cameras).

MRY_ERR_NULL_POINTER

if the hObjID or pXFormLocks is NULL.

MRY_ERR_NOT_VALID_OBJECT

if the hObjID is not a valid object handle.

Remarks

If the object is a camera, the function always returns MRY_ERR_NO_LOCKS since the camera cannot have transformation locks.

See Also

SetTransformLocks, SetTransforms, GetTransforms, GetAttributes, SetAttributes


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 transformations 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 the texture specific pointer is NULL but texture specific handling was requested.

MRY_ERR_NOT_VALID_OBJECT

if the hObjID is not a valid object nor texture handle, nor texture link.

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_TEXTURE_NOT_FOUND

if the texture specified could not be found.

MRY_ERR_INVALID_ATTRIB_BLOCK

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

MRY_ERR_OBJ_ALREADY_HAS_BBOX

if the MRY_SCN_CREATE_BOUNDINGBOX flag is passed even though the object already has a

bounding

box. The hBoundID of the pAttribs struct is set to the bounding box in the GetAttributes call. Use DeleteObject with this object handle to delete the bounding box.

MRY_ERR_OBJ_CANNOT_BE_BOUNDED

if the object cannot be bounded. This happens with planes and other infinite objects, or plugin objects that do not have the MRY_ATTR_HAS_OBJ_PARAMS flag set or with CSG/groups whose children are not boundable.

Remarks

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

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 to disable redraws until you're done and then call it again to enable them.

If the plugin is setting texture data (hObjID identifies a texture) only the following flags are evaluated (all others are ignored, including the MRY_SCN_USE_OBJECT_NAME flag):

Note that the name of a texture cannot be changed.

If hObjID identifies a plugin object and nFlags contains MRY_SCN_USE_OBJECT_SPECIFIC, the wireframe for that object will be re-constructed (i.e. GetWireFrameInfo and either BuildWireFrame or BuildLazyWireFrame will be called).

If hObjID identifies a texturelink, the call is ignored and MRY_ERR_NOT_VALID_OBJECT is returned.

Note that transformations are handled by SetTransforms.

See Also

MRY_OBJ_ATTRIBUTES, GetAttributes, SetTransforms, RedrawScene


Top
 

GetAttributes

The function GetAttributes retrieves the attributes of and other information about an object, texture or texture link.

    long WINAPI fnGetAttributes(long hObjID, LPMRY_OBJ_ATTRIBUTES pAttribs);

Parameters

hObjID

Contains a handle to the object, texture or texture link 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, texture handle or texture link.

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 the object-specific pointer (see MRY_OBJ_ATTRIBUTES) is non-NULL, the object-specific information is also written out.

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

If hObjID identifies a a texture link, only the hParentID and achObjectName members are valid.
Note that transformations can be retrieved by GetTransforms.

See Also

SetAttributes, GetTransforms, MRY_OBJ_ATTRIBUTES


Top
 

OpenEnumObject

The function OpenEnumObject creates an enumeration handle for enumerating an object or list of objects.

    long WINAPI fnOpenEnumObject(long hRoot, long *hEnum);

Parameters

hRoot

Contains the handle of the element to enumerate.
The following constants can be used to start an enumeration:

  • MRY_ENUM_OBJECTS - the objects of the scene will be enumerated.
  • MRY_ENUM_CAMERAS - the cameras of the scene will be enumerated.
  • MRY_ENUM_TEXTURES - the textures of the scene will be enumerated.

hEnum

Contains a pointer to the handle that is to receive the enumeration handle.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NOT_VALID_OBJECT

if hRoot is not a valid object handle or object list handle.

MRY_ERR_OUT_OF_MEMORY

if the enumeration cannot be allocated.

Remarks

This function can enumerate the global list of objects, cameras or textures. If this function succeeds, use the returned hEnum handle to retrieve object handles with the EnumObjects function until no more objects are returned.

See Also

EnumObjects, CloseEnumObject


Top
 

EnumObjects

The function EnumObjects retrieves the handle of an object from an enumeration.

    long WINAPI fnEnumObjects(long hEnum, int nIndex, long *hObj);

Parameters

hEnum

Contains the handle of the enumeration.

nIndex

Contains the index of the object handle to retrieve.

hObj

Contains the pointer where the retrieved object handle is to be stored.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the hEnum parameter is NULL.

MRY_ERR_NO_MORE_ITEMS

if no more objects can be enumerated by hEnum.

Remarks

The function retrieves the handle of the object that is in the zero-based nIndex position of the enumeration. To enumerate all objects, simply incremement nIndex in a loop until this function returns MRY_ERR_NO_MORE_ITEMS.

See Also

OpenEnumObject, CloseEnumObject


Top
 

CloseEnumObject

The function CloseEnumObject releases the enumeration handle.

    long WINAPI fnCloseEnumObject(long hEnum);

Parameters

hEnum

Contains the handle of the enumeration.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if hEnum is NULL.

Remarks

This function releases the handle returned by OpenEnumObject.

See Also

OpenEnumObject, EnumObjects


Top
 

RedrawScene

The function RedrawScene causes Moray to redraw all views and can enable or disable redrawing of the scene.

    long WINAPI fnRedrawScene(int nFlags);

Parameters

nFlags

This can be a combination of the following values:

  • MRY_SCN_DRW_DISABLE - disables screen refresh until you next call this function without this value.
  • MRY_SCN_DRW_RECALC - makes Moray recalculate the wireframes of an object (see Remarks).
  • MRY_SCN_DRW_REINIT - makes Moray update the Select Tab and the Browser.
  • MRY_SCN_DRW_REDRAW_IMMEDIATENEW! - makes Moray execute a Redraw before returning from the call.

Return Values

MRY_SUCCESS

always.

Remarks

If nFlags is zero, this function simply redraws all views.

Use the MRY_SCN_DRW_DISABLE value to disable the screen redrawing when calling functions that normally cause a redraw. For example, when creating multiple objects, first disable the redraw, create the objects and then re-enable the redraw, also specifying MRY_SCN_DRW_RECALC so that the wireframes are re-calculated.

Whenever you have called functions that alter the hierarchy of the scene, you must pass the MRY_SCN_DRW_REINIT value to this call. This includes assigning/changing textures to/of objects.
The behaviour has changed from the last plugin version in that passing MRY_SCN_DRW_REINIT does not re-initialize the local static wireframe shape of an object. The re-generation of the local static wireframe of all built-in objects is now handled automatically in the calls to SetAttributes. The MRY_SCN_DRW_RECALC flag makes Moray recalculate the objects wireframe, taking into account any transformation changes that may have occurred.

See Also

YieldIdleTime, RedrawObject


Top
 

SelectTexture

The function SelectTexture can be used to popup a dialog with all the textures in the scene, allowing the user to select one.

    long WINAPI fnSelectTexture(char* pszTextureName);

Parameters

pszTextureName

A pointer to where the name of the selected texture should be written.

Return Values

MRY_ERR_NULL_POINTER

if pszTextureName contains a NULL pointer.

MRY_SUCCESS

if the user selected a texture.

MRY_ERR_NO_MORE_ITEMS

if the user cancelled the dialog.

Remarks

NEW! Available in V2.10 and later only.

If your object can handle multiple texturing, this function is an easy way to select a texture without building the dialog yourself. The name of the texture will be written to the passed memory and MRY_SUCCESS returned if the user selects a texture.


Top
 

RedrawObject

The function RedrawObject causes Moray to redraw all views and can enable or disable redrawing of the scene.

    long WINAPI fnRedrawObject(long hObj, int nFlags);

Parameters

hObj

The handle of the object which should be redrawn.

nFlags

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

Return Values

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

YieldIdleTime, RedrawScene


Top
 

RedrawEvent

The function RedrawEvent can be provided by the plugin if it wants to be informed of redraw events occurring in specific views.

    long WINAPI fnRedrawEvent(int nEventID, LPMRY_SCN_VIEWINFO pViewInfo);

Parameters

nEventID

The event that is being signalled.

pViewInfo

a pointer to a MRY_SCN_VIEWINFO struct that is already filled out.

Return Values

MRY_SUCCESS

should be returned (currently ignored by Moray).

Remarks

This function should not be implemented by the interface if does not require access to the views during redrawing since it will unnecessarily slow down Moray.

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



Note that the MRY_SCN_VIEWINFO struct pointed to by pViewInfo is already valid and the plugin does not need to call GetViewInfo to obtain this information.

See Also

MRY_SCN_VIEWINFO


Top
 

RequestScreenSpace

The function RequestScreenSpace can be called to request an area on the screen that the plugin can use.

    long WINAPI fnRequestScreenSpace(LPMRY_SCN_VIEW_SCREEN_SPACE pScreenSpace);

Parameters

pScreenSpace

A pointer to a MRY_SCN_VIEW_SCREEN_SPACE struct containing the size and orientation of the requested space.

Return Values

MRY_ERR_NULL_POINTER

if pScreenSpace is NULL or if the phScreenSpace member of the struct pointed to by pScreenSpace is NULL

MRY_ERR_VERSION_NOT_SUPPORTED

if the version differs in the major number.

MRY_ERR_VALUE_OUT_OF_RANGE

if the value in the nFlags member is out of range.

MRY_ERR_UNKNOWN_HANDLE

if the phScreenSpace member is not a valid reserved handle.

MRY_SUCCESS

if the function reserved the screen space

Remarks

This function reserves a band of a certain size along one of the edges of the views. The views are resized accordingly to make space for the reserved band.


Reserving screen space:
A plugin can reserve screen space at any time after the MRY_NTC_MORAY_BOOTED event has been received (see the Event function).
To request screen space, set the following fields of the MRY_SCN_VIEW_SCREEN_SPACE struct and call this function:

When the function returns, the following fields of the struct are set:




Querying screen space:
A plugin can query the data of a screen space that it previously reserved, by setting the following fields of the MRY_SCN_VIEW_SCREEN_SPACE struct and calling this function:

When the function returns, the following fields of the struct are set:




Freeing screen space:
When a plugin no longer needs the screen space, it should call this function with the following fields of the MRY_SCN_VIEW_SCREEN_SPACE struct set:



In addition, the plugin must respond to the MRY_NTC_RESIZED event (see the Event function), must call this function to query the new size of the screen space and resize itself and any controls accordingly.

See Also

Event, MRY_SCN_VIEW_SCREEN_SPACE


Top
 

ActivateController

The function ActivateController can be called by the plugin to activate or deactivate a Controller Interface.

    long WINAPI fnActivateController(LPMRY_INTERFACEID pControllerUID);

Parameters

pControllerUID

contains a pointer to the MRY_INTERFACEID identifying the controller.

Return Values

MRY_SUCCESS

if the controller interface was activated.

MRY_ERR_INTERFACE_NOT_FOUND

if the interface identified by pControllerUID could not be found.

Remarks

To activate a Controller Interface call this function with the UID of the interface.
To deactivate the controller, pass NULL in pControllerUID.

See Also

Controller Interface


Top
 

MakeLegalPOVName

The function MakeLegalPOVName can be called by the plugin to convert a symbol to a legal POV-Ray symbol.

    long WINAPI fnMakeLegalPOVName(char * pszVarName);

Parameters

pszVarName

contains a pointer to the symbol that should be converted.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the passed variable is NULL.

Remarks

Note that the conversion happens in-place and that the string may grow. The conversion is the same conversion that Moray uses internally for all symbols before exporting.

NEW!V2.08 and later only.


Top
 

ProgressFunction

The function ProgressFunction can be called by the plugin to handle progress bars on Moray's status bar.

    long WINAPI fnProgressFunction(LPMRY_PROGRESS_DATA pProgressData);

Parameters

pProgressData

contains a pointer to a MRY_PROGRESS_DATA struct that determines what actions to take.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if the passed variable is NULL.

MRY_ERR_VERSION_NOT_SUPPORTED

if the passed struct is incompatible with the current Moray.

MRY_ERR_OUT_OF_MEMORY

if a progress bar could not be created.

MRY_ERR_INVALID_HANDLE

if the nHandle member of the MRY_PROGRESS_DATA struct is invalid (only in the non-create calls).

MRY_ERR_UNKNOWN_FUNCTION

if the nFunction member of the MRY_PROGRESS_DATA struct is invalid.

Remarks

Use this function to create, step and destroy a progress bar on Moray's status bar. The nFunction member (see MRY_PROGRESS_DATA) determines what action you would like to take.

NEW!V2.09 and later only.

See Also

MRY_PROGRESS_DATA


Top
 

YieldIdleTime

The function YieldIdleTime gives Moray time to execute any pending redraws.

    long WINAPI fnYieldIdleTime();

Return Values

MRY_SUCCESS

if the function executed a redraw.

MRY_ERR_REDRAW_DONE

if no more time for redraws is needed.

Remarks

Note that this function does not allow Moray to do any message processing. It only allows the redrawing of the views to finish.

See Also

RedrawScene


Top
 

CheckCursorShape

The function CheckCursorShape is a function that can be provided by the plugin to make Moray display a different mouse cursor over a specific view.

    long WINAPI fnCheckCursorShape(long hView, long *lShape);

Parameters

hView

contains the handle of the view that is currently being queried about mouse cursor shape.

lShape

contains a pointer to the custom mouse cursor or the idnetifier of the built-in cursor.

Return Values

This function can return either of the following values to make Moray respond accordingly:

MRY_CRS_CUSTOM

if Moray should display a cursor that is provided by the plugin.

MRY_CRS_BUILT_IN

if Moray should display one of the built-in cursors.

MRY_CRS_DONT_CARE

if the plugin does not want to override the cursor being displayed by Moray.

$NEW$MRY_CRS_CUSTOM_NO_MODE

if Moray should display a cursor that is provided by the plugin but continue as if the plugin hadn

Remarks

Moray will query the plugin if it wants to display a different cursor when the mouse if over a specific view.

The plugin can make Moray display a cursor that is built-in to Moray by returning MRY_CRS_BUILT_IN and setting lShape to one of the following values:


The plugin can also load its own cursor (using Win32 API function LoadCursor) and write the HCURSOR value into the long pointed to by lShape. In this case the plugin must return MRY_CRS_CUSTOM or MRY_CRS_CUSTOM_NO_MODE. The difference between these two is that in the first case Moray does not allow any view manipulation. In the second case Moray continues as if nothing was different, simply displaying the cursor supplied. Note that only the transformation modes allow cursor overrides.


Top
 

Get3DWireframeData

The function Get3DWireframeData can be provided by the plugin to create wireframes for things not implemented by an Object Interface.

    long WINAPI fnGet3DWireframeData)(long *pnNumVects, long *pnNumEdges, long* nReserved);

Parameters

pnNumVects

Contains a pointer to a variable where the plugin should store the number of 3D vertices it needs to create for the wireframe. See Remarks.

pnNumEdges

Contains a pointer to a variable where the plugin should store the number of 3D edges it needs to create for the wireframe. See Remarks.

nReserved

is reserved for future use.

Return Values

MRY_SUCCESS

always (currently ignored by Moray).

Remarks

NEW! This function is not called in Moray V3.5 and later. Please see DrawOpenGLView for details.

If the plugin does not know ahead of time how many vertices and edges it will require, it should write MRY_OBJ_LAZY_WIREFRAME to both locations pointed to by pnNumVects and pnNumEdges. In this case Moray will then call the BuildLazyWireframe functions to let the plugin create the wireframe.

If the plugin knows ahead of time how many vertices and edges it will require, it should set the locations pointed to by pnNumVects and pnNumEdges accordingly. In this case Moray will then call BuildWireframe function to let the plugin create the wireframe.

See Also

BuildWireframe, BuildLazyWireframe


Top
 

BuildWireframe

The function BuildWireframe can be provided by the plugin to create wireframes for things not implemented by an Object Interface.

    void WINAPI fnBuildWireframe(pfnAddSceneVertex fnAddVertex, pfnAddSceneEdge fnAddEdge);

Parameters

fnAddVertex

Contains a pointer to a function that should be called to create a vertex.

fnAddEdge

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

Remarks

NEW! This function is not called in Moray V3.5 and later. Please see DrawOpenGLView for details.

If the plugin knows ahead of time how many vertices and edges it will require, it should set the locations pointed to by pnNumVects and pnNumEdges in the call to Get3DWireframeData accordingly. In this case Moray will then call this function to let the plugin create the wireframe. The function is passed two pointers to functions that can be used to create vertices and edges.

The functions that is passed to the plugin to let it create vertices at a specific location is defined as follows:

    fnAddSceneVertex(double dX,double dY,double dZ);

The functions that is passed to the plugin to let it create edges is defined as follows:

    fnAddSceneEdge(long nVertex1, long nVertex2,long lColor);

The parameter nVertex1 contains the zero-based index of the first vertex of this edge.
nVertex2 contains the zero-based index of the second vertex of this edge.
lColor should be set the color that the edge should display in (in the format 0x00RRGGBB).

See Also

BuildLazyWireframe, Get3DWireframeData


Top
 

BuildLazyWireframe

The function BuildLazyWireframe can be provided by the plugin to create wireframes for things not implemented by an Object Interface.

    void WINAPI fnBuildLazyWireframe(pfnAddSceneVertexEdge fnAddVertexEdge);

Parameters

fnAddVertexEdge

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

Remarks

NEW! This function is not called in Moray V3.5 and later. Please see DrawOpenGLView for details.

If the plugin does not know ahead of time how many vertices and edges it will require, it should write MRY_OBJ_LAZY_WIREFRAME to both locations pointed to by pnNumVects and pnNumEdges in the call to Get3DWireframeData.
In this case Moray will then call this functions to let the plugin create the wireframe. The function is passed a pointer to a function that can be used to create an edge. Moray will collect the edges and will then merge the vertices and create its own vertex and edge list. This also means that using this form of wireframe generation is slower than if the plugin knows ahead of time how many vertices and edges it will require. Since this function can be called regularly, try to avoid using the lazy method. The function that is passed to the plugin to let it create an edge is defined as follows:

    fnAddSceneVertexEdge(LPMRY_VERTEXEDGE pEdge,long lColor);

See MRY_VERTEXEDGE for details of the structure. lColor should be set the color that the edge should display in (in the format 0x00RRGGBB).

See Also

BuildWireframe, Get3DWireframeData


Top
 

ExportScene

The function ExportScene exports the scene to file.

    long WINAPI fnExportScene(const char* pszFilename);

Parameters

pszFilename

Contains the name of the file to export the scene to or NULL (see Remarks).

Return Values

MRY_SUCCESS

if the scene was successfully exported.

MRY_ERR_COULD_NOT_EXPORT

if the scene could not be exported.

Remarks

The file is written in POV-Ray format.

If pszFilename is NULL, Moray will export to the loaded scene name it would use if the user invoked the export with Ctrl-F9 or the render with F9.

If pszFilename specifies a path, Moray will export to that path. The path must exist, otherwise MRY_ERR_COULD_NOT_EXPORT will be returned.

If the path is relative (e.g. SCENEDIR\SCENE), the scene will be exported into a subdirectory relative to the export path that the user has configured.

To use absolute paths, you must specify either the drive (C:\SCENEDIR\) or start off root (\SCENEDIR\).

If you do not specify a filename, the name of the loaded scene will be used.

See Also

RenderScene


Top
 

RenderScene

The function RenderScene exports the scene to file and calls the raytracer.

    long WINAPI fnRenderScene(const char* pszFilename);

Parameters

pszFilename

Contains the name of the file to export the scene to or NULL (see Remarks).

Return Values

MRY_SUCCESS

if the function was successful and the renderer started.

MRY_ERR_CANT_START_RENDERER

if the raytracer could not be started.

MRY_ERR_RENDERER_BUSY

if the raytracer is busy and was not stopped by the user.

MRY_ERR_COULD_NOT_EXPORT

if the file could not be exported. See Remarks.

Remarks

The file is written in the format of the active raytracer. After the successful export, the raytracer is started.

If the function returns MRY_ERR_COULD_NOT_EXPORT, it could be due to the export path being invalid, or the user not allowing us to delete the existing file if the options ask for verification when overwriting the scene.

See Also

ExportScene


Top
 

MergeScene

The function MergeScene merges an existing scene with the current one.

    long WINAPI fnMergeScene(int nType, const char* pszFilename);

Parameters

nType

Contains the type of file that you wish to merge. See Remarks.

pszFilename

Contains the name of the file to merge to the scene.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if pszFilename is NULL.

MRY_ERR_FILE_NOT_FOUND

if the file could not be located.

MRY_ERR_FILE_NOT_MERGED

if a texture library could not be merged.

Remarks

The file type indicates to Moray where to search for the file.
Valid values for nType are:


Top
 

GetConfigVar

The function GetConfigVar retrieves various configuration settings of Moray.

    long WINAPI fnGetConfigVar(int nWhichVar, long *plVar);

Parameters

nWhichVar

Contains the variable to be retrieved. See Remarks.

plVar

Contains a pointer to the address that is to receive the value of the variable.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_UNKNOWN_CONFIGVAR

if nWhichVar is an unrecognized variable.

Remarks

This function allows the plugin to query some of Morays internal settings.
Valid values for nWhichVar are:


Notes:

The variables marked (ReadOnly) can only be read, not set.

If the number of lines that need to be redrawn is above the maximum, only that many lines are drawn and then the screen is refreshed.
If a windows message is pending, at least the minimum amount of lines are drawn, then the redraw is interrupted.

The function YieldIdleTime will draw at least the minimum number of lines before checking the message queue and will then return if a message is pending. If no message is pending, it will continue drawing until the maximum is reached and will then return. If not all lines have been drawn at that time, the YieldIdleTime function will return a status indicating this.

The lower 16-bits of the value returned when the plugin queries the MRY_SCN_VAR_XFORM_MODE is a combination of the following values:



If Moray is in transformation mode (the lower 16-bits are MRY_XFORM_MODE_MOVE), then the upper 16-bits indicate which transformation mode Moray is in). The possible values are:



Most of these won't ever occur in Morays main screen. Normally Moray will return one of these in the upper 16-bits :



In response to the MRY_SCN_VAR_REGISTRY_BASE query, the parameter plVar is set to point to a 512 character buffer containing the registry branch under which the plugin can store its registry settings. The name ends in "Plugins\\" and the plugin must append its name and use that as the branch to store its stuff under.
The correct way to call this function is with an address of a char pointer:

If the function returns MRY_SUCCESS, pBase will then point to a 512 character buffer. Note that you should copy the branch if you plan to keep it around. Subsequent calls to GetConfigVar() will modify the buffer. You must not attempt to free the pointer.

See Also

GetViewInfo, SetConfigVar, YieldIdleTime


Top
 

SetConfigVar

The function SetConfigVar sets internal configuration variables.

    long WINAPI fnSetConfigVar(int nWhichVar, long lVar);

Parameters

nWhichVar

Contains the variable to be set. See Remarks.

lVar

Contains the new value of the variable.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_UNKNOWN_CONFIGVAR

if nWhichVar is an unrecognized variable.

Remarks

This function allows the plugin to set some of Morays internal settings.
Valid values for nWhichVar are:


Note that for the wireframe division variables, the wireframe of the entire scene is recalculated.

See Also

GetConfigVar


Top
 

SendEvent

The function SendEvent sends a message to Moray.

    long WINAPI fnSendEvent(int nEvent, long lParam);

Parameters

nEvent

Contains the event to send to Moray.

lParam

Contains any extra information that may be needed for certain events.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_UNKNOWN_EVENT

if the nEvent is not a valid event.

Remarks

This function can be used to inform Moray of events that the plugin may cause.
Valid values for nEvent are:


Top
 

GetViewInfo

The function GetViewInfo retrieves information about one of the four views of the Moray main screen.

    long WINAPI fnGetViewInfo(int nIndex, LPMRY_SCN_VIEWINFO vi);

Parameters

nIndex

Contains the zero-based index of the view to query. See Remarks.

lpViewInfo

Contains a pointer to a MRY_SCN_VIEWINFO struct that is to receive the information.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than zero or greater than three.

MRY_ERR_NULL_POINTER

if lpViewInfo is NULL.

MRY_ERR_VERSION_NOT_SUPPORTED

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

MRY_ERR_INTERNAL_ERROR

ir Moray is in a unstable state.

Remarks

The 4 views that can be queried are the main views. The Extended Editor views (such as those for the bezier and sweep editors) cannot be queried. The views are numbered between 0 and 3 and per default are laid out as follows:

See Also

SetViewInfo, MRY_SCN_VIEWINFO


Top
 

ReleaseBackdrop

The function ReleaseBackdrop deletes the backdrop of a view.

    long WINAPI fnReleaseBackdrop(long nIndex);

Parameters

nIndex

Contains the zero-based index of the view whose backdrop is to be deleted.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than 0 or greater than 3.

Remarks

If you plan to use AllocateBackdrop, you do not need to call this function first, since AllocateBackdrop will make sure that any older backdrop is properly deleted.

See Also

GetViewInfo, AllocateBackdrop, RenderBackdrop, RenderBackdropPixel, InvalidateBackdrop


Top
 

AllocateBackdrop

The function AllocateBackdrop allocates a backdrop for the view.

    long WINAPI fnAllocateBackdrop(long nIndex, int nWidth, int nHeight);

Parameters

nIndex

Contains the zero-based index of the view whose backdrop is to be allocated.

nWidth

Contains the width in pixels of the new backdrop.

nHeight

Contains the height in pixels of the new backdrop.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than 0 or greater than 3.

MRY_ERR_OUT_OF_MEMORY

if the backdrop could not be allocated.

Remarks

This deletes any previous backdrop of the view and attempts to allocate a bitmap of the size specified by nWidth and nHeight. If this function is successful, you can use the RenderBackdrop function to paint into the backdrop.

See Also

GetViewInfo, RenderBackdrop, RenderBackdropPixel, ReleaseBackdrop, InvalidateBackdrop


Top
 

RenderBackdrop

The function RenderBackdrop renders into the backdrop of a view.

    long WINAPI fnRenderBackdrop(long nIndex, int nLine, int lNumPixels, unsigned char* pPixelData);

Parameters

nIndex

Contains the zero-based index of the view whose backdrop is to be rendered into.

nLine

Contains the zero-based line number that you want to render.

lNumPixels

Contains the number of pixels to be painted into the backdrop.

pPixelData

Contains a pointer to the pixel data. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than 0 or greater than 3.

Remarks

The pixel data pointed to by pPixelData is interpreted as 24-bit RGB data, i.e. three bytes per pixel.

The line is always rendered starting from the left edge.

If lNumPixels is larger than the nWidth parameter passed to AllocateBackdrop, nothing is painted.
Likewise if nLine is larger than the nHeight parameter passed to AllocateBackdrop, nothing is painted.

See Also

GetViewInfo, ReleaseBackdrop, AllocateBackdrop, RenderBackdropPixel, InvalidateBackdrop


Top
 

RenderBackdropPixel

The function RenderBackdropPixel renders a pixel into the backdrop of a view.

    long WINAPI fnRenderBackdropPixel(long nIndex, int nX, int nY, unsigned char *pPixelData);

Parameters

nIndex

Contains the zero-based index of the view whose backdrop is to be rendered into.

nX, nY

Contains the position of the pixel you want to render.

pPixelData

Contains a pointer to the pixel data. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than 0 or greater than 3.

Remarks

The pixel data pointed to by pPixelData is interpreted as a 24-bit RGB pixel, i.e. three bytes.

nX and nY must be greater than or equal to zero and less than width and height, respectively.

Due to runtime considerations this function does not update the screen. Use the InvalidateBackdrop function transfer the backdrop pixels to the screen.

See Also

GetViewInfo, ReleaseBackdrop, AllocateBackdrop, RenderBackdrop, InvalidateBackdrop


Top
 

InvalidateBackdrop

The function InvalidateBackdrop paints the backdrop of a view to the screen.

    long WINAPI fnInvalidateBackdrop(long nIndex, int nX1, int nY1, int nX2, int nY2);

Parameters

nIndex

Contains the zero-based index of the view whose backdrop is to be rendered into.

nX1, nY1

Contains the top-left corner of the rectangle of the backdrop you want to refresh.

nX2, nY2

Contains the bottom-right corner of the rectangle of the backdrop you want to refresh.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than 0 or greater than 3.

Remarks

Note that this function is only neccessary if you call RenderBackdropPixel, since that function does not update the screen display. Ideally you should render a number of pixels and then update the area with a call to this function.

nX1, nY1, nX2 and nY2 must be greater than or equal to zero and less than width and height, respectively.

Note that in the current release, the X-coordinates are ignored and the entire scanlines spanned by nY1 and nY2 are repainted. NEW!From Moray V3.5, the coordinates are ignored, since OpenGL always repaints the entire screen.

See Also

GetViewInfo, ReleaseBackdrop, AllocateBackdrop, RenderBackdrop, InvalidateBackdrop


Top
 

GetRenderOptions

The function GetRenderOptions retrieves the rendering options of Moray.

    long WINAPI fnGetRenderOptions(int nRenderer, LPMRY_RENDER_OPTIONS pOptions);

Parameters

nRenderer

Contains the renderer whose options are to be retrieved. See Comments.

pOptions

Contains a pointer to a MRY_RENDER_OPTIONS structure that is to receive the options.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_NULL_POINTER

if pOptions is NULL.

MRY_ERR_VERSION_NOT_SUPPORTED

if the nVersion member of pOptions is higher than Moray supports.

MRY_ERR_INDEX_OUT_OF_RANGE

if nRenderer is an incorrect value.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_UNKNOWN_EVENT

if the nEvent is not a valid event.

Remarks

This function can be used to find out what rendering options Moray is currently using the renderer.

Valid values for nRenderer are:

Note that using MRY_RENDER_ACTIVE will return the type of the active renderer in the nActiveRenderer member of the MRY_RENDER_OPTIONS structure pointed to by pOptions.


Top
 

RefreshTextureEditor

The function RefreshTextureEditor can be called by the plugin to rebuild the Texture Editor display. [V1.03]

    long WINAPI fnRefreshTextureEditor();

Return Values

MRY_SUCCESS

if the function succeeded.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

Remarks

This function can must be used to transfer any textures that a plugin has created via the CreateObject function to the Texture Editor and to make the Texture Editor update its display.

See Also

CreateObject


Top
 

GetSettings

The function GetSettings retrieves the information in the Scene Settings Dialog of Moray. This includes the background color,

    long WINAPI fnGetSettings(LPMRY_SCN_SETTINGS pSettings);

Parameters

pSettings

Contains a pointer to a MRY_SCN_SETTINGS structure that is to receive the data.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_VERSION_NOT_SUPPORTED

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

See Also

MRY_SCN_SETTINGS, SetSettings


Top
 

SetSettings

The function SetSettings sets the information in the Scene Settings Dialog of Moray. This includes the background color,

    long WINAPI fnSetSettings(LPMRY_SCN_SETTINGS pSettings);

Parameters

pSettings

Contains a pointer to a MRY_SCN_SETTINGS structure that should be used to set the data.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

MRY_ERR_VERSION_NOT_SUPPORTED

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

See Also

MRY_SCN_SETTINGS, GetSettings


Top
 

SetViewInfo

The function SetViewInfo sets information of one of the four views of the Moray main screen.

    long WINAPI fnSetViewInfo(int nIndex, LPMRY_SCN_VIEWINFO pViewInfo);

Parameters

nIndex

Contains the index of the view. See Remarks.

pViewInfo

Contains a pointer to a MRY_SCN_VIEWINFO struct that contains the new information.

Return Values

MRY_SUCCESS

if the function was successful.

MRY_ERR_INDEX_OUT_OF_RANGE

if nIndex is less than zero or greater than three.

MRY_ERR_NULL_POINTER

if vi is NULL.

MRY_ERR_VERSION_NOT_SUPPORTED

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

MRY_ERR_INTERNAL_ERROR

if Moray is in a unstable state.

Remarks

The views are numbered between 0 and 3 and per default are laid out as follows:

See Also

GetViewInfo, MRY_SCN_VIEWINFO


Top
 

DrawOpenGLView

The function DrawOpenGLView is called by Moray when the scene has been rendered.

    long WINAPI fnDrawOpenGLView(LPMRY_SCN_VIEWINFO pViewInfo);

Parameters

pViewInfo

Contains a pointer to a MRY_SCN_VIEWINFO struct that contains the information of the view being rendered.

Return Values

The

function should return MRY_SUCCESS. The return code is currently ignored.

Remarks

NEW! This function exists in Moray V3.5 (Scene V2.07) and later only.

This function (if implemented) is called by Moray every time the scene in a specific view has been rendered. It allows the plugin to issue OpenGL drawing commands to add graphics to the view. OpenGL commands should simply draw in 3D and let OpenGL project it onto the view. The plugin should normally not need to worry about whether the view is a 2D view or a 3D view.

OpenGL is configured as follows:

You need to save and restore the OpenGL matrix if you change it.
Note that there may not neccessarily be a unit matrix on the stack. If the user is in one of the editors, he may be working in Local mode. In this case the OpenGL matrix stack is setup so that any elements rendered are transformed into the local coordinate system of the object being edited.

See Also

MRY_SCN_VIEWINFO


Top
 

PushOntoUndoStack

The function PushOntoUndoStack creates an undo action on the Undo stack.

    long WINAPI fnPushOntoUndoStack(LPMRY_SCN_UNDO_INFO pUndoInfo);

Parameters

pUndoInfo

contains a pointer to the MRY_SCN_UNDO_INFO structure that specifies the undo action.

Return Values

MRY_SUCCESS

if the call was successful and the action was placed on the stack.

MRY_ERR_NULL_POINTER

if pUndoInfo is NULL.

MRY_ERR_INTERNAL_ERROR

if Moray is in an unstable state.

MRY_ERR_VERSION_NOT_SUPPORTED

if the nVersion member of the MRY_SCN_UNDO_INFO structure is not compatible with the current Moray version.

Remarks

The members of the MRY_SCN_UNDO_INFO structure contain all the information that Moray requires to manage the undo action. It also contains a pointer to the plugins own undo data that teh plugins undo action may require. This information must be allocated on the heap, as it remains in the Undo buffer until Moray signals the plugin that it can release the info in the UndoStackPopped call.

See Also

UndoStackPopped, MRY_SCN_UNDO_INFO


Top
 

UndoStackPopped

The function UndoStackPopped indicates that the undo action that the plugin previously created should be executed or released.

    long WINAPI fnUndoStackPopped(int nAction, LPMRY_SCN_UNDO_INFO pUndoInfo);

Parameters

nAction

This flag indicates whether the undo action should be executed or released.

pUndoInfo

contains a pointer to the MRY_SCN_UNDO_INFO structure that specifies the undo action and was passed to the PushOntoUndoStack function.

Return Values

This function can return any combination of the following flags to make Moray do the required action(s):

MRY_SCN_UNDO_RECALC

- if the wireframe display has changed (e.g. an object has been deleted). Moray will recalculate the wireframe display. Mostly this flag will be combined with the MRY_SCN_UNDO_REDRAW flag.

MRY_SCN_UNDO_REDRAW

- to make Moray redraw all the views.

MRY_SCN_UNDO_DOMENU

- to make Moray update the menu of the currently selected object.

MRY_SCN_UNDO_UPDATETREE

- to make Moray update the Object tree (i.e. Browser and Select Tab).

Remarks

This function must be implemented by the plugin if it wants to support Undo. The flag nAction It can be one of the following values:

When the user undoes an action, this function is called twice, once with the MRY_SCN_UNDO_EXECUTE flag and then with the MRY_SCN_UNDO_RELEASE flag. When the user clears the Undo Buffer or the undo action is removed from the bottom of the stack, this function is called with the MRY_SCN_UNDO_RELEASE flag.

See Also

PushOntoUndoStack, MRY_SCN_UNDO_INFO


Top
 

GetPluginDLLInfo

The function GetPluginDLLInfo can be used to get information about the DLLs currently loaded by Moray.

    long WINAPI fnGetPluginDLLInfo(int nDLLIndex, LPMRY_DLLINFO *pDLLInfo);

Parameters

nDLLIndex

contains the zero-based index of the DLL to be queried.

pDLLInfo

contains a pointer to a pointer to a MRY_DLLINFO structure where you want the information stored.

Return Values

MRY_SUCCESS

if the information could be retrieved and stored in pDLLInfo.

MRY_ERR_NO_MORE_DLLS

if no more DLLs are loaded (nDLLIndex too high).

MRY_ERR_INDEX_OUT_OF_RANGE

if nDLLIndex below 0.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

Remarks

Use this function to find the general information associated with each plugin DLL that is currently loaded by Moray. See MRY_DLLINFO for details about the infcormation returned. To use this function simply call this function in a loop, starting nDLLIndex at 0 and incrementing each time through the loop until the function returns MRY_ERR_NO_MORE_DLLS.

See Also

GetInterfaceInfo, QueryInterfaceByUID


Top
 

GetInterfaceInfo

The function GetInterfaceInfo can be used to retrieve information about all the interfaces of all the plugins currently loaded by Moray.

    long WINAPI fnGetInterfaceInfo(int nDLLIndex, int nInterfaceIndex, LPMRY_INTERFACE *pInterface);

Parameters

nDLLIndex

contains the zero-based index of the DLL to be queried.

nInterfaceIndex

contains the zero-based index of the interface of the specified DLL to be queried.

pInterface

contains a pointer to a pointer to a MRY_INTERFACE structure where you want the information stored.

Return Values

MRY_SUCCESS

if the information could be retrieved and stored in pInterface.

MRY_ERR_NO_MORE_DLLS

if no more DLLs are loaded (nDLLIndex too high).

MRY_ERR_NO_MORE_INTERFACES

if no more interfaces are present in this DLL (nInterfaceIndex too high for this DLL).

MRY_ERR_INDEX_OUT_OF_RANGE

if nDLLIndex or nInterfaceIndex is below 0.

MRY_ERR_INTERNAL_ERROR

if Moray is unstable.

Remarks

Use this function to retrieve all the interfaces of all the plugins currently loaded by Moray.

See Also

GetPluginDLLInfo, QueryInterfaceByUID


Top
 

QueryInterfaceByUID

The function QueryInterfaceByUID can be used to get the a specific interface from another plugin currently loaded by Moray.

    long WINAPI fnQueryInterfaceByUID(LPMRY_INTERFACEID pUID, LPMRY_INTERFACE *pInterface);

Parameters

pUID

contains a pointer to a MRY_INTERFACEID containind the unique ID of the interface that you're querying.

pInterface

contains a pointer to a pointer to a MRY_INTERFACE structure where you want the information stored.

Return Values

MRY_SUCCESS

if the interface was found.

MRY_ERR_INTERFACE_NOT_FOUND

if the interface specified by pUID is not loaded.

Remarks

Use this function to query Moray for a specific interface. If you know the UID of a specific interface this function will retrieve that interface. You could use this function in conjunction with the External Interface to create interfaces between plugins.

See Also

GetPluginDLLInfo, GetInterfaceInfo


Top
 

NEW!PromptForFilename

The function PromptForFilename can be used to request a filename of a specific type from the user.

    long WINAPI fnPromptForFilename(int nType, char *pszName, int nAttribs);

Parameters

nType

The type of file requested. This can be one of the following types:

  • MRY_FILES_MORAY_SCENE - a MDL file from Moray's scene directory.
  • MRY_FILES_POVRAY_SCENE - a POV file from Moray's POV-Ray Export directory.
  • MRY_FILES_IMAGEMAP - an image file from Moray's image map directory.
  • MRY_FILES_BUMPMAP - an image file from Moray's bump map directory.
  • MRY_FILES_HEIGHTFIELD - an image file from Moray's heightfield directory.
  • MRY_FILES_USER_OBJECT - an UDO file from Moray's UDO directory.
  • MRY_FILES_RAWFILE - a RAW file from Moray's raw file directory.
  • MRY_FILES_BLOBFILE - a BLB file from Moray's blob file directory.
  • MRY_FILES_GLYPHFILE - a DAT file from Moray's glyph directory.
  • MRY_FILES_BACKDROP - an image file from Moray's backdrop directory.
  • MRY_FILES_TRUETYPE - a TTF font file from Moray's TTF Fonts directory.
  • MRY_FILES_INCFILE - a POV-Ray INC file from Moray's include file directory.
  • MRY_FILES_MORAY_OBJECTS - a MDL file from Moray's object directory.
  • MRY_FILES_TEXTURE_LIB - a MTX file from Moray's Material Library directory.
  • MRY_FILES_PLUGINS - a DLL file from Moray's Plugin directory.

pszName

This parameter contains the default name to prompt for and if the user selected a file, the name of the file he selected.

nAttribs

This parameter can be used to determine what kind of file dialog it is (Load or Save) and what behaviour the dialog should display. The flags are similar to the normal Explorer flags:

  • MRY_FILES_LOADDIALOG - Display a Load dialog.
  • MRY_FILES_SAVEDIALOG - Display a Save dialog
  • MRY_FILES_FILEMUSTEXIST - The selected file must exist (mostly used in conjunction with a Load dialog).
  • MRY_FILES_OVERWRITEPROMPT - If the file exists, ask whether to overwrite the file (mostly used in conjunction with a Save dialog).
  • MRY_FILES_PATHMUSTEXIST - The path to the file must already exist.
  • MRY_FILES_HIDEREADONLY - Do not display Read-Only files in the File Dialog.

Return Values

MRY_SUCCESS

is returned if a file was selected.

MRY_ERR_NO_FILE_SELECTED

is returned if no file was selected.

Remarks

This function pops up Moray's custom File Dialog. This is the preferred way to ask for a file of a specific type (e.g. Moray scene, Imagemap, etc.) if the plugin needs it. The File Dialog will have access to the Search paths that the user has configured on his machine.

See Also

QualifyFilename


Top
 

NEW!QualifyFilename

The function QualifyFilename can be used to find the full name of a file of a specific type.

    long WINAPI fnQualifyFilename(int nType, char *pszName);

Parameters

nType

The type of file to find. See PromptForFilename for details.

pszName

The name of the file to find. On return it contains the fully qualified name

Return Values

MRY_ERR_FILE_NOT_FOUND

if the file was not found.

MRY_SUCCESS

should be returned by the function.

Remarks

Note that you are responsible for making pszName large enough to hold a fully qualified pathname.

See Also

PromptForFilename


Top
 

NEW!DecomposeMatrix

The function DecomposeMatrix cane be used to decompose a transformation matrix to the individual transformation components.

    long WINAPI fnDecomposeMatrix(double adMatrix[16], double adComponents[12])

Parameters

adMatrix

The 4x4 matrix that needs to be decomposed (see Remarks for layout).

adComponents

The 12 components that result in the passed matrix.

Return Values

MRY_SUCCESS

if the matrix was successfully decomposed.

MRY_ERR_SINGULAR_MATRIX

if the matrix is singular and thus cannot be decomposed.

Remarks

This function is new for V205 of the scene interface, be sure to test for at least this version. It simply exposes a function in Moray that you may find useful. The algorithm is an adaption of the one by Spencer W. Thomas described in Graphics Gems II. Note that it cannot handle perspective matrices.

Matrix layout:

The adMatrix array contains the transformation that you want to decompose into its individual components.

If this is the matrix you want to decompose:

a11 a21 a31 a41
a12 a22 a32 a42
a13 a23 a33 a43
a14 a24 a34 a44

The adMatrix array is ordered like this: a11, a21, a31, a41, a12, a22, a32, a42, a13, a23, a33, a43, a14, a24, a34, a44

Note that a41, a42 and a43 are always 0 and a44 is always 1. a14, a24 and a34 contain the translation parameters.

Component layout: The returned adComponent array is ordered as follows:

Scale X
Scale Y
Scale Z
Shear XY
Shear XZ
Shear YZ
Rotation X
Rotation Y
Rotation Z
Translation X
Translation Y
Translation Z


Top
 

NEW!RetrieveWireframeInfo

The function RetrieveWireframeInfo can be used to retrieve the wireframe and polygon representation of an object.

    long WINAPI fnRetrieveWireframeInfo(long hObjID, LPMRY_WIREFRAME_BUILDING pWireBuilder);

Parameters

hObjID

The handle of the object whose wireframe is to be retrieved.

pWireBuilder

A pointer to a LPMRY_WIREFRAME_BUILDING struct.

Return Values

MRY_ERR_NULL_POINTER

- if hObjID is NULL.

MRY_ERR_VERSION_NOT_SUPPORTED

- if the version of this struct is not supported.

MRY_ERR_NOT_VALID_OBJECT

- if hObjID is not the handle of a valid object.

MRY_SUCCESS

should be returned by the function.

Remarks

This function makes Moray initialize a MRY_WIREFRAME_BUILDING struct with all the data required to query and modify an existing objects wireframe. See the documentation of MRY_WIREFRAME_BUILDING for details.

See Also

MRY_WIREFRAME_BUILDING


Top
 

Event

The function Event informs the plugin of certain events.

    long WINAPI fnEvent(long hObjID, int nFlags);

Parameters

hObjID

Contains the handle of the object that the event pertains to.

nFlags

Contains the event that is being relayed.

Return Values

MRY_SUCCESS

should be returned by the function.

MRY_NTC_REQ_RECALC

can be returned (see Remarks).

Remarks

This function can be provided by the plugin. Moray will call the function with the following values of nFlags:


NEW!The MRY_NTC_SCENE_LOADED is no longer sent to the Event function. It is now sent to LoadSaveEvent.

This function should be provided if the plugin needs to reference objects in a scene. For example, the lensflare plugin needs to have a reference to a light and a camera. If either of these are deleted by the user, the lensflare plugin must also release its reference.

The plugin can return MRY_NTC_REQ_RECALC in response to the MRY_NTC_OBJ_SELECTED if the plugin requires that the objects be recalculated.

See Also

PrintEvent, PrintEventObject, LoadSaveEvent


Top
 

NEW!LoadSaveEvent

The function LoadSaveEvent informs the plugin of certain events related to loading, saving and pasting.

    long WINAPI fnLoadSaveEvent(long hObj, int nFlags, long lParam1, long lParam2);

Parameters

hObj

Contains the handle of the object that the event pertains to.

nFlags

Contains the event that is being relayed.

lParam1

Contains parameters that vary depending on the event.

lParam2

Contains parameters that vary depending on the event.

Return Values

MRY_SUCCESS

should be returned by the function.

Remarks

This function can be provided by the plugin. Moray will call the function with the following values of nFlags:

This function should be provided if the plugin needs to keep track of objects in a scene and wants to be notified of these events.

See Also

PrintEvent, PrintEventObject, Event


Top
 

PrintEvent

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

    long WINAPI fnPrintEvent(long lFileID, int nEvent, pfnOutput fnOut);

Parameters

lFileID

Contains the handle to the file that is used to identify the file to Moray and is passed back to Moray in the call to the fnOut function.

nEvent

Contains the output event that is occurring.

fnOut

Contains a pointer to the function that the plugin must call if it wants to write something to the output stream. See Remarks.

Return Values

MRY_SUCCESS

if the function was successful.

Remarks

This function can be provided by the plugin. Moray will call the functions at various times while writing the scene file for the raytracer.

nEvent can be one of the following values:


Note that a plugin that implements the Object Interface should not use any of these events to determine when to export itself, since its Export function should be used to do that. If the object requires that something be written to the scene file once, no matter how many instances of that object are created, then this function would be the right place to do that.

The prototype for the fnOut function is:

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

The lFileID parameter passed to this function must be the one passed in via the lFileID argument.

See Also

Event, LoadSaveEvent, PrintEventObject


Top
 

PrintEventObject

The function PrintEventObject is called by Moray when certain output events are about to occur. [V1.03]

    long WINAPI fnPrintEventObject(long lFileID, long hObjID, int nEvent, pfnOutput fnOut);

Parameters

lFileID

Contains the handle to the file that is used to identify the file to Moray and is passed back to Moray in the call to the fnOut function.

nEvent

Contains the output event that is occurring.

hObjID

Contains the handle of the object this event relates to.

fnOut

Contains a pointer to the function that the plugin must call if it wants to write something to the output stream. See Remarks.

Return Values

The function should return MRY_SUCCESS.

The

function can return MRY_ERR_OBJ_DONT_EXPORT (see Remarks).

Remarks

This function can be provided by the plugin. Moray will call the functions when a top-level object is about to be written to the scene file for the raytracer.

nEvent can be one of the following values:


Note that for the MRY_NTC_BEGIN_XXXXX events, this function can return MRY_ERR_DONT_EXPORT in which case Moray will not export the definition of the item identified by hObjID (nor any of its children). Moray will still call this function with the corresponding MRY_NTC_END_XXXX event. Use this with care! It is meant as a means for plugins to work with Moray objects and replace their export.

This function is called for top-level objects only, but not for objects that are declared.

Note that this also means that for plugin objects implemented via the Object Interface the Print function will not be called.

The prototype for the fnOut function is:

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

The lFileID parameter passed to this function must be the one passed in via the lFileID argument.

See Also

Event, LoadSaveEvent, PrintEvent


Top
 

RequiredStreamSize

The function RequiredStreamSize is called by Moray to get the number of bytes to write to a MDL file.

    long WINAPI fnRequiredStreamSize(long hObjID);

Parameters

hObjID

Currently NULL. Reserved.

Return Values

The number of bytes that the interface wants to write out to the MDL file.

Remarks

This function is called by Moray to find out whether the plugin wants to write any object-independent data to the MDL file that is being saved. The function does not need to be set and is only called if the WriteToStream and ReadFromStream members are set.

See Also

WriteToStream, ReadFromStream


Top
 

WriteToStream

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

    long WINAPI fnWriteToStream(long hObjID, pfnStreamIO fnIO, long lStreamID);

Parameters

hObID

Reserved, currently is NULL.

fnIO

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

lStreamID

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

Return Values

The function should return MRY_SUCCESS. The return value is currently ignored.

Remarks

The function does not need to be set and is only called if the RequiredStreamSize and ReadFromStream members are set and RequiredStreamSize returns a size greater 0.
The function is called after the entire scene has been written by Moray.
To write data to the file use the fnIO function that is provided by Moray.
The prototype for this function is:

    void WINAPI fnIO(long lStreamID,void *pData,unsigned int nLength);

The lStreamID that is passed to this function must be the lStreamID that was passed to the WriteToStream function.

See Also

RequiredStreamSize, ReadFromStream


Top
 

ReadFromStream

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

    long WINAPI fnReadFromStream(long lDataLength, pfnStreamIO fnIO, long lStreamID);

Parameters

lDataLength

Contains the number of bytes this function is allowed to read.

fnIO

Contains a pointer to the function that must be used to read the data from the file.

lStreamID

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

Return Values

The function should return MRY_SUCCESS. The return value is currently ignored.

Remarks

The function does not need to be set and is only called if the RequiredStreamSize and WriteToStream members are set and RequiredStreamSize returns a size greater 0.
The function is called after the entire scene has been read by Moray. If you need to work with the objects in the scene immediately after loading a scene, use Event function and listen for the MRY_NTC_SCENE_LOADED event. When this event is signaled the entire scene has been loaded and all objects, references, cameras and views have been setup.
To read data from the file use the fnIO function that is provided by Moray.
The prototype for this function is:

    void WINAPI fnIO(long lStreamID,void *pData,unsigned int nLength);

The lStreamID that is passed to this function must be the lStreamID that was passed to the ReadFromStream function.

See Also

RequiredStreamSize, WriteToStream


Top