| 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 |
|
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
|
|
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. |
|
|
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
|
|
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:
create a mesh2 object.
The action is stored in Morays Undo buffer if the created element is not a texture.
See Also
|
|
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
|
|
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
|
|
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 |
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
- determines that the layer information of the object should be set according to the pObjectLayers.
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
|
|
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
|
|
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.
|
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 |
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
|
|
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
|
|
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:
|
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
|
|
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
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.
|
|
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:
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
V2.08 and later only.
|
|
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.
V2.09 and later only.
See Also
|
|
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
|
|
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.
|
|
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
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
|
|
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
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
|
|
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
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
|
|
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 |
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
|
|
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:
|
|
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:
- Moray is in dolly mode.
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
From Moray V3.5, the coordinates are ignored, since OpenGL always repaints the entire screen.
See Also
GetViewInfo, ReleaseBackdrop, AllocateBackdrop, RenderBackdrop, InvalidateBackdrop
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
|
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:
|
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:
|
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
|
|
|
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
|
|
|
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
|
|
|
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
|
|
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:
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
|
|
|
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
|
|
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
|
|
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
|
|
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 |
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
|
|
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
|
PromptForFilename