C API

Welcome to the documentation for the Mari C Application Programmer Interface.

The Mari C API is provided as grouped sets of functions to perform specific tasks. Users can build plug-in libraries that return lists of supported plug-in structures, each of which indicates the name and version of the API it supports. The various APIs are listed in the Modules section on the left.

The API is provided solely as C functions to avoid any dependency on compiler versions or configurations, and to simplify name resolution. It does not require developers to link their plug-ins to any specific library; they only need to define a specified set of functions so the Mari host can interact with them. These specific functions are all defined through the main include file, Mari.h. The general plug-in interface can be found in FnPluginSystem.h, and a simple description of working with it is in the Plug-in System section.

Please see the Modules list on the left to find information on specific subsections of the API.

A set of examples are provided to demonstrate writing plug-in code for the available interfaces. Please see the documentation for them for a description of how to build them, including the Makefiles or Visual Studio solution according to the platform.

Mari Project Structure

Mari projects are structured according to the following hierarchy:

- Project
  - Entities (container tranform nodes)
    - GeoEntities ("objects")
      - GeoVersions
        - GeoObjects
          - GeoData
      - Patches
      - Channels
        - Images
          - Mip-map levels
            - Multiple 256x256 tiles
      - Shaders
      - Selection groups
      - Child Entities
  - Image Manager images
    - One full-resolution tile
  - Canvas Manager cameras
    - Camera

A description of each of these items is below.

Entity: these are tranform containers that contain other entities or GeoEntities.
GeoEntity: these are referred to in the GUI as “objects”
GeoVersion: a GeoEntity can be composed of one or more versions; only one is displayed at any time
GeoObject: an individual lower-level geometry mesh; versions are composed of one or more meshes, and all are displayed at once
GeoData: the raw data making up a given GeoObject (vertices, UVs, normals, indices, etc)
Selection group: a collection of faces to select as a unit using the “Selection Groups” palette
Child GeoEntities: each entity may have child entities, which may have their own relative transforms
Channel: a collection of images, one for each occupied UV patch. These can be referenced by UDIM number
Image: the pixel data for a single, optionally mip-mapped and tiled, image. Images are composed of one or more tiles, which are separate regions of image data. Images in channels are always divided into 256x256 tiles, so a 512x512 image would be divided into a 2x2 grid of 256x256-pixel tiles
Mip-map levels: channels each have a number of mip-map levels used at various levels of detail, starting at their full resolution, and stopping at the level where only a single 256x256 tile is needed
256x256 tiles: these make up the separate regions of an image. For example, a 1024x1024 image in a channel will contain 16 tiles (4x4). A tile may contain pixel data in byte, half-float, or float formats with three (RGB) or four (RGBA) components
Image Manager images: unlike channel images, these are composed of a single tile, which is at the full resolution of the image. These images are not mip-mapped. They can be stored with a project, or loaded separately into Mari when no project is open
Camera Manager cameras: 3D cameras used in each canvas view

Camera Reader API

group Camera Reader API

This API allows Mari to load from custom camera formats.

Defines

MRI_CAMERA_READER_API_NAME "MriCameraReader": Use this in plug-in structure definitions to provide the string identifier of the camera reader API.

MRI_CAMERA_READER_API_VERSION 2000

Use this in plug-in structure definitions to provide the integer version of the camera reader API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Typedefs

typedef MriUserItemHandle MriCameraHandle: A camera object.

Enums

enum MriCameraPluginResult

Return values form camera plug-in and host functions.

Values:

enumerator MRI_CAM_SUCCEEDED = 0: The operation completed successfully.

enumerator MRI_CAM_FAILED = 1: The operation failed in a general or unspecified way.

enumerator MRI_CAM_NOT_SUPPORTED = 2: The operation is not supported on this data type.

enumerator MRI_CAM_INVALID_HANDLE = 3: An invalid handle was supplied.

enumerator MRI_CAM_NOT_CREATED = 4: The camera must be created before calling this operation.

enumerator MRI_CAM_ALREADY_CREATED = 5: The camera cannot be created twice.

enumerator MRI_CAM_INVALID_POINTER = 6: An invalid (NULL) pointer was provided.

enumerator MRI_CAM_FILE_OPEN_FAILED = 7: The specified file could not be opened.

enumerator MRI_CAM_FILE_READ_FAILED = 8: The specified file could not be read.

enumerator MRI_CAM_INVALID_FRAME = 9: An invalid frame number (e.g., negative) was specified.

enum MriCameraType

Types of cameras accepted for camera creation.

Values:

enumerator MRI_CAM_PERSPECTIVE = 0: Perspective camera.

enumerator MRI_CAM_ORTHO = 1: Orthographic camera.

Camera Reader Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all geometry reader plug-ins.

The host will check the formats supported by the camera reader using the supportedFormats() function. When a camera of a custom type supported by a plug-in is to be read, the host will call the plug-in’s load() function with appropriate parameters.

To create and store the loaded camera data, plug-ins should call appropriate functions on the host, such as createCamera().

Typedefs

typedef MriCameraPluginResult (*MriCameraReaderFrameRangeFunc)(const char *pFileName, const char *pTake, int *pStartFrameOut, int *pEndFrameOut, const char **ppMessageStringOut)

Returns the frame range of a camera at the given path.

MriCameraPluginResult frameRange(char *pFileName, char *pTake,
                       int *pStartFrameOut, int *pEndFrameOut, const char **ppMessageStringOut); 

Warning and error messages for the loading operation can be provided using ppMessageStringOut. To supply multiple messages, separate each with a new line character (‘\n’). Each message will have the file name prepended, except if it starts with a colon (‘:’). ppMessageStringOut may be left as NULL (as it is when passed in) to indicate that there are no messages to display.

Param pFileName:: The name of the file to examine, with full path. This will match one of the formats supported by the plug-in.
Param pTake:: The optional name of a particular animation take within the file to examine. If no take is given then the full range for all takes should be returned..
Param pStartFrameOut:: Receives the first frame number in the animation timeline. The pointer will not be NULL.
Param pEndFrameOut:: Receives the last frame number in the animation timeline. The pointer will not be NULL.
Param ppMessageStringOut:: Set this to a string containing warning or error messages if desired. (See above)

typedef MriCameraPluginResult (*MriCameraReaderLoadFunc)(MriCameraHandle Entity, const char *pFileName, const char **ppMessageStringOut)

Loads a camera from the given file name.

MriCameraPluginResult load(MriCameraHandle CameraHandle, char *pFileName, const char *pFileName,
                        const char **ppMessageStringOut); 

Warning and error messages for the loading operation can be provided using ppMessageStringOut. To supply multiple messages, separate each with a new line character (‘\n’). Each message will have the file name prepended, except if it starts with a colon (‘:’). ppMessageStringOut may be left as NULL (as it is when passed in) to indicate that there are no messages to display.

Any attributes set on CameraHandle after a successful return from this function will be added to the loaded entity as metadata. See setAttribute() for details. Please note though that string lists are not supported as metadata, and will be stored as strings instead.

Param Entity:: This provides a reference to the individual camera loading operation, and should be passed into all related host functions.
Param pFileName:: The name of the file to load, with full path. This will match one of the formats supported by the plug-in.
Param ppMessageStringOut:: Set this to a string containing warning or error messages if desired. (See above)
Return:: The success state of the function

struct MriCameraReaderPluginV1

#include <MriCameraReaderPlugin.h>

Camera reader plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

struct MriCameraReaderPluginV2

#include <MriCameraReaderPlugin.h>

Camera reader plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Camera Reader Host Definitions

group Host Definitions

This functionality is provided by the camera reader plug-in host.

All of the data passed to these functions will be copied by Mari, so there is no need to maintain the buffers after the calls return.

Typedefs

typedef MriCameraPluginResult (*MriCameraReaderCreateCameraFunc)(MriCameraHandle CameraHandle, MriCameraType Type, const char *pIdentifier)

Creates a new camera of the given type.

MriCameraPluginResult createCamera(MriCameraHandle CameraHandle, MriCameraType Type, const char *pIdentifier); 

Creates a new camera if the given type. Subsequent calls to any host functions will set individual properties of the camera, such as the FOV. Host functions require a frame number, to allow for animated cameras. For cameras without animation, simply use a frame number of 0.

Param CameraHandle:: The handle provided to the load() function,
Param Type:: The type of camera to create (perspective or ortho).
Param pIdentifier:: A string identifier for the camera.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetFarFunc)(MriCameraHandle CameraHandle, int Frame, float Far)

Sets the far clipping plane for the camera.

MriCameraPluginResult setFar(MriCameraHandle CameraHandle, int Frame, float Far);

Use this function to set the far clipping plane for the camera, in milimetres. This is the length along the look at vector for which the camera view frustum ends.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param Far:: The position of the far clipping plane.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetFovFunc)(MriCameraHandle CameraHandle, int Frame, float FovX, float FovY)

Sets the field of view (FOV) for the camera.

MriCameraPluginResult setFov(MriCameraHandle CameraHandle, int Frame, float FovX, float FovY);

Use this function to set the field of view angle of the camera, in degrees, in the X and Y direction.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param FovX:: The horizontal field of view, in degrees.
Param FovY:: The vertical field of view, in degrees.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetLookAtFunc)(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Z)

Sets the look at vector for the camera.

MriCameraPluginResult setLookAt(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Z);

Use this function to set the look at vector for the camera. This vector represents the direction the camera is pointing to in 3D space (from eye to reference point). The vectors should be be normalized.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param X:: The x coordinate of the 3D vector.
Param Y:: The y coordinate of the 3D vector.
Param Z:: The z coordinate of the 3D vector.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetNearFunc)(MriCameraHandle CameraHandle, int Frame, float Near)

Sets the near clipping plane for the camera.

MriCameraPluginResult setNear(MriCameraHandle CameraHandle, int Frame, float Near);

Use this function to set the near clipping plane for the camera, in milimetres. This is the length along the look at vector for which the camera view frustum begins.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param Near:: The position of the near clipping plane.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetTranslationFunc)(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Z)

Sets the translation vector of the camera.

MriCameraPluginResult setTranslation(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Y);

Use this function to set the translation (position) of the camera in 3D space. Units should be in centimetres.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param X:: The x coordinate of the 3D translation.
Param Y:: The y coordinate of the 3D translation.
Param Z:: The z coordinate of the 3D translation.
Return:: The success state of the function.

typedef MriCameraPluginResult (*MriCameraReaderSetUpFunc)(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Z)

Sets the up vector for the camera.

MriCameraPluginResult setUp(MriCameraHandle CameraHandle, int Frame, float X, float Y, float Z);

Use this function to set the up vector for the camera. This vector represents the orientation of the camera in 3D space. The vector should be normalized.

Param CameraHandle:: The handle provided to the load() function,
Param Frame:: The frame to set the data for, which must not be negative.
Param X:: The x coordinate of the 3D vector.
Param Y:: The y coordinate of the 3D vector.
Param Z:: The z coordinate of the 3D vector.
Return:: The success state of the function.

struct MriCameraReaderHostV1

#include <MriCameraReaderPlugin.h>

An interface of host functions supplied by Mari for camera reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Display Render API

group Display Render API

This API allows to render a custom display.

Defines

MRI_DISPLAY_RENDER_API_NAME "MriDisplayRender": Use this in plug-in structure definitions to provide the string identifier of the display render API.

MRI_DISPLAY_RENDER_API_VERSION 1000

Use this in plug-in structure definitions to provide the integer version of the display render API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Display Render Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all display Render plug-ins.

Typedefs

typedef MriUserPluginResult (*MriDisplayRenderDisplayDestroyedFunc)(const char *DisplayName)

Called when the custom display widget is destroyed.

In response to destruction of widget, the custom renderer is given a chance to clean up anything to do with the custom display.

For example, if there is background threads writing to the offscreen buffer. Make sure that the threads are stopped before this callback returns.

MriUserPluginResult (*MriDisplayRenderDisplayDestroyedFunc)(const char *DisplayName);

Param DisplayName:: The name of the display to render into.
Return:: The success state of the function

typedef MriUserPluginResult (*MriDisplayRenderDisplayResizedFunc)(const char *DisplayName, int DisplayWidth, int DisplayHeight)

Called when the custom display widget is resized.

In response to resizing of widget, the custom renderer is given a chance to update the size of the offscreen buffer of the widget. It is OK to leave the buffer size fixed. Use resizeOffscreenBuffer() to resize the offscreen buffer of the widget.

MriUserPluginResult (*MriDisplayRenderDisplayResizedFunc)(const char *DisplayName,
                                                          int DisplayWidth,
                                                          int DisplayHeight); 

Param DisplayName:: The name of the display to render into.
Param DisplayWidth:: The width of the display to render into.
Param DisplayHeight:: The height of the display to render into.
Return:: The success state of the function

typedef MriUserPluginResult (*MriDisplayRenderRenderFunc)(const char *DisplayName, unsigned char *OffscreenBufferPointer, int OffscreenBufferWidth, int OffscreenBufferHeight)

Renders the pixels into the display.

MriUserPluginResult (*MriDisplayRenderRenderFunc)(const char *DisplayName,
                                                  int DisplayWidth,
                                                  int DisplayHeight); 

Param DisplayName:: The name of the display to render into.
Param OffscreenBufferPointer:: The pointer to which the display pixels should be written to each pixel is of ARGB format with 8 bits each. In total, each pixel is 32bits.
Param OffscreenBufferWidth:: The width of the offscreen buffer to render into.
Param OffscreenBufferHeight:: The height of the offscreen buffer to render into.
Return:: The success state of the function

struct MriDisplayRenderPluginV1

#include <MriDisplayRenderPlugin.h>

The user plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Display Render Host Definitions

group Host Definitions

This functionality is provided by the display render plug-in host.

Typedefs

typedef MriUserPluginResult (*MriDisplayRenderResizeOffscreenBufferFunc)(const char *DisplayName, int OffscreenBufferWidth, int OffscreenBufferHeight, unsigned char **NewBufferPointer)

This resizes the offscreenbuffer of the custom display widget specified by the DisplayName.

After resizing the offscreen buffer, a new memory block is allocated to the offscreen buffer. Make sure to fill all pixels. Once filled, sparse lazy update is OK until resized again.

MriUserPluginResult resizeOffscreenBuffer(const char* DisplayName,int OffscreenBufferWidth,int OffscreenBufferHeight, unsigned char** NewBufferPointer); 

Param DisplayName:: The name of the display widget.
Param OffscreenBufferWidth:: The width of the offscreen buffer to resize to.
Param OffscreenBufferHeight:: The height of the offscreen buffer to resize to.
Param NewBufferPointer:: The pointer to the new buffer will be returned into the unsigned char* memory block pointed to by NewBufferPointer. NULL if resize fails.
Return:: The success state of the function

typedef MriUserPluginResult (*MriDisplayRenderUpdateDisplayFunc)(const char *DisplayName)

This triggers update of the custom display widget so that the render() will be called.

MriUserPluginResult updateDisplay(const char* DisplayName); 

Param DisplayName:: The name of the display widget.
Return:: The success state of the function

struct MriDisplayRenderHostV1

#include <MriDisplayRenderPlugin.h>

An interface of host functions supplied by Mari for the user plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Geometry Access API

group Geometry Access API

This API allows access to geometry data in Mari.

Defines

MRI_GEOMETRY_ACCESS_API_NAME "MriGeometryAccessPlugin": Use this in plug-in structure definitions to provide the string identifier of the API.

MRI_GEOMETRY_ACCESS_API_VERSION 1001

Use this in plug-in structure definitions to provide the integer version of the API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Geometry Access Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all geometry access plug-ins.

The plugin must implement readGeoEntity(), given uuids about a geo entity and version, to drill down from GeoEntity to version to mesh to data channels and get the geometry data back.

Please note that a version will store 2 lists of meshes, an original unsubdivided one, and subdivided meshes. The latter can be of various subdivision levels as well. For example, let’s say we have an object that has been subdivided to level 2. The The following meshes will be accessible from the GeoVersion:

Original unsubdivided meshes
Subdivided meshes for level 0 (same as original meshes, but triangulated and reindexed)
Subdivided meshes for level 1 (the meshes, subdivided once)
Subdivided meshes for level 2 (the meshes, subdivided twice)

Typedefs

typedef MriGeoPluginResult (*MriGeometryAccessReadGeoEntityFunc)(MriGeoEntityHandle GeoEntityHandle, const char *GeoUuid, const char *VersionUuid, int Frame, int QuerySubdivisionMesh, int SubdivisionLevel)

Implements logic to locate a mesh(es) for a geo entity and version and gather channel data (uv, normal, vertex and etc).

MriGeoPluginResult readGeoEntity(MriGeoEntityHandle GeoEntityHandle,
                                    const char* GeoUuid,
                                    const char* VersionUuid,
                                    int Frame,
                                    int QuerySubdivisionMesh,
                                    int SubdivisionLevel); 

The GeoEntity and Geo Version must exist and be loaded within the current Mari project, otherwise an error is returned. We need to pass in geo entity uuid, a version uuid within that geo entity and any extra parameter required so that we can query Mari for mesh data.

Param GeoEntityHandle:: The handle associated with the geo entity, being queried in the operation.
Param GeoUuid:: The uuid of the geo entity to get geometry data from.
Param VersionUuid:: The uuid of the version, within the geo entity, to use for getting to mesh data.
Param Frame:: The frame to query for channel data, in case of animation.
Param QuerySubdivisionMesh:: A flag to indicate whether we need to query subdivision meshes from the geo entity, instead of its original (unsubdivided) meshes.
Param SubdivisionLevel:: The level of subdivision, at which we need mesh data.
Return:: The success state of the function

struct MriGeometryAccessPluginV1

#include <MriGeometryAccessPlugin.h>

The user plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Geometry Access Host Definitions

group Host Definitions

This functionality is provided by the geometry access plug-in host.

So, we need functions to query MriGeoEntity (MriGeoEntityHandle), MriGeoVersion (MriGeoVersionHandle), MriGeo (MriGeoObjectHandle/MriGeoMeshHandle), MriChannel (MriGeoDataHandle, (MriGeoDataRole, MriGeoDataType))

To access geometry data, we need to:

Get a geo entity (MriGeoEntityHandle), given its uuid.
We then need to query a version (MriGeoVersionHandle) from the geo entity, given a version uuid.
We then query all the meshes (MriGeoMeshHandle) from the version.
For each of the mesh, we get the available data channels (MriGeoDataHandle).
We then query data out of the mesh.

Typedefs

typedef MriGeoPluginResult (*MriGeometryAccessGetGeometryBlockFunc)(MriGeoEntityHandle GeoEntityHandle, const char *GeoUuid)

This locates the required Geo Entity in Mari, given a uuid and associates it with a handle, so that it can be referenced later easily.

MriGeoPluginResult getGeoEntityBlock(MriGeoEntityHandle GeoEntityHandle, const char* GeoUuid); 

The GeoEntity must exist and be loaded within the current Mari project, otherwise an error is returned.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used as a token to access that object throughout the Api.
Param GeoUuid:: The uuid of the Geo Entity required.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetGeometryNameFunc)(MriGeoEntityHandle GeoEntityHandle, char **OutName)

Queries the geo entity for its name.

MriGeoPluginResult getGeoEntityName(MriGeoEntityHandle GeoEntityHandle, char** OutName); 

Returns the name of the GeoEntity in Mari.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Param OutName:: The name of the Geo Entity.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetGeometrySubdivisionCurrentLevelFunc)(MriGeoEntityHandle GeoEntityHandle, int *OutSubdivisionLevel)

Returns the current subdivision level of the Geo Entity.

MriGeoPluginResult getGeoEntitySubdivisionCurrentLevel(MriGeoEntityHandle GeoEntityHandle, int* OutSubdivisionLevel); 

Get the current subdivision level of the Geo Entity.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Param OutSubdivisionLevel:: The current subdivision level of the Geo Entity.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetGeometrySubdivisionRangeFunc)(MriGeoEntityHandle GeoEntityHandle, int *OutSubdivisionMin, int *OutSubdivisionMax)

Returns the minimum and maximum levels of subdivisions, added for the Geo Entity.

MriGeoPluginResult getGeoEntitySubdivisionRange(MriGeoEntityHandle GeoEntityHandle, int* OutSubdivisionMin, int* OutSubdivisionMax); 

Get the subdivision levels of the Geo Entity.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Param OutSubdivisionMin:: The minimum subdivision level of the Geo Entity.
Param OutSubdivisionMax:: The maximum subdivision level of the Geo Entity.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetGeometryTransformFunc)(MriGeoEntityHandle GeoEntityHandle, int Frame, double **OutTransformMatrix, double **OutTransposeInverseTransformMatrix)

Returns the transform matrices of the Geo Entity.

MriGeoPluginResult getGeoEntityTransform(MriGeoEntityHandle GeoEntityHandle, int Frame, double** OutTransformMatrix, double** OutInverseTransposeTransformMatrix); 

Returns the world-space transform matrix and its transpose of the inverse equivalent as well. The former is required to transform the geometry vertices, while the latter is required for transforming normals.

The matrices are 4x4 and returned as 16 double values. Note that objects in Mari are stored in a hierarchical manner and the geometry NEEDS to be transformed before they can be used out of Mari.

We also need to pass in a frame, since transforms can vary across frames for animation.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Param Frame:: The frame of animation.
Param OutTransformMatrix:: The transform matrix, used for vertices.
Param OutTransposeInverseTransformMatrix:: The transpose of the inverse of the transform matrix, used for normals.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataBlockFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, int Frame)

Acquires the data associated with a data channel.

MriGeoPluginResult getGeoEntityMeshChannelDataBlock(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle); 

This must be used before we get the geometry data to ensure that the data reference we get afterwards stays valid in Mari’s memory, until we explicitly release the data using releaseGeoEntityMeshChannelDataBlock(); getting the channel data directly without using the wrapper get-block and release-block will not ensure that the data pointer is valid once we get it.

Please note that we need to pass in a data frame, in case of animated data.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoChannelHandle:: The handle of the data channel.
Param Frame:: Frame at which to get channel geometry data.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataElementSize)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, int *OutGeoDataElementSize)

Returns the size of a unit of data in a channel.

MriGeoPluginResult getGeoEntityMeshChannelDataElementSize(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, int* OutGeoDataElementSize); 

This returns how many elements are used, contiguously, to represent data in the channel. E.g., a Vector3f would have its element size as 3, an int would have its value as 1 and etc.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoMeshHandle:: The handle of the data channel.
Param OutGeoDataElementSize:: The size of a unit of data in the channel.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataEntryCountFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, unsigned int *OutGeoDataEntryCount)

Returns the count of entries of the data array in a channel.

MriGeoPluginResult getGeoEntityMeshChannelDataEntryCount(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, unsigned int* OutGeoDataEntryCount); 

This returns how many data entries there are in the channel.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoMeshHandle:: The handle of the data channel.
Param OutGeoDataEntryCount:: The number of data entries in the channel.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, const unsigned char **OutGeoData, size_t *OutGeoDataSize)

Returns the data in a channel.

MriGeoPluginResult getGeoEntityMeshChannelData(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, const unsigned char ** OutGeoData, size_t* OutGeoDataSize); 

This returns the data in the channel, cast as unsigned char pointer. To safely read the data back, we need to:

use getGeoEntityMeshChannelDataRole() to determine the role of the data we need.
use getGeoEntityMeshChannelDataType() to cast the data back to its correct data type
use getGeoEntityMeshChannelDataElementSize() to get the number of continuous elements making up the data
use getGeoEntityMeshChannelDataEntryCount() to get the number of data entries in the data channel

Please note that we NEED to call getGeoEntityMeshChannelDataBlock() first, to get initialise the data block and releaseGeoEntityMeshChannelDataBlock(), once we’ve done with accessing the geometry data; this is to ensure that the geo data is valid throughout. Mari tends to cache data back to disk, based on its data manager, and there’s no guarantee that the data pointer holds valid data unless we explicitly ask Mari to keep the data reference and release it afterwards.

Also, note that the data type is marked as const and is NOT meant to be modified in the api world.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoChannelHandle:: The handle of the data channel.
Param OutGeoData:: The data in the channel.
Param OutGeoDataSize:: The size (in bytes) of data in the channel.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataRoleFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, MriGeoDataRole *OutGeoDataRole)

Returns the role of the data in a channel.

MriGeoPluginResult getGeoEntityMeshChannelDataRole(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, MriGeoDataRole* OutGeoDataRole); 

Returns the role of data, contained within a channel. This tells us what the channel contains, i.e., uvs or normals or vertices and etc.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoMeshHandle:: The handle of the data channel.
Param OutGeoDataRole:: The role/meaning of the data in the channel.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelDataTypeFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, MriGeoDataType *OutGeoDataType)

Returns the type of the data in a channel.

MriGeoPluginResult getGeoEntityMeshChannelDataType(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle, MriGeoDataType* OutGeoDataType); 

Returns the type of data, contained within a channel. This is required so that we can cast the returned data into its appropriate data type.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoMeshHandle:: The handle of the data channel.
Param OutGeoDataType:: The data type of the channel.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshChannelsFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, void **OutMeshChannels, int *OutChannelCount)

Queries a Geo mesh for its available data channels.

MriGeoPluginResult getGeoEntityMeshChannels(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, void** OutMeshChannels, int* OutChannelCount); 

We use this function to get all the original (un-subdivided) meshes and their corresponding handles for a geo version.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param OutMeshChannels:: A list of data channel handles, associated with the channels in Mari.
Param OutChannelCount:: The number of data channel, contained within the mesh.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshInfoFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, int *OutReverseWinding)

Returns various information about the mesh.

MriGeoPluginResult getGeoEntityMeshInfo(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, int* OutReverseWinding); 

Returns the various information of the GeoEntity in Mari.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param OutReverseWinding:: Whether the winding should be reversed for the Geo Entity.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshNameFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, char **OutName)

Queries a mesh for its name.

MriGeoPluginResult getGeoEntitySubdivisionMeshes(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, int SubdivisionLevel, void** OutGeoMeshes, int* OutMeshCount); 

Returns the name of a mesh.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param OutName:: The name of the mesh.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetMeshSubdivisionInfoFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, int *OutIsSubdivisionMesh, int *OutSubdivisionLevel)

Queries whether a mesh is subdivided and its subdivision level.

MriGeoPluginResult getGeoEntityMeshSubdivisionInfo(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, int* OutIsSubdivisionMesh, int* OutSubdivisionLevel); 

Returns the name of a mesh.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param OutIsSubdivisionMesh:: Flag to indicate whether this mesh is subdivided.
Param OutSubdivisionLevel:: The subdivision level of the mesh.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetOriginalMeshesFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, void **OutGeoMeshes, int *OutMeshCount)

Queries a Geo Version for its original meshes.

MriGeoPluginResult getGeoEntityOriginalMeshes(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, void** OutGeoMeshes, int* OutMeshCount); 

We use this function to get all the original (un-subdivided) meshes and their corresponding handles for a geo version.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param OutGeoMeshes:: A list of mesh handles, associated with the mesh objects in Mari.
Param OutMeshCount:: The number of meshes, contained within the version.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetSubdivisionMeshesFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, int SubdivisionLevel, void **OutGeoMeshes, int *OutMeshCount)

Queries a Geo Version for its subdivision meshes.

MriGeoPluginResult getGeoEntitySubdivisionMeshes(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, int SubdivisionLevel, void** OutGeoMeshes, int* OutMeshCount); 

We use this function to get all the subdivision meshes and their corresponding handles for a geo version.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param SubdivisionLevel:: The subdivision level for which we want the meshes.
Param OutGeoMeshes:: A list of mesh handles, associated with the mesh objects in Mari.
Param OutMeshCount:: The number of meshes, contained within the version.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetVersionFunc)(MriGeoEntityHandle GeoEntityHandle, const char *VersionUuid, void **OutGeoVersions, int *OutVersionCount)

Queries a Geo Entity for a specific version, given a version uuid.

MriGeoPluginResult getGeoEntityVersion(MriGeoEntityHandle GeoEntityHandle, const char* VersionUuid, void** OutGeoVersions, int* OutVersionCount); 

We use this function to get a specific version of the geo entity, through its uuid.

We then use the version count, returned, to determine if the version was found.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param VersionUuid:: The required version’s uuid.
Param OutGeoVersions:: A list of version handles, used to refer to the versions in Mari.
Param OutVersionCount:: The number of versions found.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetVersionNameFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, char **OutName)

Queries the name of a geo version.

MriGeoPluginResult getGeoEntityVersionName(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, char** OutName); 

Get the name of a geometry version.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param OutName:: The name of the version.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetVersionPathFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, char **OutPath)

Queries the file path of a geo version.

MriGeoPluginResult getGeoEntityVersionPath(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, char** OutPath); 

Get the name of a geometry version.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param OutPath:: The path of the version.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetVersionSettingsFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, int *OutCount, char ***OutSettingsKeys, char ***OutSettingsValues)

Queries the file path of a geo version.

MriGeoPluginResult getGeoEntityVersionSettings(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, int* OutCount, char *** OutSettingsKeys, char *** OutSettingsValues); 

This returns a list of metadata, stored on the geo version, in Mari, either at geometry import time or stored by some operation.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param OutCount:: The count of metadata on the the version.
Param OutSettingsKeys:: The metadata keys.
Param OutSettingsValues:: The values of the metadata.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessGetVersionsFunc)(MriGeoEntityHandle GeoEntityHandle, void **OutGeoVersions, int *OutVersionCount)

Queries a Geo Entity for its versions.

MriGeoPluginResult getGeoEntityVersions(MriGeoEntityHandle GeoEntityHandle, void** OutGeoVersions, int* OutVersionCount); 

We use this function to get all the versions for a geo entity and their corresponding handles, through which we can refer to a specific version later on.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param OutGeoVersions:: A list of version handles, associated with the version objects in Mari.
Param OutVersionCount:: The number of versions, contained within the geo entity.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessReleaseGeometryBlockFunc)(MriGeoEntityHandle GeoEntityHandle)

Releases the geometry block, associated with the Geo Entity handle.

MriGeoPluginResult releaseGeometryBlock(MriGeoEntityHandle GeoEntityHandle); 

Once we have finished with querying the geo entity and its mesh data, we need to safely release the handle associated with it.

This is a vital step and make sure memory is cleaned up properly. This always need to go hand-in-hand with the getGeoEntityBlock() function.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity and used to reference the object in the Api world.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeometryAccessReleaseMeshChannelDataBlockFunc)(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle)

Releases the data associated with a data channel.

MriGeoPluginResult releaseGeoEntityMeshChannelDataBlock(MriGeoEntityHandle GeoEntityHandle, MriGeoVersionHandle GeoVersionHandle, MriGeoMeshHandle GeoMeshHandle, MriGeoDataHandle GeoChannelHandle); 

This must be used after we have finished with the geometry data, to ensure that the geometry block in Mari’s cache is released safely.

Param GeoEntityHandle:: The handle that is associated with the Geo Entity.
Param GeoVersionHandle:: The handle of the version.
Param GeoMeshHandle:: The handle of the mesh.
Param GeoChannelHandle:: The handle of the data channel.
Return:: The success state of the function

struct MriGeometryAccessHostV1

#include <MriGeometryAccessPlugin.h>

An interface of host functions supplied by Mari for geometry access plug-in to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Geo I/O

group Geo I/O

These types are used by geometry related plug-ins.

Typedefs

typedef MriUserItemHandle MriGeoDataHandle

Handles, used as tokens between internal objects and their representations in the external world.

A single type of geometry data, such as vertices or normals

typedef MriUserItemHandle MriGeoEntityHandle: An Entity, that acts as a parent for other entities and tranforms them, or a Geo Entity that contains a number of geo versions - often just one.

typedef MriUserItemHandle MriGeoMeshHandle: A geo mesh contains a set of geo data (vertices, normals, etc)

typedef MriUserItemHandle MriGeoObjectHandle: A geo object contains a set of geo data (vertices, normals, etc)

typedef MriUserItemHandle MriGeoVersionHandle: A geo version contains a set of geo objects - often just one.

typedef MriUserItemHandle MriSelectionGroupHandle: A geo entity contains a number of selections - sometimes none.

Enums

enum MriGeoDataRole

Roles for geometry data, such as vertices or UVs.

Values:

enumerator MRI_GDR_INVALID = -1: Invalid type.

enumerator MRI_GDR_VERTICES = 0: Vertex coordinates (x, y, z)

enumerator MRI_GDR_UV = 1: Texture coordinates (u, v)

enumerator MRI_GDR_NORMALS = 2: Vertex normal directions (x, y, z)

enumerator MRI_GDR_TANGENTS = 3: Vertex tangents (x, y, z)

enumerator MRI_GDR_COLORS = 4: Vertex colors (r, g, b)

enumerator MRI_GDR_INDICES = 5: Vertex indices (three per triangle)

enumerator MRI_GDR_ORIGINAL_VERTICES = 6: Copy of Vertex coordinates (x, y, z) to be used for ptex.

enumerator MRI_GDR_ORIGINAL_NORMALS = 7: Copy of Vertex normal directions (x, y, z) to be used for ptex.

enumerator MRI_GDR_ORIGINAL_INDICES = 8: Non-triangulated vertex indices (e.g., 4 for a quad, 3 for a triangle)

enumerator MRI_GDR_ORIGINAL_NORMAL_INDICES = 9: Non-triangulated normal indices (e.g., 4 for a quad, 3 for a triangle)

enumerator MRI_GDR_FACE_VERTEX_COUNTS = 10: Number of corners per face(e.g., 4 for a quad) to be used for ptex.

enumerator MRI_GDR_FACE_INDICES = 11: Face indices.

enumerator MRI_GDR_AMBIENT_OCCLUSION = 13: AO property per vertex.

enumerator MRI_GDR_ORIGINAL_UV_INDICES = 15

enumerator MRI_GDR_MESH_FACE_VERTEX_COUNTS = 100

Original uvs indices.

(For new subdividable mesh) Number of vertices for each face.

enumerator MRI_GDR_MESH_VERTEX_INDICES = 101: (For new subdividable mesh) Vertex indices.

enumerator MRI_GDR_MESH_VERTICES = 102: (For new subdividable mesh) Vertex coordinates (x, y, z).

enumerator MRI_GDR_MESH_NORMAL_INDICES = 103: (For new subdividable mesh) Normal indices. If not present, MRI_GDR_MESH_NORMALS will be assumed to be vertex normals.

enumerator MRI_GDR_MESH_NORMALS = 104: (For new subdividable mesh) Normals (x, y, z). If not present, Mari will generate normals

enumerator MRI_GDR_MESH_UV0_INDICES = 105: (For new subdividable mesh) Uv0 indices. If not present, MRI_GDR_MESH_UV0 will be assumed to hav the same indices as vertices

enumerator MRI_GDR_MESH_UV0 = 106: (For new subdividable mesh) Texture coordinates for the UV set 0.

enumerator MRI_GDR_MESH_SUBD_CREASE_LENGTHS = 150: (For new subdividable mesh) (Optional) Crease lengths. Each number specifies how many elemens in the crease indices is a connected crease edge. E.g. if CreaseLengths = [3,2] and CreaseIndices = [6,2,3,8,5], then the edges connecting vertices 6,2,3 forms the first crease while the edge connecting vertices 8,5 forms the second crease.

enumerator MRI_GDR_MESH_SUBD_CREASE_INDICES = 151: (For new subdividable mesh) (Optional) Crease indices (v1, v2, …).

enumerator MRI_GDR_MESH_SUBD_CREASE_SHARPNESS = 152: (For new subdividable mesh) (Optional) Crease sharpness (v1, v2). Each float defines the sharpness of each crease.

enumerator MRI_GDR_MESH_SUBD_CORNER_INDICES = 153: (For new subdividable mesh) (Optional) Corner indices. Each index is the vertex index to be considered as a corner.

enumerator MRI_GDR_MESH_SUBD_CORNER_SHARPNESS = 154: (For new subdividable mesh) (Optional) Corner sharpness. Each float defines the sharpness of each corner.

enumerator MRI_GDR_MESH_SUBD_HOLES = 155: (For new subdividable mesh) (Optional) Holes. Each int defines a hole.

enum MriGeoDataType

Types of data accepted for geometry creation.

Values:

enumerator MRI_GDT_INVALID = -1: Invalid type.

enumerator MRI_GDT_8_BUFFER = 10: A buffer of signed 8-bit, byte, values (signed char)

enumerator MRI_GDT_U8_BUFFER = 11: A buffer of unsigned 8-bit, byte, values (unsigned char)

enumerator MRI_GDT_16_BUFFER = 12: A buffer of signed 16-bit, 2 byte, values (short)

enumerator MRI_GDT_U16_BUFFER = 3: A buffer of unsigned 16-bit, 2 bytes, values (unsigned short)

enumerator MRI_GDT_32_BUFFER = 14: A buffer of signed 32-bit, 4 bytes, values (int)

enumerator MRI_GDT_U32_BUFFER = 2: A buffer of unsigned 32-bit, 4 bytes, values (unsigned int)

enumerator MRI_GDT_HALF_BUFFER = 1: A buffer of 16-bit floating-point values (?float?)

enumerator MRI_GDT_FLOAT_BUFFER = 0: A buffer of 32-bit, 4 bytes, floating-point values (float)

enumerator MRI_GDT_DOUBLE_BUFFER = 15: A buffer of double precision float values (double)

enum MriGeoPluginResult

Return values from geometry plug-in and host functions.

Values:

enumerator MRI_GPR_SUCCEEDED = 0: The operation completed successfully.

enumerator MRI_GPR_FAILED = 1: The operation failed in a general or unspecified way.

enumerator MRI_GPR_NOT_SUPPORTED = 2: The operation is not supported on this data type.

enumerator MRI_GPR_INVALID_HANDLE = 3: An invalid handle was supplied.

enumerator MRI_GPR_DATA_SIZE_MISMATCH = 4: The supplied data size does not match the size that the function expected to receive.

enumerator MRI_GPR_INVALID_TYPE = 5: An invalid data type was specified.

enumerator MRI_GPR_INVALID_ROLE = 6: An invalid role was specified for the data.

enumerator MRI_GPR_INVALID_POINTER = 7: An invalid (NULL) pointer was provided.

enumerator MRI_GPR_INVALID_DATA_SIZE = 8: The specified data size is not valid for this operation (e.g., not a multiple of the element size)

enumerator MRI_GPR_FILE_OPEN_FAILED = 9: The specified file could not be opened.

enumerator MRI_GPR_FILE_READ_FAILED = 10: The specified file could not be read.

enumerator MRI_GPR_INVALID_FRAME = 11: An invalid frame number (e.g., negative) was specified.

enumerator MRI_GPR_INVALID_FACE_ID = 12: An invalid face id (e.g., negative) was specified.

enumerator MRI_GPR_OUT_OF_RANGE = 13: An invalid subscript is passed in.

enum MriSceneEntityType

Types of entities for hierarchy.

Values:

enumerator MRI_SET_ENTITY = 1: An Entity; a container node that usually acts as a parent for other entities/geoentities. It has a matrix to tranform its children.

enumerator MRI_SET_GEOENTITY = 2: A GeoEntity; contains geometry data as well as can act as a container for other entities. It has a matrix to transform its geometry and children.

enumerator MRI_SET_GEOCAMERA = 3: A GeoCamera; a camera entity loaded from geometry files.

Geometry Reader API

group Geometry Reader API

This API allows Mari to load from custom geometry formats.

Defines

MRI_GEO_READER_API_NAME "MriGeometryReader": Use this in plug-in structure definitions to provide the string identifier of the geometry reader API.

MRI_GEO_READER_API_VERSION 6000

Use this in plug-in structure definitions to provide the integer version of the geometry reader API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

MRI_GEO_READER_ATTR_MERGE_GEO "MriMergeGeo": Set this bool type attribute on a GeoEntity to true to have Mari combine it’s sub-meshes into a single mesh.

Geometry Reader Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all geometry reader plug-ins.

The host will check the formats supported by the geometry reader using the supportedFormats() function. When an object of a custom type supported by a plug-in is to be read, the host will call the plug-in’s load() function with appropriate parameters.

Plug-ins should call the functions in Host Definitions to set up the geometry structure.

Typedefs

typedef MriGeoPluginResult (*MriGeoReaderGetSettingsFunc)(MriUserItemHandle SettingsHandle, const char *pFileName)

Returns the settings that the user can change when loading an object of this type.

MriGeoPluginResult getSettings(MriUserItemHandle SettingsHandle, const char *pFileName); 

The settings should be created as attributes using the given handle. The values set by this function will be used as the defaults for the settings displayed to the user - except when adding a new version to existing geometry, when the setting selected for the original geometry will be used as the default.

The values selected by the user will be passed as attributes to the load() function.

String lists are handled slightly differently to other attributes. Setting a string list attribute here will provide a list of those strings to the user to select from, and when the value is passed into the geometry loader, the option that the user selected will be set as a single string - so please note that the type will be different. Additionally, string lists cannot be passed in as options through the Python API; to match the GUI behaviour, users need to pass in single strings instead.

If this function returns a failure state, or if the function completes without adding any attributes, no settings will be displayed.

Param SettingsHandle:: The handle to set attributes on to provide settings to the user.
Param pFileName:: The name of the file to be loaded. Any file names provided to this function are guaranteed to refer to existing files.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderLoadFunc)(MriGeoEntityHandle Entity, const char *pFileName, const char **ppMessageStringOut)

Loads a geometry entity (the highest-level class of geometry) from the given file name.

MriGeoPluginResult load(MriGeoEntityHandle Entity, const char *pFileName,
                        const char **ppMessageStringOut); 

Warning and error messages for the loading operation can be provided using ppMessageStringOut. To supply multiple messages, separate each with a new line character (‘\n’). Each message will have the file name prepended, except if it starts with a colon (‘:’). ppMessageStringOut may be left as NULL (as it is when passed in) to indicate that there are no messages to display.

Any attributes set on ImageHandle after a successful return from this function will be added to the loaded entity as metadata. See setAttribute() for details. Please note though that string lists are not supported as metadata, and will be stored as strings instead.

Param Entity:: This provides a reference to the individual geometry loading operation, and should be passed into all related host functions.
Param pFileName:: The name of the file to load, with full path. This will match one of the formats supported by the plug-in.
Param ppMessageStringOut:: Set this to a string containing warning or error messages if desired. (See above)
Return:: The success state of the function

struct MriGeoReaderPluginV1

#include <MriGeoReaderPlugin.h>

Geometry reader plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Geometry Reader Host Definitions

group Host Definitions

This functionality is provided by the geometry reader plug-in host.

Mari geometry is structured according to the following hierarchy:

GeoEntity (these are referred to in the GUI as “objects”)
- GeoVersion (an entity can be composed of one or more versions; only one is used at a time)
  - GeoObject (an individual lower-level geometry mesh; versions are composed of one or more meshes, and all are displayed at once)
    - GeoData (such as vertices, UVs, etc)
- GeoEntity children (each entity may have child entities, which may have their own relative transforms)
- SelectionGroup (each entity may have selection groups referencing faces in GeoObjects to ease selection in the GUI)

Mari scenegraph is inherently hierarchical and allows creation of parents and children. Normally we have 2 type of entities:

an Entity : this is a container node that usually acts as a parent for other entities/geoentities. It contains a transform matrix
a Geo Entity (GUI object) : this is an actual container node for geometry data, such as versions and meshes and etc. It also can contain children entities and has a transform matrix to transform its children.

Each of the above items can be created separately, in any order.

GeoData must be assigned to GeoObjects for use. GeoObjects can be added to a GeoVersion explicitly, or if not, they will be added to the last created version. GeoVersions are always implicitly added to the GeoEntity being created, and if no GeoVersion is created, one will be constructed automatically.

In addition, selection groups may be created referencing the faces of objects contained in a GeoEntity. These provide a way to quickly select groups of faces through the GUI.

All of the data passed to these functions will be copied by Mari, so there is no need to maintain the buffers after the calls return.

Typedefs

typedef MriGeoPluginResult (*MriGeoReaderAddFacesToSelectionGroupFunc)(MriGeoEntityHandle Entity, MriSelectionGroupHandle SelectionGroup, MriGeoObjectHandle Object, const int *pFaceIndices, int NumFaces)

Adds all or some faces of a GeoObject to a previously-created selection group.

MriGeoPluginResult addFacesToSelectionGroup(MriGeoEntityHandle Entity,
                                            MriSelectionGroupHandle SelectionGroup,
                                            MriGeoObjectHandle Object,
                                            const int *pFaceIndices, int NumFaces); 

The selection group must have previously been created. If an face index is invalid, i.e. not in the geo object, an error will be returned. To add all faces from the GeoEntity, pass pFaceIndices as NULL and NumFaces as zero.

See also

createSelectionGroup()

Param Entity:: The entity that the object and selection group belong to
Param SelectionGroup:: The selection group to add faces to.
Param Object:: The object that contains the faces to add to the selection group
Param pFaceIndices:: A list of face indices for Object to add to the selection group. May be NULL if NumFaces is zero.
Param NumFaces:: The number of face indices pointed to by pFaceIndices. If pFaceIndices is NULL, this must be zero, which will add all faces from Object to the group.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderAddGeoDataToObjectFunc)(MriGeoEntityHandle Entity, MriGeoObjectHandle Object, MriGeoDataHandle Data)

Sets data in the geometry object for the specific role (such as vertices) that the data was created for.

MriGeoPluginResult addGeoDataToObject(MriGeoEntityHandle Entity, MriGeoObjectHandle Object,
                                      MriGeoDataHandle Data); 

The data must have been created for this geometry entity. If it was for another entity, an invalid handle error will be returned.

Param Entity:: The entity that the object and data belong to. This provides a context for the operation.
Param Object:: The object to assign data to
Param Data:: The data set to assign to the object
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderAddGeoObjectToVersionFunc)(MriGeoEntityHandle Entity, MriGeoVersionHandle Version, MriGeoObjectHandle Object)

Adds a geometry object to a geometry version.

MriGeoPluginResult addGeoObjectToVersion(MriGeoEntityHandle Entity, MriGeoVersionHandle Version,
                                         MriGeoObjectHandle Object); 

If a geo object is not added to a specific geo version, it will be added to the last one created - or to a default one, if no version is created explicitly.

Param Entity:: The entity that the object and version belong to
Param Version:: The geo version to add an object to
Param Object:: The geo object to add to the version
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderCreateChildEntityFunc)(MriGeoEntityHandle ParentEntity, MriGeoEntityHandle *pChildHandleOut)

Creates a new entity as a child of the main one being loaded.

MriGeoPluginResult createChildEntity(MriGeoEntityHandle ParentEntity,
                                     MriGeoEntityHandle *pChildHandleOut); 

Child entities are used as parent containers for other entities or Geo entities. They should only be used for placing geometry in hierarchies and they usually contain a transform matrix to transform their children globally.

Param ParentEntity:: The entity to create a child entity for. This must be a valid handle - either the top-level entity handle passed into the load() function, or one created by a previous call to this function.
Param pChildHandleOut:: Receives the handle to the new child entity. The pointer must not be NULL.

typedef MriGeoPluginResult (*MriGeoReaderCreateChildGeoEntityFunc)(MriGeoEntityHandle ParentEntity, const char *pFileName, MriGeoEntityHandle *pChildHandleOut)

Creates a new Geo Entity as a child of the main one being loaded.

MriGeoPluginResult createChildGeoEntity(MriGeoEntityHandle ParentEntity,
                                        const char *pFileName,
                                        MriGeoEntityHandle *pChildHandleOut); 

Child geo entities are used to encapsulate geometry, so they should have geo data, geo objects, etc. They can also act as parent containers to other entities and also have a global transform matrix to transform their children entities.

Param ParentEntity:: The geo entity to create a child entity for. This must be a valid handle - either the top-level entity handle passed into the load() function, or one created by a previous call to this function.
Param pFileName:: The file name for the child entity, as an identifier. This may be any valid string, but the pointer must not be NULL.
Param pChildHandleOut:: Receives the handle to the new child entity. The pointer must not be NULL.

typedef MriGeoPluginResult (*MriGeoReaderCreateGeoDataFunc)(MriGeoEntityHandle Entity, const void *pData, long long DataSizeBytes, MriGeoDataType DataType, MriGeoDataRole Role, MriGeoDataHandle *pDataHandleOut)

Creates geometry data, such as vertices or normals, from the given buffer.

MriGeoPluginResult createGeoData(MriGeoEntityHandle Entity, const void *pData,
                                 long long DataSizeBytes, MriGeoDataType DataType,
                                 MriGeoDataRole Role, MriGeoDataHandle *pDataHandleOut); 

The geometry data created by this function can fulfil a variety of roles for a geometry object. Geometry objects compose geometry versions, which in turn make up geometry entities, the highest level of geometry used by Mari. Geometry entities are referred to as “objects” in the Mari user interface.

Data provided to this function will be copied by Mari, so there is no need to maintain the buffer after the call returns.

Geometry data can be added to multiple geometry objects if desired, provided those objects are both part of the same geometry entity. Any geo data that is not added to a geo object will be deleted automatically when the load() function returns.

Param Entity:: The entity, as provided to the load() function, to create data for. This provides a context for the operation, and a way to determine when the data is no longer needed to avoid potential leaks.
Param pData:: The data to copy, which must be in the appropriate format (see DataType)
Param DataSizeBytes:: The number of bytes of data to copy. This must be a multiple of the number of bytes of data used by each element. For example, buffers of vertex data must be a multiple of 12 bytes long, as each vertex will take up three floats.
Param DataType:: Indicates the type of data that is in the buffer: MRI_GDT_FLOAT_BUFFER (vertices, normals, UVs), MRI_GDT_U32_BUFFER (face indices), etc
Param Role:: The role that the data performs - e.g. vertices, UVs, etc
Param pDataHandleOut:: Receives the handle for the new geometry data, if the function succeeds. The pointer must not be NULL.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderCreateGeoObjectFunc)(MriGeoEntityHandle Entity, const char *pIdentifier, int NumTriangles, MriGeoObjectHandle *pObjHandleOut)

Creates a new low-level geometry object.

MriGeoPluginResult createGeoObject(MriGeoEntityHandle Entity, const char *pIdentifier,
                                   int NumTriangles, MriGeoObjectHandle *pObjHandleOut); 

Geometry data must be added to each geometry object before use.

Geo objects should be added to a version object. If objects are not added to a specific version, they will be automatically added to the last version created. (Note that if no versions are created by the plug-in, one will be created automatically)

Param Entity:: The entity, as provided to the load() function, to create an object for. This provides a context for the operation, and a way to determine which geo version to add the entity to if none is specified.
Param pIdentifier:: A string identifier for the object, such as the file name if it is unique.
Param NumTriangles:: The number of triangles in the object’s geometry
Param pObjHandleOut:: Receives the handle for the new geometry object, if the function succeeds. The pointer must not be NULL.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderCreateGeoVersionFunc)(MriGeoEntityHandle Entity, const char *pName, MriGeoVersionHandle *pVersionHandleOut)

Creates a new geometry version - a component of a geo entity.

MriGeoPluginResult createGeoVersion(MriGeoEntityHandle Entity, const char *pName,
                                    MriGeoVersionHandle *pVersionHandleOut); 

All created geo versions will be automatically added to the entity they are created for. If no geo versions are created by the plug-in, one will be created automatically.

At least one geometry object must be added to a geo version before use.

Param Entity:: The entity, as provided to the load() function, to create and add a version for.
Param pName:: The name to use as a unique identifier for the version.
Param pVersionHandleOut:: Receives the handle for the new geometry version, if the function succeeds. The pointer must not be NULL.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderCreateMeshObjectFunc)(MriGeoEntityHandle Entity, const char *pIdentifier, int NumFaces, MriGeoObjectHandle *pObjHandleOut)

Creates a new low-level geometry object that supports non triangle faces and subdivision mesh.

MriGeoPluginResult createMeshObject(MriGeoEntityHandle Entity, const char *pIdentifier,
                                   int NumFaces, MriGeoObjectHandle *pObjHandleOut); 

Geometry data must be added to each mesh object before use.

Geo objects should be added to a version object. If objects are not added to a specific version, they will be automatically added to the last version created. (Note that if no versions are created by the plug-in, one will be created automatically)

Param Entity:: The entity, as provided to the load() function, to create an object for. This provides a context for the operation, and a way to determine which geo version to add the entity to if none is specified.
Param pIdentifier:: A string identifier for the object, such as the file name if it is unique.
Param NumFaces:: The number of faces in the object’s geometry
Param pObjHandleOut:: Receives the handle for the new geometry object, if the function succeeds. The pointer must not be NULL.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderCreateSelectionGroupFunc)(MriGeoEntityHandle Entity, const char *pName, MriSelectionGroupHandle *pSelectionHandleOut)

Creates a new selection group - a list of faces that can be selected as a unit.

MriGeoPluginResult createSelectionGroup(MriGeoEntityHandle Entity, const char *pName,
                                        MriSelectionGroupHandle *pSelectionHandleOut); 

A selection group can hold references to specific faces in specific objects.

See also

addFacesToSelectionGroup()

Param Entity:: The entity to create a selection group for
Param pName:: The name for the selection group, as an identifier. This may be any valid string, but the pointer must not be NULL.
Param pSelectionHandleOut:: Receives the handle to the new selection group. The pointer must not be NULL.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderGetEntityHandleFromNameKeyFunc)(const char *pName, MriGeoEntityHandle *pHandleOut, MriGeoEntityHandle *pParentHandleOut)

Gets the handle and the parent of an entity, given its name.

MriGeoPluginResult GetEntityHandleFromNameKey(const char *pName,
                                              MriGeoEntityHandle *pHandleOut,
                                              MriGeoEntityHandle *pParentHandleOut); 

pName The name of the entity that we are looking information for. This may be any valid string, but the pointer must not be NULL.

Param pHandleOut:: Receives the handle of the entity, whose name matches the input name. The pointer can be NULL if no matching entity is found.
Param pParentHandleOut:: Receives the handle of the parent of the entity, whose name matches the input name. The pointer can be NULL if no matching entity is found or the matching entity has no parent.

typedef MriGeoPluginResult (*MriGeoReaderGetEntityTypeFunc)(MriGeoEntityHandle Entity, MriSceneEntityType *pTypeOut)

Gets the type of an entity.

MriGeoPluginResult getEntityName(MriGeoEntityHandle Entity,
                                 MriSceneEntityType* pTypeOut); 

Param Entity:: The entity to get the type for. This may be the handle to an entity that was provided to the load() function, or a child entity created with createChildGeoEntity() or createChildEntity().
Param pTypeOut:: The type of the entity. This will be either MRI_SET_ENTITY for an Entity or MRI_SET_GEOENTITY for a GeoEntity.

typedef MriGeoPluginResult (*MriGeoReaderSetEntityNameFunc)(MriGeoEntityHandle Entity, const char *pName)

Sets the name of an entity.

MriGeoPluginResult setEntityName(MriGeoEntityHandle Entity,
                                 const char *pName); 

Param Entity:: The entity to set the name for. This may be the handle to an entity that was provided to the load() function, or a child entity created with createChildGeoEntity() or createChildEntity().
Param pName:: The new name. This may be any valid string, but the pointer must not be NULL.

typedef MriGeoPluginResult (*MriGeoReaderSetEntityTypeFunc)(MriGeoEntityHandle Entity, MriSceneEntityType pType)

Sets the type of an entity.

MriGeoPluginResult setEntityType(MriGeoEntityHandle Entity,
                                 MriSceneEntityType pType); 

Param Entity:: The entity to set the type for. This may be the handle to an entity that was provided to the load() function, or a child entity created with createChildGeoEntity() or createChildEntity().
Param pType:: The entity type. This can be either MRI_SET_ENTITY for an Entity or MRI_SET_GEOENTITY for a GeoEntity.

typedef MriGeoPluginResult (*MriGeoReaderSetGeoDataForFrameFunc)(MriGeoEntityHandle Entity, MriGeoDataHandle ExistingData, int Frame, const void *pNewData, long long DataSizeBytes)

Sets new geometry data for a given frame.

MriGeoPluginResult setGeoDataForFrame(MriGeoEntityHandle Entity,
                                      MriGeoDataHandle ExistingData, int Frame,
                                      const void *pNewData, long long DataSizeBytes); 

Use this function to set up animated geometry.

This must be applied to existing geometry data. The initial data will be used for frame zero. The new data must have the same format and role as the existing data. However, there is no requirement to call this function at any particular time; for example, it may be called before or after adding the data to an object.

Any combination of the geometry data for an object may be animated or not. When an object does not contain animated data for a given role, the same data will be used for all frames.

The data for each frame must contain a matching number of elements. For example, an object with six vertices and six normals on frame zero could provide twelve vertices and twelve normals on another frame, but if that other frame instead provided only vertices, it must provide six, to match the number of normals that were provided for all frames.

Data provided to this function will be copied by Mari, so there is no need to maintain the buffer after the call returns.

Param Entity:: The entity to create data for, as provided to the load() function. This provides a context for the operation.
Param Frame:: The frame to set data for, which must not be negative. The data that was set in the call to createGeoData() will apply to frame zero.
Param ExistingData:: The existing geometry data object created with createGeoData().
Param pNewData:: The new data to add (by copy) to the existing data for the new frame. This must be in the same format as the original data. It may contain a different number of elements to the original data, subject to the restrictions above.
Param DataSizeBytes:: The number of bytes of data to copy. This must be a multiple of the number of bytes of data used by each element. For example, buffers of vertex data must be a multiple of 12 bytes long, as each vertex will take up three floats.
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderSetGeoEntityTransformFunc)(MriGeoEntityHandle Entity, const double *pTransformationMatrix)

Sets the transformation matrix of an entity relative to its parent.

MriGeoPluginResult setGeoEntityTransform(MriGeoEntityHandle Entity,
                                         const float *pTransformationMatrix); 

Each entity’s transform defaults to the identity matrix.

Param Entity:: The entity to set the transformation for. This may be the handle to an entity that was provided to the load() function, or a child entity created with createChildGeoEntity() or createChildEntity().
Param pTransformationMatrix:: A 4x4 transformation matrix, stored as a contiguous 1D array of 16 values

typedef MriGeoPluginResult (*MriGeoReaderSetSubdivisionOnMeshObjectFunc)(MriGeoEntityHandle Entity, MriGeoObjectHandle Object, const char *subdivisionScheme, int interpolateBoundary, int faceVaryingLinearInterpolation, int propagateCorner)

Sets open subdivision properties for this GeoObject.

MriGeoPluginResult setSubdivisionOnMeshObject(MriGeoEntityHandle Entity,
                                              MriGeoObjectHandle Object,
                                              const char *subdivisionScheme,
                                              int interpolateBoundary,
                                              int faceVaryingLinearInterpolation,
                                              int propagateCorner); 

The various properties are standard OpenSubdiv ones. Please refer to the OpenSubdiv documentation: http://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html

See also

createSelectionGroup()

Param Entity:: The entity that the object belongs to
Param Object:: The object that is subdivideable
Param subdivisionScheme:: Subdivision scheme.
Param interpolateBoundary:: Boundary interpolation rule.
Param faceVaryingLinearInterpolation:: Face varying interpolation rule.
Param propagateCorner:: 0 (Corners Plus 1) or 1 (Corners Plus 2).
Return:: The success state of the function

typedef MriGeoPluginResult (*MriGeoReaderSetSubdivisionOnMeshObjectFuncV6)(MriGeoEntityHandle Entity, MriGeoObjectHandle Object, const char *subdivisionScheme, int interpolateBoundary, int faceVaryingLinearInterpolation, int propagateCorner, int triangleSubdivision)

Sets open subdivision properties for this GeoObject.

MriGeoPluginResult setSubdivisionOnMeshObject(MriGeoEntityHandle Entity,
                                              MriGeoObjectHandle Object,
                                              const char *subdivisionScheme,
                                              int interpolateBoundary,
                                              int faceVaryingLinearInterpolation,
                                              int propagateCorner,
                                              int triangleSubdivision); 

The various properties are standard OpenSubdiv ones. Please refer to the OpenSubdiv documentation: http://graphics.pixar.com/opensubdiv/docs/subdivision_surfaces.html

See also

createSelectionGroup()

Param Entity:: The entity that the object belongs to
Param Object:: The object that is subdivideable
Param subdivisionScheme:: Subdivision scheme.
Param interpolateBoundary:: Boundary interpolation rule.
Param faceVaryingLinearInterpolation:: Face varying interpolation rule.
Param propagateCorner:: 0 (Corners Plus 1) or 1 (Corners Plus 2).
Param triangleSubdivision:: 0 (Catmull-Clark) or 2 (Smooth).
Return:: The success state of the function

struct MriGeoReaderHostV1

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV2

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV3

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV4

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV5

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV6

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

struct MriGeoReaderHostV7

#include <MriGeoReaderPlugin.h>

An interface of host functions supplied by Mari for geometry reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Image I/O

group Image I/O

These types are used by both image reader and writer plug-ins.

Typedefs

typedef MriUserItemHandle MriImageHandle: Provides a reference to an image read or write operation.

Enums

enum MriImageDataFormat

Formats for image data.

Values:

enumerator MRI_IDF_UNKNOWN = -1: Invalid format.

enumerator MRI_IDF_BYTE_RGB = 0: 8 bit RGB data

enumerator MRI_IDF_BYTE_RGBA = 1: 8 bit RGBA data

enumerator MRI_IDF_HALF_RGB = 2: 16 bit RGB data

enumerator MRI_IDF_HALF_RGBA = 3: 16 bit RGBA data

enumerator MRI_IDF_FLOAT_RGB = 4: 32 bit RGB data

enumerator MRI_IDF_FLOAT_RGBA = 5: 32 bit RGBA data

enum MriImagePluginResult

Return values from image plug-in and host functions.

Values:

enumerator MRI_IPR_SUCCEEDED = 0: The operation completed successfully.

enumerator MRI_IPR_FAILED = 1: The operation failed in a general or unspecified way.

enumerator MRI_IPR_NOT_SUPPORTED = 2: The operation is not supported on this data type.

enumerator MRI_IPR_INVALID_HANDLE = 3: An invalid handle was supplied.

enumerator MRI_IPR_NOT_CREATED = 4: The image must be created before calling this operation.

enumerator MRI_IPR_ALREADY_CREATED = 5: The image cannot be created twice.

enumerator MRI_IPR_DATA_SIZE_MISMATCH = 6: The supplied data size does not match the size that the function expected to receive.

enumerator MRI_IPR_TILE_OUT_OF_RANGE = 7: The indicated tile does not exist.

enumerator MRI_IPR_INVALID_POINTER = 8: An invalid (NULL) pointer was supplied.

enumerator MRI_IPR_INVALID_TILE = 9: An invalid tile was specified.

enumerator MRI_IPR_INVALID_SIZE = 10: An image with the given size cannot be created (such as zero or negative)

enumerator MRI_IPR_MIPMAP_OUT_OF_RANGE = 11: The specified mip-map level is out of range.

struct MriImageMipMapInfo: #include <MriImagePluginCommon.h>

Properties of a single mip-map level within an image.

Image Info API

group Image Info API

This API allows access to Mari images (image manager and channel/layer tiles).

Defines

MRI_IMAGEINFO_API_NAME "MriImageInfo": Use this in plug-in structure definitions to provide the string identifier of the image info API.

MRI_IMAGEINFO_API_VERSION 1001

Use this in plug-in structure definitions to provide the integer version of the image info API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Image Info Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all image info plug-ins.

The plugin must implement getImageInfo(), given an image uuid, to get metadata about an image, such as its width, height, mip map levels data and image data type.

Typedefs

typedef MriImagePluginResult (*MriImageInfoGetImageInfoFunc)(MriImageHandle ImageHandle, const char *ImageUuid, int *ImageWidth, int *ImageHeight, int *IsUniformColor, const char **OutColor, MriImageDataFormat *DataFormat, int *MipMapLevels, int *TileWidth, int *TileHeight, MriImageMipMapInfo *MipMapInfo, char **OutColorSpace, int *OutColourProfileCount, char ***OutColourProfileList)

Queries an image for its metadata.

MriImagePluginResult getImageInfo(MriImageHandle ImageHandle,
                                    const char* ImageUuid,
                                    int * ImageWidth,
                                    int * ImageHeight,
                                    int * IsUniformColor,
                                    const char* * OutColor,
                                    MriImageDataFormat * DataFormat,
                                    int * MipMapLevels,
                                    int * TileWidth,
                                    int * TileHeight,
                                    MriImageMipMapInfo * MipMapInfo,
                                    char** OutColorSpace,
                                    int* OutColourProfileCount,
                                    char*** OutColourProfileList); 

The Image must exist and be loaded within the current Mari project, otherwise an error is returned.

Param ImageHandle:: The image handle, for which image we want to query.
Param ImageUuid:: The uuid of the image to query.
Param ImageWidth:: The width of the image.
Param ImageHeight:: The height of the image.
Param IsUniformColor:: Flag to indicate whether the image is of uniform color.
Param OutColor:: The uniform color of the image.
Param DataFormat:: The image data format.
Param MipMapLevels:: The number of mip map levels in the image.
Param TileWidth:: The width of a tile in the image.
Param TileHeight:: The height of a tile in the image.
Param MipMapInfo:: Information about mip map levels in the image.
Param OutColorSpace:: The colorspace of the image.
Param OutColourProfileCount:: The count of color profiles for the image.
Param OutColourProfileList:: The list of color profiles for the image.
Return:: The success state of the function

struct MriImageInfoPluginV1

#include <MriImageInfoPlugin.h>

The user plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Image Info Host Definitions

group Host Definitions

This functionality is provided by the image info plug-in host.

These functions are used to query an image in Mari (from the image manager or a tile from a channel/layer) and its properties, such as:

its mip map info
the image resolution (width and height).
details about a specific tile.
the format of the image data
whether the image is of uniform color.

Typedefs

typedef MriImagePluginResult (*MriImageInfoGetColourProfilesFunc)(MriImageHandle ImageHandle, char **OutColorSpace, int *OutColourProfileCount, char ***OutColourProfileList)

Queries the color profiles of an image.

MriImagePluginResult getColourProfiles(MriImageHandle ImageHandle, char** OutColorSpace, int* OutColourProfileCount, char *** OutColourProfileList); 

Returns the color profiles of an image and its default colorspace.

Param ImageHandle:: The image handle, for which image we want to query.
Param OutColorSpace:: The default colorspace of the image.
Param OutColourProfileCount:: The count of color profiles available for that image.
Param OutColourProfileList:: An array of the color profile names.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageInfoGetDataFormatFunc)(MriImageHandle ImageHandle, MriImageDataFormat *OutDataFormat)

Queries the data format of an image.

MriImagePluginResult getDataFormat(MriImageHandle ImageHandle, MriImageDataFormat* OutDataFormat); 

Returns the format of the data in the image, i.e., data type and the number of channels.

Param ImageHandle:: The image handle, for which image we want to query.
Param OutDataFormat:: The data format of the image.
Return:: The success state of the function

typedef void (*MriImageInfoGetImageHandleFunc)(MriImageHandle *OutImageHandle)

Creates an image handle, that can be used to refer to an image in the api world.

void getImageHandle(MriImageHandle* OutImageHandle); 

Creates an image handle.

Param OutImageHandle:: The newly-created image handle.

typedef MriImagePluginResult (*MriImageInfoGetMipMapInfoFunc)(MriImageHandle ImageHandle, int MipMapLevel, MriImageMipMapInfo *OutMipMapInfo)

Queries an image for its mip map details, given a mip map level.

MriImagePluginResult getMipMapInfo(MriImageHandle ImageHandle, int MipMapLevel, MriImageMipMapInfo* OutMipMapInfo); 

The GeoEntity must exist and be loaded within the current Mari project, otherwise an error is returned.

Param ImageHandle:: The image handle, for which image we want to query.
Param MipMapLevel:: The mip map level for which we need mip map info
Param OutMipMapInfo:: The mip map info structure.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageInfoGetSizeFunc)(MriImageHandle ImageHandle, int *OutWidth, int *OutHeight)

Gets the size of an image.

MriImagePluginResult getImageSize(MriImageHandle ImageHandle, int* OutWidth, int* OutHeight); 

Returns the width and height of the image.

Param ImageHandle:: The image handle, for which image we want to query.
Param OutWidth:: The width of the image.
Param OutHeight:: The height of the image.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageInfoGetTileInfoFunc)(MriImageHandle ImageHandle, int *OutMipMapLevels, int *OutTileWidth, int *OutTileHeight)

Gets the tile information for an image.

MriImagePluginResult getTileInfo(MriImageHandle ImageHandle, int* OutMipMapLevel, int* OutTileWidth, int* OutTileHeight); 

Returns the number of mip map levels and a tile’s width and height, for an image.

Param ImageHandle:: The image handle, for which image we want to query.
Param OutMipMapLevels:: The number of mip map levels of the image.
Param OutTileWidth:: The width of a tile in the image.
Param OutTileHeight:: The height of a tile in the image.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageInfoGetUniformColorInfoFunc)(MriImageHandle ImageHandle, int *OutIsUniformColor, const char **OutColor)

Queries an image for whether it is of uniform color.

MriImagePluginResult getUniformColorInfo(MriImageHandle ImageHandle, int* OutIsUniformColor, const char** OutColor); 

Returns whether an image is of uniform color and the color.

Param ImageHandle:: The image handle, for which image we want to query.
Param OutIsUniformColor:: Flag to indicate whether the image is of uniform color.
Param OutColor:: The colour of the image.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageInfoLoadImageFromUuidFunc)(MriImageHandle ImageHandle, const char *ImageUuid)

This locates the required Image in Mari, given a uuid and associates it with a handle, so that it can be referenced later easily.

MriImagePluginResult loadImageFromUuid(MriImageHandle ImageHandle, const char* ImageUuid); 

The GeoEntity must exist and be loaded within the current Mari project, otherwise an error is returned.

Param ImageHandle:: The handle that is associated with the image and used as a token to access that image throughout the Api.
Param ImageUuid:: The uuid of the image required.
Return:: The success state of the function

typedef void (*MriImageInfoReleaseImageHandleFunc)(MriImageHandle *OutImageHandle)

Releases an image handle.

void releaseImageHandle(MriImageHandle* OutImageHandle); 

Used to release an image handle and clean up memory safely. This needs to go hand-in-hand with getImageHandle().

Param OutImageHandle:: The newly-created image handle.

struct MriImageInfoHostV1

#include <MriImageInfoPlugin.h>

An interface of host functions supplied by Mari for image info plug-in to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Image Reader API

group Image Reader API

This API allows Mari to load from custom image formats.

Defines

MRI_IMAGE_READER_API_NAME "MriImageReader": Use this in plug-in structure definitions to provide the string identifier of the image reader API.

MRI_IMAGE_READER_API_VERSION 1007

Use this in plug-in structure definitions to provide the integer version of the image reader API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Image Reader Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all image reader plug-ins.

The host will check the formats supported by the image reader using the supportedFormats() function. When an image of a custom type supported by a plug-in is to be read, the host will call the plug-in’s load() function with appropriate parameters.

To create and store the loaded image data, plug-ins should call appropriate functions on the host, such as createImage() and storeTile().

Typedefs

typedef MriImagePluginResult (*MriImageReaderImageDataFormatFunc)(const char *FileName, MriImageDataFormat *OutFormat)

Returns the image data format of a given file name.

MriImagePluginResult imageDataFormat(const char *FileName, MriImageDataFormat *OutFormat); 

Mari needs the image data format of a given file format at various places to resolve color space and etc.

Param FileName:: The name of the file to query, with full path. This will match one of the formats supported by the plug-in.
Param OutFormat:: The image data format, of the input file.
Return:: The success state of the function

typedef MriImagePluginResult (*MriImageReaderLoadFunc)(MriImageHandle ImageHandle, const char *pFileName, const char **ppMessageStringOut)

Loads an image of a custom format.

MriImagePluginResult load(MriImageHandle ImageHandle, const char *pFileName,
                          const char **ppMessageStringOut, MriImageReaderLoadFlags Flags); 

Warning and error messages for the loading operation can be provided using ppMessageStringOut. To supply multiple messages, separate each with a new line character (‘\n’). Each message will have the file name prepended, except if it starts with a colon (‘:’). ppMessageStringOut may be left as NULL (as it is when passed in) to indicate that there are no messages to display.

Any attributes set on ImageHandle after a successful return from this function will be added to the loaded image as metadata. See setAttribute() for details. Please note though that string lists are not supported as metadata, and will be stored as strings instead.

Param ImageHandle:: This provides a reference to the individual image loading operation, and should be passed into all related host functions.
Param pFileName:: The name of the file to load, with full path. This will match one of the formats supported by the plug-in.
Param ppMessageStringOut:: Set this to a string containing warning or error messages if desired. (See above)
Return:: The success state of the function

struct MriImageReaderPluginV1

#include <MriImageReaderPlugin.h>

Image reader plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

struct MriImageReaderPluginV2

#include <MriImageReaderPlugin.h>

Image reader plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Image Reader Host Definitions

group Host Definitions

This functionality is provided by the image reader plug-in host.

All of the data passed to these functions will be copied by Mari, so there is no need to maintain the buffers after the calls return.

Typedefs

typedef MriImagePluginResult (*MriImageReaderCreateImageFunc)(MriImageHandle ImageHandle, int Width, int Height, MriImageDataFormat Format, int *pNumMipMapLevelsOut, int *pTileWidthOut, int *pTileHeightOut)

Creates a new image of dimensions Width x Height.

MriImagePluginResult createImage(MriImageHandle ImageHandle, int Width, int Height,
                                 MriImageDataFormat Format, int *pOutNumMipMapLevels,
                                 int *pOutTileWidth, int *pOutTileHeight); 

All tiles in the image must be set using storeTile() for the image load to complete successfully. However, it is only necessary to do this for the top mip-map level.

If only the tiles on the top mip-map level are set, Mari will generate all of the lower mip-map level data automatically, using its standard downsampling method. To instead set the rest of this data yourself, call storeTile() for each of the tiles at each mip-map level.

See Mari Project Structure for a description of how Mari uses tiles.

Param ImageHandle:: The handle provided to the load() function
Param Width:: The width of the image to create, in pixels
Param Height:: The height of the image to create, in pixels
Param Format:: Specifies the data size (byte, half, float) and components (RGB, RGBA) of the image to create
Param pNumMipMapLevelsOut:: Receives the number of mip-map levels in the image. The pointer may be NULL if the value is not required, such as if the user will only set the top mip-map level (0) and leave the rest to be automatically generated.
Param pTileWidthOut:: Receives the width of each tile in the image, in pixels. This will be either 256 or the entire width of the image, and the same width will apply to any lower mip-map levels. The pointer must not be NULL, as the value will always be required.
Param pTileHeightOut:: Receives the height of each tile in the image, in pixels. This will be either 256 or the entire height of the image, and the same height will apply to any lower mip-map levels. The pointer must not be NULL, as the value will always be required.
Return:: The success state of the function. On failure, there is no need to set an additional error message.

typedef MriImagePluginResult (*MriImageReaderGetMipMapInfoFunc)(MriImageHandle ImageHandle, int MipMapLevel, MriImageMipMapInfo *pInfo)

Returns the properties of a given mip-map level in the current image.

MriImagePluginResult getMipMapInfo(MriImageHandle ImageHandle, int MipMapLevel,
                                   MriImageMipMapInfo *pInfo); 

Param ImageHandle:: The handle provided to the load() function
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pInfo:: Receives the info for the mip-map level. The pointer must not be NULL.

typedef void (*MriImageReaderSetProgressFunc)(int Percentage)

Sets the percentage of progress for the current operation.

void setProgress(int Percentage); 

The progress will be displayed on the status bar or image import dialog, as appropriate for the type of operation.

Param Percentage:: The percentage of progress for the current operation. This will be clamped to the range [0, 100].

typedef MriImagePluginResult (*MriImageReaderStoreTileFunc)(MriImageHandle ImageHandle, int XIndex, int YIndex, int MipMapLevel, const void *pData, long long DataSizeBytes)

Stores the given data into the tile in the current image with the given indices.

MriImagePluginResult storeTile(MriImageHandle ImageHandle, int XIndex, int YIndex,
                               int MipMapLevel, const void *pData, long long DataSizeBytes); 

All tiles in the image must be set for the image load to complete successfully. However, it is only necessary to do this for the top mip-map level.

If only the tiles on the top mip-map level are set, Mari will generate all of the lower mip-map level data automatically, using its standard downsampling method. To instead set the rest of this data yourself, call this function for each of the tiles at each mip-map level.

See Mari Project Structure for a description of how Mari uses tiles.

Param ImageHandle:: The handle provided to the load() function
Param XIndex:: Horizontal tile index, in the range [0, num tiles across - 1]
Param YIndex:: Vertical tile index, in the range [0, num tiles down - 1]
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pData:: Image data of the correct format and size to fill a tile
Param DataSizeBytes:: Length of the data provided for the tile, in bytes. This must exactly match the expected data size
Return:: The success state of the function

struct MriImageReaderHostV1

#include <MriImageReaderPlugin.h>

An interface of host functions supplied by Mari for image reader plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Image Writer API

group Image Writer API

This API allows Mari to save in custom image formats.

Defines

MRI_IMAGE_WRITER_API_NAME "MriImageWriter": Use this in plug-in structure definitions to provide the string identifier of the image writer API.

MRI_IMAGE_WRITER_API_VERSION 1005

Use this in plug-in structure definitions to provide the integer version of the image writer API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Image Writer Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all image writer plug-ins.

The host will check the formats supported by the image writer using the supportedFormats() and supportedImageFormats() functions. When an image of a custom type supported by a plug-in is to be written, the host will call the plug-in’s save() function with appropriate parameters.

To retrieve the image data to save, plug-ins should call appropriate functions on the host, such as loadTile().

Typedefs

typedef MriImagePluginResult (*MriImageWriterSaveFunc)(MriImageHandle ImageHandle, const char *pFileName, const char **ppMessageStringOut, MriImageDataFormat Format, int NumMipMapLevels, int TileWidth, int TileHeight)

Saves an image in a custom format.

MriImagePluginResult save(MriImageHandle ImageHandle, const char *pFileName,
                          const char **ppMessageStringOut, MriImageDataFormat Format,
                          int NumMipMapLevels, int TileWidth, int TileHeight); 

Warning and error messages for the loading operation can be provided using ppMessageStringOut. To supply multiple messages, separate each with a new line character (‘\n’). Each message will have the file name prepended, except if it starts with a colon (‘:’). ppMessageStringOut may be left as NULL (as it is when passed in) to indicate that there are no messages to display.

Param ImageHandle:: This provides a reference to the individual image saving operation, and should be passed into all related host functions.
Param pFileName:: The name of the file to save, with full path. This will match one of the formats supported by the plug-in.
Param ppMessageStringOut:: Set this to a string containing warning or error messages if desired. (See above)
Param Format:: The data format of the image being saved, which specifies its channels (RGB or RGBA) and bit depth
Param NumMipMapLevels:: The number of available mip-map levels of the image. When the image’s tile size is not 256x256, it will be stored in a single tile of dimensions matching the entire image, and only one mip-map level will be available.
Param TileWidth:: The width of each tile. In general, this will be either 256 (the width of an internal tile) or the entire width of the image.
Param TileHeight:: The height of each tile. In general, this will be either 256 (the height of an internal tile) or the entire height of the image.

typedef MriImageDataFormat *(*MriImageWriterSupportedImageFormatsFunc)(const char *pExtension, int *pNumFormatsOut)

Returns a pointer to information about the image formats supported by the plug-in.

MriImageDataFormat *supportedImageFormats(const char *pExtension, int *pNumFormatsOut); 

Param pNumFormatsOut:: Receives the number of supported formats. The pointer will not be NULL.

struct MriImageWriterPluginV1

#include <MriImageWriterPlugin.h>

Image writer plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Image Writer Host Definitions

group Host Definitions

This functionality is provided by the image writer plug-in host.

Typedefs

typedef MriImagePluginResult (*MriImageWriterGetMipMapInfoFunc)(MriImageHandle ImageHandle, int MipMapLevel, MriImageMipMapInfo *pInfo)

Returns the properties of a given mip-map level in the current image.

MriImagePluginResult getMipMapInfo(MriImageHandle ImageHandle, int MipMapLevel,
                                   MriImageMipMapInfo *pInfo); 

Param ImageHandle:: The handle provided to the save() function
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pInfo:: Receives the info for the mip-map level. The pointer must not be NULL.

typedef MriImagePluginResult (*MriImageWriterGetTileHashFunc)(MriImageHandle ImageHandle, int XIndex, int YIndex, int MipMapLevel, char *pHash, int HashSize)

Returns the data hash string for a given tile in the current image with the given indices.

MriImagePluginResult getTileHash(MriImageHandle Handle, int XIndex, int YIndex, char *pHash,
                                 int HashSize); 

Param ImageHandle:: The handle provided to the save() function
Param XIndex:: Horizontal tile index, in the range [0, num tiles across - 1]
Param YIndex:: Vertical tile index, in the range [0, num tiles down - 1]
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pHash:: Buffer to receive the data from the hash string
Param HashSize:: The expected number of chars to receive from the tile hash. This must exactly match the amount of characters in the data hash string, including the null terminator character.

typedef MriImagePluginResult (*MriImageWriterGetTileHashSizeFunc)(MriImageHandle ImageHandle, int XIndex, int YIndex, int MipMapLevel, int *pHashSize)

Returns the length of the data hash string for a given tile in the current image.

MriImagePluginResult getTileHashSize(MriImageHandle Handle, int XIndex, int YIndex,
                                     int *pHashSize); 

Param ImageHandle:: The handle provided to the save() function
Param XIndex:: Horizontal tile index, in the range [0, num tiles across - 1]
Param YIndex:: Vertical tile index, in the range [0, num tiles down - 1]
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pHashSize:: Length of data hash string in chars. This includes the null terminator character.

typedef MriImagePluginResult (*MriImageWriterLoadTileFunc)(MriImageHandle ImageHandle, int XIndex, int YIndex, int MipMapLevel, void *pData, long long DataSizeBytes)

Loads data from the tile in the current image with the given indices.

MriImagePluginResult loadTile(MriImageHandle Handle, int XIndex, int YIndex,
                              int MipMapLevel, void *pData, long long DataSizeBytes); 

See Mari Project Structure for a description of how Mari uses tiles.

Param ImageHandle:: The handle provided to the save() function
Param XIndex:: Horizontal tile index, in the range [0, num tiles across - 1]
Param YIndex:: Vertical tile index, in the range [0, num tiles down - 1]
Param MipMapLevel:: Mip-map level index, in the range [0, num mip-map levels - 1]
Param pData:: The address of a buffer that is at least DataSizeBytes long that will receive the image data from the tile
Param DataSizeBytes:: The expected number of data bytes to receive from the tile. This must exactly match the amount of image data in the tile.

struct MriImageWriterHostV1

#include <MriImageWriterPlugin.h>

An interface of host functions supplied by Mari for image writer plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Texture Access API

group Texture Access API

This API allows access to Mari texture data.

Unnamed Group

typedef MriImagePluginResult (*MriTextureGetReadPixelBlockFunc)(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest *PixelBlockRequest)

This gets the texture block, as per the request structure, and associates it with the input handle in read-only mode.

The texture data is read using readPixelBlockData(); the latter returns a void pointer and the size of the data. We need to get the format of the iamge data using getDataFormat(), so as to be able to cast the void pointer to the correct data. Note that it’s vital to check that the size of the data is not zero, before starting to read the data.

MriImagePluginResult getReadPixelBlock(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest* PixelBlockInfo); 

The request structure specifies the image uuid we are looking for as well as mip map info and color-space required. The pixel block handle is associated with the texture block in write mode and can be used throughout the plugin to access texture data.

Note that we NEED to use releasePixelBlock() when we are finished with the texture data, so that the texture data is cleaned up properly in memory.

Param PixelBlockHandle:: The handle that is associated with the texture and used throughout the api to reference it.
Param PixelBlockRequest:: The request structure, specifying what texture block to query.
Return:: The success state of the function

typedef MriImagePluginResult (*MriTextureGetWritePixelBlockFunc)(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest *PixelBlockRequest)

This gets the texture block, as per the request structure, and associates it with the input handle in write mode.

MriImagePluginResult getWritePixelBlock(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest* PixelBlockInfo); 

The request structure specifies the image uuid we are looking for as well as mip map info and color-space required. The pixel block handle is associated with the texture block in read-only mode and can be used throughout the plugin to access texture data.

Note that we NEED to use setAndReleasePixelBlock() when we are finished with the texture data, so that any changes made to the latter will be saved out and the memory is cleaned up nicely.

Param PixelBlockHandle:: The handle that is associated with the texture and used throughout the api to reference it.
Param PixelBlockRequest:: The request structure, specifying what texture block to query.
Return:: The success state of the function

typedef MriImagePluginResult (*MriTextureReleasePixelBlockFunc)(MriPixelBlockHandle PixelBlockHandle)

This function releases a read-only texture block and clean up any reference to the latter as well as its memory.

MriImagePluginResult releasePixelBlock(MriPixelBlockHandle PixelBlockHandle); 

This step is VITAL, once we’re finished reading the texture data, so that the handle is discarded properly and its associated texture data is removed from memory properly.

Param PixelBlockHandle:: The texture handle of the pixel block to release.
Return:: The success state of the function

typedef MriImagePluginResult (*MriTextureSetAndReleasePixelBlockFunc)(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest *PixelBlockRequest)

This function releases a write texture block, saves it to Mari’s DDI and clean up any reference to the latter as well as its memory.

MriImagePluginResult setAndReleasePixelBlock(MriPixelBlockHandle PixelBlockHandle); 

This step is VITAL, once we’re finished writing to a texture data, so that the changes are made persistent in the disk cache and the handle is discarded properly and its associated texture data is removed from memory properly.

Param PixelBlockHandle:: The texture handle of the pixel block to release.
Return:: The success state of the function

typedef MriImagePluginResult (*MriTextureReadPixelBlockDataFunc)(MriPixelBlockHandle PixelBlockHandle, size_t *BlockSize, void **OutData)

Reads the texture data.

MriImagePluginResult readPixelBlockData(MriPixelBlockHandle PixelBlockHandle, size_t* BlockSize, void** OutData); 

This function returns the texture data, from a texture block, as well as its size, in bytes. The data is returned as a void pointer and needs to be converted back to its proper data format when we read it later on.

Please ensure that all the handles, associated with texture blocks, are released properly once we are finished with the texture block, by using either releasePixelBlock(), if we requested a read pixel block through getReadPixelBlock(), or setAndReleasePixelBlock(), if we requested a write pixel block through getWritePixelBlock().

Param PixelBlockHandle:: The texture handle to query data for.
Param BlockSize:: The size, in bytes, of the texture data.
Param OutData:: The texture data.
Return:: The success state of the function

typedef int (*MriTextureCheckIfPixelHandleIsValidFunc)(MriPixelBlockHandle PixelBlockHandle)

Checks whether a texture handle is still associated to a texture block.

int isPixelHandleValid(MriPixelBlockHandle PixelBlockHandle); 

This function checks whether a handle is still in use and associated to a texture block. It is vital that this is NOT the case, once we’ve released a texture block, otherwise the Mari project will contain live hashes and cause the application to crash should we try to close the latter.

Please ensure that all the handles, associated with texture blocks, are released properly once we are finished with the texture block, by using either releasePixelBlock(), if we requested a read pixel block through getReadPixelBlock(), or setAndReleasePixelBlock(), if we requested a write pixel block through getWritePixelBlock().

Param PixelBlockHandle:: The handle to check.
Return:: The success state of the function

typedef MriImagePluginResult (*MriTextureUpdateImageMipmapLevelsFunc)(const char *ImageUuid)

This updates all the mip map levels in an image, once we updated a texture block.

MriImagePluginResult updateImageMipmapLevels(const char* ImageUuid); 

We need to update all the other mip map levels of an image, once we’ve made some change to one of its tile/texture block; otherwise, we wouldnt see the change propagated to the other mip map levels.

Param ImageUuid:: The image uuid of the image to update.
Return:: The success state of the function

typedef void (*MriTextureGetPixelBlockHandleFunc)(MriPixelBlockHandle *OutPixelBlockHandle)

This creates a new texture block handle.

void getPixelBlockHandle(MriPixelBlockHandle* OutPixelBlockHandle); 

This creates a handle that can be associated to a texture block.

Param OutPixelBlockHandle:: The newly-created handle.

typedef void (*MriTextureReleasePixelBlockHandleFunc)(MriPixelBlockHandle *OutPixelBlockHandle)

This releases a texture block handle safely and cleans memory after it.

void releasePixelBlockHandle(MriPixelBlockHandle* OutPixelBlockHandle); 

Please note that this only discards the handle and does NOT do anything to its associated pixel block. The latter MUST be released using releasePixelBlock() or setAndReleasePixelBlock().

Param OutPixelBlockHandle:: The handle to be removed.

Defines

MRI_TEXTURE_API_NAME "MriTexturePlugin": Use this in plug-in structure definitions to provide the string identifier of the API.

MRI_TEXTURE_API_VERSION 1001

Use this in plug-in structure definitions to provide the integer version of the API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Typedefs

typedef MriUserItemHandle MriPixelBlockHandle: A handle to a pixel block object.

struct MriPixelBlockRequest: #include <MriTexturePlugin.h>

Properties of a pixel block request.

struct MriPixelBlockSerializable: #include <MriTexturePlugin.h>

Properties of a serializable pixel block request.

struct MriTextureHostV1

#include <MriTexturePlugin.h>

An interface of host functions supplied by Mari for texture writer plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

Texture Access Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all texture plug-ins.

The plugin must implement getPixelBlockData(), to get texture data, given a pixel block request.

Typedefs

typedef MriImagePluginResult (*MriTextureGetPixelBlockDataFunc)(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest *PixelBlockRequest, void **OutData, size_t *OutBlockSize)

Gets texture data for an image tile.

MriImagePluginResult getPixelBlockData(MriPixelBlockHandle PixelBlockHandle,
                                            MriPixelBlockRequest * PixelBlockRequest,
                                            void* * OutData,
                                            size_t * OutBlockSize); 

The Image must exist and be loaded within the current Mari project, otherwise an error is returned.

This function takes in a pixel block request (MriPixelBlockRequest) to locate the requested tile of the image and returns back its data as well as the size, in bytes. We need to cast the data back to the appropriate image data format.

Param PixelBlockHandle:: The hnadle associated with the pixel block.
Param PixelBlockRequest:: The request strucuture, detailing which tile to extract information from and in what format.
Param OutData:: The texture data.
Param OutBlockSize:: The data size in bytes.
Return:: The success state of the function

struct MriTexturePluginV1

#include <MriTexturePlugin.h>

Texture plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

Texture Access Host Definitions

group Host Definitions

This functionality is provided by the texture writer plug-in host. Texture data, in Mari, comes from either an image in the image manager or from a layer; the latter is tiled (each 256 by 256) and contained mip maps, while the former is not tiled.

To shield the user from all the complexity of accessing texture and how it is stored, we use a MriPixelBlockHandle in the api world and associate that with an image uuid. Once associated, we can then only refer to the image using the handle. We also need to pass in a pixel request block when we want to do the association, to specify the mip map level we want texture data from, the tile X and Y coordinates and a color-space in which we want the data to be returned. The host automatically formats the data into the requested color-space and stores the resulting data in an internally managed cache, so that any future access to that texture with that same color-space would bypass the same heavy color-conversion process again.

User Geometry Operation API

group User Geometry Operation API

This API allows registering a geometry operation with Mari.

Defines

MRI_USER_GEOMETRY_OPERATION_API_NAME "MriUserGeometryOperationPlugin": Use this in plug-in structure definitions to provide the string identifier of the API.

MRI_USER_GEOMETRY_OPERATION_API_VERSION 1001

Use this in plug-in structure definitions to provide the integer version of the API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Typedefs

typedef MriUserItemHandle MriGeometryOperationBlockHandle: A handle to a geometry operation.

User Geometry Operation Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all user geometry operation plug-ins.

The plugin needs to implement an execute() function, passing to it handles to geometry and parameters required to implement the operation. This function is the main entry point into the plugin; we pass in parameters, such as the uuids of the geometry and version, so that we could locate the meshes we need to gather data about and lay down logic to manipulate this mesh data (uv, normal, vertices and etc.); the latter could then optionally written out to an output file or fed into a production pipeline.

Please note that the geometries and versions must exist within the current open Mari project, so that we can access them.

Typedefs

typedef MriGeoPluginResult (*MriUserGeometryOperationExecuteFunc)(MriGeometryOperationBlockHandle GeometryOpHandle, const char *Operation, const char *GeoUuid, MriGeoEntityHandle GeoEntityHandle, const char *VersionUuid, int Frame, int QuerySubdivisionMesh, int SubdivisionLevel, int ExtraParameterCount, char **ExtraParameterKeys, char **ExtraParameterValues)

Implements logic to execute an operation on the mesh data of a GeoEntity.

MriGeoPluginResult execute(MriGeometryOperationBlockHandle GeometryOpHandle,
                                const char* Operation,
                                const char* GeoUuid,
                                MriGeoEntityHandle GeoEntityHandle,
                                const char* VersionUuid,
                                int Frame,
                                int QuerySubdivisionMesh,
                                int SubdivisionLevel,
                                int ExtraParameterCount,
                                char** ExtraParameterKeys,
                                char** ExtraParameterValues); 

The GeoEntity and Geo Version must exist and be loaded within the current Mari project, otherwise an error is returned.

We need to pass in geo entity uuid, a version uuid within that geo entity and any extra parameter required so that we can query Mari for mesh data.

Note that we can also pass in extra parameters, to be used to implement the geometry data. This could be a filename, if we want to write data to a file, for example.

To achieve this, we should pass in a list of keys, a list of values and a count of the number of extra parameters we are passing to the execute function.

Param GeometryOpHandle:: The handle that is associated with the operation and used as a token to access this operation throughout the Api.
Param Operation:: The sub-operation to execute; this is declared in the list of supportedFormats().
Param GeoUuid:: The uuid of the geo entity to get geometry data from.
Param GeoEntityHandle:: The handle associated with the geo entity, being queried in the operation.
Param VersionUuid:: The uuid of the version, within the geo entity, to use for getting to mesh data.
Param Frame:: The frame to query for channel data, in case of animation.
Param QuerySubdivisionMesh:: A flag to indicate whether we need to query subdivision meshes from the geo entity, instead of its original (unsubdivided) meshes.
Param SubdivisionLevel:: The level of subdivision, at which we need mesh data.
Param ExtraParameterCount:: The count of extra parameters, being passed to the function.
Param ExtraParameterKeys:: The extra parameter keys.
Param ExtraParameterValues:: The extra parameter values.
Return:: The success state of the function

struct MriUserGeometryOperationPluginV1

#include <MriUserGeometryOperationPlugin.h>

The user plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

User Geometry Operation Host Definitions

group Host Definitions

This functionality is provided by the plug-in host.

The geometry operation plugin doesn’t require anything from the Host; it only need to interface with other plugins (Geometry Access) to get data about geometry.

The host does define a trace() function, though, that can be called from the geometry operation plugin to print out debug messages to the console.

struct MriUserGeometryOperationHostV1

#include <MriUserGeometryOperationPlugin.h>

An interface of host functions supplied by Mari for the user plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

User Image Operation API

group User Image Operation API

This API allows registering an image operation with Mari.

Defines

MRI_USER_IMAGE_OPERATION_API_NAME "MriUserImageOperationPlugin": Use this in plug-in structure definitions to provide the string identifier of the API.

MRI_USER_IMAGE_OPERATION_API_VERSION 1001

Use this in plug-in structure definitions to provide the integer version of the API.

The version is composed of:

external_release_number * 1000 + internal_revision_number 

Typedefs

typedef MriUserItemHandle MriImageOperationBlockHandle: A handle to an image operation.

User Image Operation Plug-in Definitions

group Plug-in Definitions

This functionality must be implemented by all user image operation plug-ins.

The plugin needs to implement an execute() function, passing to it handles to image and parameters required to implement the operation. This function is the main entry point into the plugin; we pass in parameters, such as the uuids of the image, so that we could locate the required channels/images and lay down logic to manipulate the image data/pixels. The latter can then be written back (released) and made persistent.

Please note that the channels/images must exist within the current open Mari project, so that we can access them.

Typedefs

typedef MriImagePluginResult (*MriUserImageOperationExecuteFunc)(MriImageOperationBlockHandle ImageOpHandle, const char *Operation, MriImageHandle ImageHandle, const char *ImageUuid, MriPixelBlockHandle PixelBlockHandle, int ExtraParameterCount, char **ExtraParameterKeys, char **ExtraParameterValues)

Implements logic to query a block of texture data, from an image (texture), get its pixel data, manipulate it (invert the pixel data for example) and write the result back to the channel.

MriImagePluginResult execute(MriImageOperationBlockHandle ImageOpHandle,
                               const char* Operation,
                               MriImageHandle ImageHandle,
                               const char* ImageUuid,
                               MriPixelBlockHandle PixelBlockHandle,
                               int ExtraParameterCount,
                               char** ExtraParameterKeys,
                               char** ExtraParameterValues); 

The image (coming from a channel or image manager) must exist and be loaded within the current Mari project, otherwise an error is returned.

We need to pass in the image’s uuid, its handle and a handle to a pixel block, that is the main texture block storing the read pixel data to be manipulated and written back at the end of the operation.

Note that we can also pass in extra parameters, to be used to implement the operation. This could be a a specific channel that we need to consider when executing an invert operation for example.

To achieve this, we should pass in a list of keys, a list of values and a count of the number of extra parameters we are passing to the execute function.

Param ImageOpHandle:: The handle that is associated with the operation and used as a token to access this operation throughout the Api.
Param Operation:: The sub-operation to execute; this is declared in the list of supportedFormats().
Param ImageHandle:: The handle associated with the image, being queried in the operation.
Param ImageUuid:: The uuid of the image to get texture data from.
Param PixelBlockHandle:: The handle to a pixel block, that is a block of texture data that we are querying and manipulating; this is what we need save (release) at the end of the operation.
Param ExtraParameterCount:: The count of extra parameters, being passed to the function.
Param ExtraParameterKeys:: The extra parameter keys.
Param ExtraParameterValues:: The extra parameter values.
Return:: The success state of the function

struct MriUserImageOperationPluginV1

#include <MriUserImageOperationPlugin.h>

The user plug-ins must implement this suite of functions.

All of these function pointers must be non-NULL for the suite to be considered valid.

See the function pointer type definitions for details of the functions.

User Image Operation Host Definitions

group Host Definitions

This functionality is provided by the plug-in host.

The image operation plugin doesn’t require anything from the Host; it only need to interface with other plugins (Image Info and Texture Access) to get data about texture.

The host does define a trace() function, though, that can be called from the operation plugin to print out debug messages to the console.

struct MriUserImageOperationHostV1

#include <MriUserImageOperationPlugin.h>

An interface of host functions supplied by Mari for the user plug-ins to call.

All of these function pointers will be non-NULL.

See the function pointer type definitions for details of the functions.

File Formats

group File Formats

These allows plug-ins to specify the file extensions that they support.

File formats must be used through one of the main provided APIs.

Typedefs

typedef MriFileFormatDesc *(*MriUserPluginSupportedFormatsFunc)(int *pNumFormatsOut)

Returns a pointer to a structure of information about the file formats supported by the plug-in.

MriFileFormatDesc *supportedFormats(int *pNumFormatsOut); 

Param pNumFormatsOut:: Receives the number of supported formats. The pointer will not be NULL.

struct MriFileFormatDesc: #include <MriUserPluginCommon.h>

Specifies the extension of, and description for, a file format.

Attributes

group Attributes

Attributes provide a simple mechanism for passing general properties between the plug-in and host.

These can be used as settings for loading or saving, metadata to store on loaded objects, or otherwise.

Attributes must be used through one of the main provided APIs.

Typedefs

typedef MriUserPluginResult (*MriUserPluginGetAttributeFunc)(MriUserItemHandle Item, const char *pName, MriAttributeValue *pValueOut)

Retrieves the value of an attribute.

MriUserPluginResult getAttribute(MriUserItemHandle Item, const char *pName,
                                 MriImageAttribute *pValueOut); 

All string data is managed internally, so there is no need to free any returned pointers.

Param Item:: The item currently being referenced by the plug-in, such as an image or geometry handle
Param pName:: The name of the attribute to retrieve
Param pValueOut:: Receives the value of the attribute if successful. This must not be NULL.
Return:: The success state of the function

typedef MriUserPluginResult (*MriUserPluginListAttributesFunc)(MriUserItemHandle Item, const char *const **pppNamesOut, int *pNumNamesOut)

Returns a list of the attributes available for the given item.

MriUserPluginResult listAttributes(MriUserItemHandle Item, const char * const **pppNamesOut,
                                   int *pNumNamesOut); 

All string data is managed internally, so there is no need to free any returned pointers.

Param Item:: The item currently being referenced by the plug-in, such as an image or geometry handle
Param pppNamesOut:: Receives a pointer to an array of attribute names. This memory is valid up until the next call of listAttributes() for this attribute group. The pointer must not be NULL.
Param pNumNamesOut:: Receives the number of attribute names. This must not be NULL.
Return:: The success state of the function

typedef MriUserPluginResult (*MriUserPluginRemoveAttributeFunc)(MriUserItemHandle Item, const char *pName)

Removes an existing attribute.

MriUserPluginResult removeAttribute(MriUserItemHandle Item, const char *pName); 

Return:: The success state of the function

typedef MriUserPluginResult (*MriUserPluginSetAttributeFunc)(MriUserItemHandle Item, const char *pName, const MriAttributeValue *pNewValue)

Sets the value of a new or existing attribute.

MriUserPluginResult setAttribute(MriUserItemHandle Item, const char *pName,
                                 const MriImageAttribute *pNewValue); 

All required data is copied, including string characters, so there is no need to keep source data valid after calling this function.

Param Item:: The item currently being referenced by the plug-in, such as an image or geometry handle
Param pName:: The name of the attribute to set
Param pNewValue:: The value of the attribute to set. This must not be NULL.
Return:: The success state of the function

Enums

enum MriAttributeType

Describes the type of an attribute, and how its data is stored.

Values:

enumerator MRI_ATTR_NULL = 0: An empty or invalid value.

enumerator MRI_ATTR_BOOL = 1: A true or false value, with non-zero or zero stored in m_Int.

enumerator MRI_ATTR_INT = 2: An integer value, with data stored in m_Int.

enumerator MRI_ATTR_DOUBLE = 3: A double-precision floating point value, with data stored in m_Double.

enumerator MRI_ATTR_STRING = 4: A string value, with data stored in m_pString.

enumerator MRI_ATTR_STRING_LIST = 5: A string list value, with data stored in m_pString. Elements are separated by ‘\n’ (a new line character).

struct MriAttributeValue

#include <MriUserPluginCommon.h>

Describes an attribute, with type and data, for passing between Mari and plug-ins.

Attributes provide the ability to pass data of various types between Mari and plug-ins. These can be for cases such as metadata, loading options, and others.

Attributes are managed in groups in the context of a relevant processing handle, to identify them between potentially concurrent image or geometry data loads or saves, for example. This also allows Mari to manage all attribute memory itself and clean it up once a processing operation is complete.

All data, including strings and attribute lists, is managed by Mari itself. User plug-ins do not need to maintain any buffers themselves beyond any single function call that they make.

Logging

group Logging

Provides debug logging functionality for use by plug-ins.

Logging must be used through one of the main provided APIs.

Typedefs

typedef void (*MriUserPluginTraceFunc)(const char *pFormat, ...)

Writes debug tracing text to the Mari log with printf-style formatting.

void trace(const char *pFormat, ...); 

For example:

trace("Number of characters: %d", 4); 

Any errors, such as an invalid pointer being supplied for the format, will be ignored.

Examples

group Examples

These examples show how to implement Mari plug-ins using the C API.

All example code is written in C only. This makes it easy to see the simplest use of the plug-in interface, and simplifies the building process, as there is no need to link in any libraries other than the standard C ones automatically used by the compiler.

To build the examples:

On Linux, you can use the provided Makefiles
On Windows, you can use the Visual Studio solution file, which was made in VS2005, but should work fine in other versions. Alternatively, you can start a Visual Studio 64-bit command prompt, and run the build.bat in the examples folder.

Make sure you copy the built examples to your Mari custom plug-ins folder, so Mari will find them when it starts up, and you can try them out. You can use the “make install” (Linux) or “build install” (Windows) commands to do this if desired. On Linux, the install script creates symbolic links to the libraries, so it should only be necessary to install them once.

The default Mari custom plug-ins folder is:

~/Mari/Plugins (on Linux)
Documents\Mari\Plugins (on Windows)

You can use a different folder, or a list of folders, for custom plug-ins by specifying it in the environment variable MARI_PLUGINS_PATH.

Display Render

group Display Render

This demonstrates the usage of the DisplayRender API to render custom display in Mari.

This example implements the DisplayRender plugin, allowing a user to register custom display renderer.

Functions

void createDisplayRenderThread(void)

void deleteDisplayRenderThread(void)

void *displayRenderAsyncRender(void *param)

Variables

unsigned char *s_DisplayRenderBuffer = NULL

int s_DisplayRenderBufferHeight = 0

int s_DisplayRenderBufferWidth = 0

pthread_mutex_t s_DisplayRenderMutex

pthread_t s_DisplayRenderThread

bool s_DisplayRenderThreadExit = false

Display Render Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriUserPluginResult displayRenderDisplayDestroyed(const char *DisplayName)

MriUserPluginResult displayRenderDisplayResized(const char *DisplayName, int DisplayWidth, int DisplayHeight)

MriUserPluginResult displayRenderRender(const char *DisplayName, unsigned char *OffscreenBufferPointer, int OffscreenBufferWidth, int OffscreenBufferHeight): Renders the pixels into the display.

Display Render Example Plug-in Interface

group Plug-in Interface

Functions

void flushDisplayRenderSuite(): Cleans up the display render plug-in.

const void *getDisplayRenderSuite(): Returns the suite of functions provided by a display render plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

FnPluginStatus setDisplayRenderPluginHost(const FnPluginHost *pHost): Sets the display render host information for a plug-in.

Variables

MriDisplayRenderHostV1 s_DisplayRenderPluginHost: The Display Render host structure, which contains functions that the plug-in can call.

MriDisplayRenderPluginV1 s_DisplayRenderPluginPluginSuite = {&displayRenderRender, &displayRenderDisplayResized, &displayRenderDisplayDestroyed}: The plug-in structure, to provide to the display render host so it can call functions when needed.

Geometry Reader

group Geometry Reader

This demonstrates the loading of a simple set of geometry using the Mari C API.

Defines

CORNERS_PER_SIDE 4: Data elements (vertices, etc) per cube side.

NUM_CUBE_CORNERS (NUM_CUBE_SIDES * CORNERS_PER_SIDE): Cube data element counts (vertices, etc)

NUM_CUBE_SIDES 6: Cube sides (for clarity)

NUM_RECT_CORNERS 4: Rect data element counts (vertices, etc)

Variables

const float geoReaderKEpsilon = 1.0e-6f

const char *const kpAdditionalCubeText = "Create Additional Child Cubes": Attribute name text for checking.

Geometry Reader Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriGeoPluginResult geoReaderGetSettings(MriUserItemHandle SettingsHandle, const char *pFileName): Retrieves the settings for loading a geometry file.

MriGeoPluginResult geoReaderLoad(MriGeoEntityHandle Entity, const char *pFileName, const char **ppMessagesOut): Loads a geometry file.

MriFileFormatDesc *geoReaderSupportedFormats(int *pNumFormatsOut): Returns the formats supported by the plug-in.

Geometry Reader Example Plug-in Interface

group Plug-in Interface

Functions

void geoReaderFlushPluginSuite(): Cleans up the plug-in.

const void *geoReaderGetPluginSuite(): Returns the suite of functions provided by a plug-in.

FnPluginStatus geoReaderSetHost(const FnPluginHost *pHost): Sets the host information for a plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

Variables

MriGeoReaderHostV3 s_GeoReaderHost: The host structure, which contains functions that the plug-in can call.

MriGeoReaderPluginV1 s_GeoReaderPluginSuite = {&geoReaderLoad, &geoReaderGetSettings, &geoReaderSupportedFormats}: The plug-in structure, to provide to the host so it can call functions when needed.

Geometry Reader Example Main Operations

group Main Operations

Functions

void freeGeoData(GeoData **ppData, int NumObjects): Frees geometry buffer data.

void generateCube(GeoData *pGeom, const CubeParams *pParams, int Frame): Generates cube geometry for a specific frame from a parameter structure.

MriGeoPluginResult generateCubeFrames(MriGeoEntityHandle Entity, MriGeoDataHandle Vertices, const CubeParams *pParams): Generates cube geometry for a set of grames from a parameter structure.

void generateRect(GeoData *pGeoDataOut, float Width, float Height, float OriginX, float OriginY, float OriginZ, float NormX, float NormY, float NormZ): Generates rectangle geometry from dimensions, origin, and normal.

MriGeoPluginResult loadCube(MriGeoEntityHandle Entity, FILE *pFile, GeoData *pGeom, CubeParams *pParams): Loads a single cube geometry from an open file.

MriGeoPluginResult loadCubes(MriGeoEntityHandle Entity, FILE *pFile, GeoData **ppGeom, CubeParams **ppParams, int *pNumCubes, int *pHasUv): Loads multiple cube geometries from an open file.

MriGeoPluginResult loadRect(MriGeoEntityHandle Entity, FILE *pFile, GeoData *pGeom, int *pHasUv): Loads rectangle geometry from an open file.

struct CubeParams: A local structure for passing cube parameters.

struct GeoData: A local structure for passing generated geometry data around.

Geometry Reader Example Helper Functions

group Helper Functions

Defines

PRINT_TO_LOG(...) PRINT_TO_LOGF(__VA_ARGS__)

PRINT_TO_LOGF(Format, ...) s_GeoReaderHost.trace("[MriExampleGeoReaderPlugin:%30s:%-4u] : " Format, __FILE__, __LINE__, ##__VA_ARGS__): Prints out the formatted string to the Mari log file with more information prepended.

Functions

float geoReaderAbsolute(float Val): Returns the absolute of a value.

void geoReaderCrossProduct(float X1, float Y1, float Z1, float X2, float Y2, float Z2, float *pResultX, float *pResultY, float *pResultZ): Calculates the cross product of two vectors.

float geoReaderDotProduct(float X1, float Y1, float Z1, float X2, float Y2, float Z2): Calculates the dot product of two vectors.

void geoReaderNormalize(float *pX, float *pY, float *pZ): Normalizes a vector.

void geoReaderPrintAllAttributes(MriUserItemHandle ItemHandle): Prints out the value of all attributes specified for the item.

void geoReaderPrintAttribute(MriUserItemHandle Handle, const char *pName): Prints out the value of an individual attribute.

void geoReaderSetFloatTriple(float **pTarget, float Val0, float Val1, float Val2): Sets three consecutive float values from the values provided.

Hierarchical Geometry Reader

group Hierarchical Geometry Reader

This demonstrates the loading of a hierarchical set of geometries using the Mari C API.

Functions

void AnimateRectangleGeomtry(HierarchicalGeoData *GeoDataOut, int Index)

Variables

const float hierarchicalGeoReaderKEpsilon = 1.0e-6f

Hierarchical Geometry Reader Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriGeoPluginResult hierarchicalGeoReaderGetSettings(MriUserItemHandle SettingsHandle, const char *pFileName): Retrieves the settings for loading a geometry file.

MriGeoPluginResult hierarchicalGeoReaderLoad(MriGeoEntityHandle Entity, const char *pFileName, const char **ppMessagesOut): Loads a geometry file.

MriFileFormatDesc *hierarchicalGeoReaderSupportedFormats(int *pNumFormatsOut): Returns the formats supported by the plug-in.

Hierarchical Geometry Reader Example Plug-in Interface

group Plug-in Interface

Functions

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

void hierarchicalGeoReaderFlushPluginSuite(): Cleans up the plug-in.

const void *hierarchicalGeoReaderGetPluginSuite(): Returns the suite of functions provided by a plug-in.

FnPluginStatus hierarchicalGeoReaderSetHost(const FnPluginHost *pHost): Sets the host information for a plug-in.

Variables

MriGeoReaderHostV4 s_HierarchicalGeoReaderHost: The host structure, which contains functions that the plug-in can call.

MriGeoReaderPluginV1 s_HierarchicalGeoReaderPluginSuite = {&hierarchicalGeoReaderLoad, &hierarchicalGeoReaderGetSettings, &hierarchicalGeoReaderSupportedFormats}: The plug-in structure, to provide to the host so it can call functions when needed.

Hierarchical Geometry Reader Example Main Operations

group Main Operations

Functions

void AnimatedRectangleGeomtry(HierarchicalGeoData *GeoDataOut, int Index): Modifies a rectangle geometry vertices, normals and uvs, to demonstrate animation.

MriGeoPluginResult CreateRectangleGeoEntity(MriGeoEntityHandle GeoEntity, const char *EntityName, int AnimationFrameCount): Creates an entire rectangle GeoEntity, from creating the geometry to creating the various strucutures in Mari and loading the various channels with the geometry data

void GenerateRectangleGeomtry(HierarchicalGeoData *GeoDataOut): Creates a rectangle geometry vertices, normals, uvs, and indices data.

struct HierarchicalGeoData: A local structure for passing generated geometry data around.

Hierarchical Geometry Reader Example Helper Functions

group Helper Functions

Functions

void getParentName(const char *Name, char *ParentName): Gets the name of the parent of a key, using the / split.

float hierarchicalGeoReaderAbsolute(float Val): Returns the absolute of a value.

void hierarchicalGeoReaderCrossProduct(float X1, float Y1, float Z1, float X2, float Y2, float Z2, float *pResultX, float *pResultY, float *pResultZ): Calculates the cross product of two vectors.

float hierarchicalGeoReaderDotProduct(float X1, float Y1, float Z1, float X2, float Y2, float Z2): Calculates the dot product of two vectors.

void hierarchicalGeoReaderNormalize(float *pX, float *pY, float *pZ): Normalizes a vector.

void hierarchicalGeoReaderSetFloatTriple(float **pTarget, float Val0, float Val1, float Val2): Sets three consecutive float values from the values provided.

Image Reader

group Image Reader: This demonstrates the loading of a simple custom image format using the Mari C API.

Image Reader Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriImagePluginResult imageDataFormat(const char *FileName, MriImageDataFormat *OutFormat)

MriFileFormatDesc *imageReaderSupportedFormats(int *pNumFormatsOut): Returns the formats supported by the plug-in.

MriImagePluginResult load(MriImageHandle ImageHandle, const char *pFileName, const char **ppMessageStringOut): Loads an image file.

Image Reader Example Plug-in Interface

group Plug-in Interface

Functions

void flushImageReaderSuite(): Cleans up the plug-in.

const void *getImageReaderSuite(): Returns the suite of functions provided by a plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

FnPluginStatus setImageReaderHost(const FnPluginHost *pHost): Sets the host information for a plug-in.

Variables

MriImageReaderHostV1 s_ImageReaderHost: The host structure, which contains functions that the plug-in can call.

MriImageReaderPluginV2 s_ImageReaderPluginSuite = {&load, &imageReaderSupportedFormats, &imageDataFormat}: The plug-in structure, to provide to the host so it can call functions when needed.

Image Reader Example Helper Functions

group Helper Functions

Functions

void imageReaderPrintAllAttributes(MriImageHandle ImageHandle): Prints out the value of all attributes specified for the item.

void imageReaderPrintAttribute(MriUserItemHandle Handle, const char *pName): Prints out the value of an individual attribute.

Image Writer

group Image Writer: This demonstrates saving to a simple custom image format using the Mari C API.

Image Writer Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriFileFormatDesc *imageWriterSupportedFormats(int *pNumFormatsOut): Returns the file formats supported by the plug-in.

MriImagePluginResult save(MriImageHandle ImageHandle, const char *pFileName, const char **ppMessageStringOut, MriImageDataFormat Format, int NumMipMapLevels, int TileWidth, int TileHeight): Saves an image file.

MriImageDataFormat *supportedImageFormats(const char *pExtension, int *pNumFormatsOut): Returns the image data formats supported by the plug-in.

Image Writer Example Plug-in Interface

group Plug-in Interface

Functions

void flushImageWriterSuite(): Cleans up the plug-in.

const void *getImageWriterSuite(): Returns the suite of functions provided by a plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

FnPluginStatus setImageWriterHost(const FnPluginHost *pHost): Sets the host information for a plug-in.

Variables

MriImageWriterHostV1 s_ImageWriterHost: The host structure, which contains functions that the plug-in can call.

MriImageWriterPluginV1 s_ImageWriterPluginSuite = {&save, &supportedImageFormats, &imageWriterSupportedFormats}: The plug-in structure, to provide to the host so it can call functions when needed.

Image Writer Example Helper Functions

group Helper Functions

Functions

void imageWriterPrintAllAttributes(MriImageHandle ImageHandle): Prints out the value of all attributes specified for the item.

void imageWriterPrintAttribute(MriUserItemHandle Handle, const char *pName): Prints out the value of an individual attribute.

Invert Image Operation

group Invert Image Operation

This demonstrates the usage of the texture API, to access image texture data and inverting the pixels.

These are the steps to demonstrate this invert operation:

The ImageInfo API is passed an image uuid to get information about the image, such as the data format, the colorspace and the mipmap information.
The Texture API, the main API, queries texture data for a given image, mipmap level and tile.
The data is parsed and the pixels are inverted.
The Texture API saves the changes back to the DDI and updates all the other mipmap levels of the image.

This example operation implements the ImageOperation plugin, that allows a user to register an image operation with Mari. This plugin’s execute function would then be called, should the plugin indicate that it implements an operation of the required type; this is done by querying the plugin’s supportedFormats function.

Invert Image Operation Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriImagePluginResult execute(MriImageOperationBlockHandle ImageOpHandle, const char *Operation, MriImageHandle ImageHandle, const char *ImageUuid, MriPixelBlockHandle PixelBlockHandle, int ExtraParameterCount, char **ExtraParameterKeys, char **ExtraParameterValues)

Gets texture data and inverts its pixels.

This is the main function that implements the invert operation on the texture data, given an image. Note that the image (from the image manager or a layer) must exists within the current project in Mari, else an error is reported.

This function also takes extra parameters, so that the user can further customise the implementation of the image operation.

Parameters:

ImageOpHandle – A handle used to co-relate this image operation to its internal side (mari internal c++)
Operation – The operation to execute (from the list of supportedFormats).
ImageHandle – A handle to reference the image, whose texture data is being used here.
ImageUuid – The uuid of the image, being queried for texture data.
PixelBlockHandle – A handle to reference to the texture data, as its read and manipulated in the API.
ExtraParameterCount – The count of extra parameters, being passed to the function.
ExtraParameterKeys – The extra parameter keys.
ExtraParameterValues – The extra parameter values.

Returns:

The success state of the function

MriImagePluginResult invertImageOpGetImageInfo(MriImageHandle ImageHandle, const char *ImageUuid, int *ImageWidth, int *ImageHeight, int *IsUniformColor, const char **OutColor, MriImageDataFormat *DataFormat, int *MipMapLevels, int *TileWidth, int *TileHeight, MriImageMipMapInfo *MipMapInfo, char **OutColorSpace, int *OutColourProfileCount, char ***OutColourProfileList)

Reads information about an image.

Note that the image must exist and be loaded within the current Mari project, otherwise an error is returned.

Parameters:

ImageHandle – The image handle, for which image we want to query.
ImageUuid – The uuid of the image to query.
ImageWidth – The width of the image.
ImageHeight – The height of the image.
IsUniformColor – Flag to indicate whether the image is of uniform color.
OutColor – The uniform color of the image.
DataFormat – The image data format.
MipMapLevels – The number of mip map levels in the image.
TileWidth – The width of a tile in the image.
TileHeight – The height of a tile in the image.
MipMapInfo – Information about mip map levels in the image.
OutColorSpace – The colorspace of the image.
OutColourProfileCount – The count of color profiles for the image.
OutColourProfileList – The list of color profiles for the image.

Returns:

The success state of the function

MriImagePluginResult invertImageOpGetPixelBlockData(MriPixelBlockHandle PixelBlockHandle, MriPixelBlockRequest *PixelBlockRequest, void **OutData, size_t *OutBlockSize)

Gets texture data for an image.

Note that the image must be loaded within Mari.

Parameters:

PixelBlockHandle – The hnadle associated with the pixel block.
PixelBlockRequest – The request strucuture, detailing which tile to extract information from and in what format.
OutData – The texture data.
OutBlockSize – The data size in bytes.

Returns:

The success state of the function

MriFileFormatDesc *invertImageOpSupportedFormats(int *pNumFormatsOut)

This defines the supported operations, exposed by this plugin.

Each entry in the array consists of a key and a description, e.g., {“Invert”, “This is an operation to invert the colours of a texture”}. These can be queried later on in Mari.

Please note that the “operation” parameter passed to “execute” must match one of the keys in the supportFormats, so that this plugin is called.

Parameters:: pNumFormatsOut – The number of supported operations.
Returns:: The supported operations.

Invert Image Operation Example Plug-in Interface

group Plug-in Interface

Functions

void flushImageOpSuite(): Cleans up the image op plug-in.

const void *getImageOpSuite(): Returns the suite of functions provided by an image op plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

void invertImageOpFlushImageInfoSuite(): Cleans up the image info plug-in.

void invertImageOpFlushTextureSuite(): Cleans up the texture plug-in.

const void *invertImageOpGetImageInfoSuite(): Returns the suite of functions provided by an image info plug-in.

const void *invertImageOpGetTextureSuite(): Returns the suite of functions provided by a texture plug-in.

FnPluginStatus invertImageOpSetImageInfoHost(const FnPluginHost *pHost): Sets the image info host information for a plug-in.

FnPluginStatus invertImageOpSetTextureHost(const FnPluginHost *pHost): Sets the texture host information for a plug-in.

FnPluginStatus setImageOpHost(const FnPluginHost *pHost): Sets the image op host information for a plug-in.

Variables

MriUserImageOperationHostV1 s_ImageOpHost: The image Op host structure, which contains functions that the plug-in can call.

MriUserImageOperationPluginV1 s_ImageOpPluginSuite = {&invertImageOpSupportedFormats, &execute}: The plug-in structure, to provide to the Image Op host so it can call functions when needed.

MriImageInfoHostV1 s_InvertImageOpImageInfoHost: The image info host structure, which contains functions that the plug-in can call.

MriImageInfoPluginV1 s_InvertImageOpImageInfoPluginSuite = {&invertImageOpGetImageInfo}: The plug-in structure, to provide to the Image Info host so it can call functions when needed.

MriTextureHostV1 s_InvertImageOpTextureHost: The texture host structure, which contains functions that the plug-in can call.

MriTexturePluginV1 s_InvertImageOpTexturePluginSuite = {&invertImageOpGetPixelBlockData}: The plug-in structure, to provide to the Texture host so it can call functions when needed.

Obj Exporter Geometry Operation

group Obj Exporter Geometry Operation

This demonstrates the usage of the GeometryAccess API to access geometry in Mari and write its mesh information to a file.

These are the steps to demonstrate this operation:

We use the GeometryAccess API, passing to it a GeoEntity uuid, version uuid and other related information, such as subdivision level and animation frame, to locate an object that we want mesh information from.
We parse through the meshes and their data channels and format them out to an obj file.

This example operation implements the GeometryOperation plugin, allowing a user to register a geometry operation with Mari. This plugin’s execute function would then be called, should the plugin indicate that it implements an operation of the required type; this is done by querying the plugin’s supportedFormats function.

Variables

FILE *OutputObjFile = 0: The obj file to write geometry mesh data to.

Obj Exporter Example Plug-in Function Suite

group Plug-in Function Suite

Functions

MriGeoPluginResult execute(MriGeometryOperationBlockHandle GeometryOpHandle, const char *Operation, const char *GeoUuid, MriGeoEntityHandle GeoEntityHandle, const char *VersionUuid, int Frame, int QuerySubdivisionMesh, int SubdivisionLevel, int ExtraParameterCount, char **ExtraParameterKeys, char **ExtraParameterValues)

Gets geometry data and write it to an Obj formatted file.

This is the main function that implements the operation on the geometry data, given information about a Geo Version in a Geo Entity. Note that the GeoEntity and This function also takes extra parameters, so that the user can further customise the implementation of the operation, e.g., passing in the the filename of the output file.

Parameters:

GeometryOpHandle – A handle used to co-relate this operation to its internal side (mari internal c++)
Operation – The operation to execute (from the list of supportedFormats).
GeoUuid – The uuid of the GeoEntity, being queried for geometry data.
GeoEntityHandle – A handle to reference the GeoEntity.
VersionUuid – The uuid of the version, of the GeoEntity, to query for mesh data.
Frame – The data frame, in case of animation.
QuerySubdivisionMesh – Flag to indicate whether to access subdivision meshes, instead of original meshes, for data.
SubdivisionLevel – The subdivision level at which the subdivision meshes are required.
ExtraParameterCount – The count of extra parameters, being passed to the function.
ExtraParameterKeys – The extra parameter keys.
ExtraParameterValues – The extra parameter values.

Returns:

The success state of the function

MriFileFormatDesc *objExporterSupportedFormats(int *pNumFormatsOut)

This defines the supported operations, exposed by this plugin.

Each entry in the array consists of a key and a description, e.g., {“Obj”, “This is an operation to export geometry data to an obj file”}. These can be queried later on in Mari.

Please note that the “operation” parameter passed to “execute” must match one of the keys in the supportFormats, so that this plugin is called.

Parameters:: pNumFormatsOut – The number of supported operations.
Returns:: The supported operations.

MriGeoPluginResult readGeoEntity(MriGeoEntityHandle GeoEntityHandle, const char *GeoUuid, const char *VersionUuid, int Frame, int QuerySubdivisionMesh, int SubdivisionLevel)

Reads a GeoEntity and gather its mesh data.

This function drills down from a GeoEntity to a version to a mesh to a data channel and gets the geometry data back. GeoVersion must exists within the current project in Mari, else an error is reported.

Parameters:

GeoEntityHandle – A handle to reference the GeoEntity.
GeoUuid – The uuid of the GeoEntity, being queried for geometry data.
VersionUuid – The uuid of the version, of the GeoEntity, to query for mesh data.
Frame – The data frame, in case of animation.
QuerySubdivisionMesh – Flag to indicate whether to access subdivision meshes, instead of original meshes, for data.
SubdivisionLevel – The subdivision level at which the subdivision meshes are required.

Obj Exporter Example Plug-in Interface

group Plug-in Interface

Functions

void flushGeometryAccessSuite(): Cleans up the geometry access plug-in.

void flushGeometryOpSuite(): Cleans up the geometry op plug-in.

const void *getGeometryAccessSuite(): Returns the suite of functions provided by a geometry access plug-in.

const void *getGeometryOpSuite(): Returns the suite of functions provided by a geometry op plug-in.

FnPlugin *getPlugins(unsigned int *pNumPlugins): Returns the list of plug-ins in this library.

FnPluginStatus setGeometryAccessHost(const FnPluginHost *pHost): Sets the geometry access host information for a plug-in.

FnPluginStatus setGeometryOpHost(const FnPluginHost *pHost): Sets the geometry op host information for a plug-in.

Variables

MriGeometryAccessPluginV1 s_GeometryAccesPluginSuite = {&readGeoEntity}: The plug-in structure, to provide to the geometry access host so it can call functions when needed.

MriGeometryAccessHostV1 s_GeometryAccessHost: The Geometry Access host structure, which contains functions that the plug-in can call.

MriUserGeometryOperationHostV1 s_GeometryOpHost: The Geometry Op host structure, which contains functions that the plug-in can call.

MriUserGeometryOperationPluginV1 s_GeometryOpPluginSuite = {&objExporterSupportedFormats, &execute}: The plug-in structure, to provide to the geometry op host so it can call functions when needed.

Obj Exporter Example Helper Functions

group Helper Functions

Functions

void printData(MriGeoDataRole GeoDataRole, const unsigned char *GeoData, unsigned int GeoDataEntryCount, MriGeoDataType GeoDataType, int GeoDataElementSize): Casts geometry data and print them to the console.

MriGeoPluginResult queryMeshAndWriteToFile(MriGeoEntityHandle GeoEntityHandle, const double *GeoEntityTransformMatrix, const double *GeoTransposeInverseTransformMatrix, MriGeoVersionHandle VersionHandle, MriGeoMeshHandle MeshHandle, FILE *OutFile, unsigned int *NextVertexIndex, unsigned int *NextUvIndex, unsigned int *NextNormalIndex, int Frame)

This function query mesh data, within a GeoVersion and write the data to file.

A Geo Entity contains a list of subdivision meshes and a list of the original (unsubdivided) meshes. We need to get the required list, since that affects the format in which we get data and parse them and format them to the output file.

Once we get the list of mesh handles, we then need to query all the data channels to gather the following key channels and their data:

Vertex (MRI_GDR_VERTICES) - MANDATORY
Normal (MRI_GDR_NORMALS)
Uv (MRI_GDR_UV)
Vertex indices (MRI_GDR_INDICES) - MANDATORY
Normal indices (MRI_GDR_ORIGINAL_NORMAL_INDICES)
Uv indices (MRI_GDR_ORIGINAL_UV_INDICES)
Face vertex counts (MRI_GDR_FACE_VERTEX_COUNTS)

This function cannot continue if we have our vertex data is 0, since that is vital information.

Note about the face vertex count data array:

Subdivision meshes are indexed and triangulated in Mari. As such, we do not store vertex count per face. The way, then, for us to determine how many vertices we have per face is by using the vertex indices elementSize. For a non-subdivided mesh (original mesh), the elementSize will be 1. For a subdivided mesh, the elementSize will be the 3 per face. Note, we use this same logic later when we need to write out indices to the file. As such, we error out if we have no face vertex count data and we are querying original meshes.

The following describes the logic of parsing the face vertex count array and the vertex indices array and getting the face vertex indices to write to the file:

1. An original unsubdivided mesh

Given an example cube with 6 faces, for original non-subdivided meshes, we have 24 indices of elementSize 1 as follows:

GeoData Element size: 1

GeoData Entry Count: 24

Data [0] : (0, )

Data [1] : (1, )

Data [2] : (2, )

Data [3] : (3, )

Data [4] : (3, )

Data [5] : (2, )

Data [6] : (4, )

Data [7] : (5, )

Data [8] : (5, )

Data [9] : (4, )

Data [10] : (6, )

Data [11] : (7, )

Data [12] : (7, )

Data [13] : (6, )

Data [14] : (1, )

Data [15] : (0, )

Data [16] : (1, )

Data [17] : (6, )

Data [18] : (4, )

Data [19] : (2, )

Data [20] : (7, )

Data [21] : (0, )

Data [22] : (3, )

Data [23] : (5, )

We also need data from our face count vertex array to appropriately interpret the indices. Given 6 entries in the face vertex count array, each of value 4 to represent 6 quads, we therefore need to parse our face vertex count array and for each face, read the indices in data to produce an index list as follows:

0 1 2 3

3 2 4 5

5 4 6 7

7 6 1 0

1 6 4 2

7 0 3 5

2. A subdivided mesh

Subdivision meshes are different since they are triangulated and reindexed; so we only need the vertex indices data and we dont have any face vertex count array. Given an example cube with 6 faces, for subdivision meshes, we have 6*2 = 12 triangles = 12 entries of elementSize 3 in our vertex indices array

GeoData Element size: 3

GeoData Entry Count: 12

Data [0] : (0, 1, 2, )

Data [1] : (0, 2, 3, )

Data [2] : (4, 5, 6, )

Data [3] : (4, 6, 7, )

Data [4] : (8, 9, 10, )

Data [5] : (8, 10, 11, )

Data [6] : (12, 13, 14, )

Data [7] : (12, 14, 15, )

Data [8] : (16, 17, 18, )

Data [9] : (16, 18, 19, )

Data [10] : (20, 21, 22, )

Data [11] : (20, 22, 23, )

Since we dont have the face vertex count array, because the data has been triangulated and reindexed, we can treat the above vertex indices data as the direct indices and write them out to the file. These indices will be exactly similar for the normals and uvs.

Please note also that it is vital that we transform the vertices and normals with the transform matrices, since Mari stores mesh data in a hierarchical manner.

Parameters:

GeoEntityHandle – A handle to the geo entity.
GeoEntityTransformMatrix – An array of 16 doubles, representing a 4x4 transform matrix of the geo entity.
GeoTransposeInverseTransformMatrix – An array of 16 doubles, representing a 4x4 transpose of the inverse of the transform matrix of the geo entity.
VersionHandle – A handle to the version, within a geo entity.
MeshHandle – A handle to the mesh, within the geo version.
OutFile – The output obj file.
NextVertexIndex – An accumulative offset to the vertex index, used for writing out to the file.
NextUvIndex – An accumulative offset to the uv index, used for writing out to the file.
NextNormalIndex – An accumulative offset to the normal index, used for writing out to the file.
Frame – The frame for which to query data, in case of animation.

Returns:

The success state of the function

const char *roleStr(MriGeoDataRole Role): Convert a GeoData Role to its string format.

void transformVectorByMatrix(float *Data, unsigned int DataCount, const double *TransformMatrix, bool Point, bool Verbose)

This transforms vector data, vertices and normals, by the matrix of the GeoEntity.

This function is used to transform vertices and normals, into baked world space. Mari uses a hierarchical node graph to store entities, objects, cameras, lights and etc. Each of these nodes has a transform matrix and can be transformed independently using various tools, such as the “move” tool. Objects can also be imported in hierarchy already using file formats such as alembic and fbx.

Therefore, we need to transform our vertices by the transform matrix, and our normals by the transpose of the inverse of the transform matrix (http://www.unknownroad.com/rtfm/graphics/rt_normals.html).

This function transforms vertices or normals, based on an argument “Point”. Set to true implies a vertex, set to false is a normal.

Parameters:

Data – The vector data of float
DataCount – The number of data entries in the array.
TransformMatrix – An array of 16 doubles, representing a 4x4 transform matrix that needs to be applied to the vector data.
Point – Toggle to indicate whether the data represents vertices or normals. This is vital to how the transformation happens and how the vector is normalised.
Verbose – A flag to toggle printing of the transformed vector.

const char *typeStr(MriGeoDataType Type): Convert a GeoData Type to its string format.