Pro Motion Developer Interface

The articles below contain interface descriptions and sample applications for two types of plugin interfaces. The file i/o interface is used to create individual image or animation file filters. The DDE plugin interface is used to let a plugin access image data for individual processing. If you have any questions concerning the interfaces please send an email to Jan Zimmermann.

File I/O Plugin Interface
Sample File I/O Plugins
Manipulation Plugin Interface

File I/O Plugin Interface

With the file plugin interface you can create a DLL implementing the file input/output logic using some predefined functions.

The DLL must the be placed into the plugins subfolder within the pro motion installation folder. By then it is automatically loaded into the application on startup and can be used like any other built in image or animation file type.

Since Pro Motion NG version 7.1.8, plugins can also be used with the Free Edition.

The DLL must just implement a couple of functions. They are called by the application as described. See Sample File I/O Plugins to have a quick start. They come with full C++ source (MS Visual Studio) so you can check them out in whole detail.

initialize()

function initialize( language: PChar; var version: word; var animation: boolean ): boolean; stdcall;

bool __stdcall initialize( char* language, unsigned short* version, bool* animation );

General initialization function. It is called once the plugin is registered by the application for further use. It is the first function that will be called at all. If an error occurs then the function must return false.

Parameters
`language`	two character ISO language code that is currently used to display translated messages.
`version`	The number of the plugin interface version. Must return “1” to be a valid plugin.
`animation`	set to true if the plugin is used for accessing animation files.

Control
Return value	`true` if successful, `false` otherwise.
May set error	Yes.

setProgressCallback()

procedure setProgressCallback( progressCallback: TProgressCallback ); stdcall;

void __stdcall setProgressCallback( ProgressCallback progressCallback );

Use this function to define a progress callback that is called by the plugin to give user feedback about the progress of loading/saving image data. A percent value of 0 should make the progress display to hide and values between 1 and 100 should make the display visible.

Parameters
`progressCallback`	A function to be called when progress changes `type TProgressCallback= procedure (percent: integer); stdcall;` `typedef void (__stdcall *ProgressCallback)( int progress )`

Control
Return value	None.
May set error	No.

getErrorMessage()

function getErrorMessage: PChar; stdcall;

char* __stdcall getErrorMessage();

Typically only certain functions are allowed to set an error message to not exaggerate error handling. Right after executing those functions getErrorMessage() is called by the application. If there is an error message then the result of the failing function is dismissed and the error is displayed.

If any of the functions causes an error then the application can read this error message using this function. As soon as a function is called the error message must be reset and it is set as soon as a function fails. The application must check for errors after each function that can create an error! Some functions may not create an error to prevent useless checking after every function call.

The plugin must reset its internal error message after getErrorMessage() was called. Since the application can only reset the error by calling getErrorMessage() every function could theoretically set an error. But if it is not explicitly allowed then the error message is not checked until a function is called that is allowed to set an error. This function will fail then instead of the one setting the error. The plugin should therefore only set errors when allowed.

Control
Return value	The error message or `nil`/`NULL`
May set error	No.

getFileTypeId()

function getFileTypeId: PChar; stdcall;

char* __stdcall getFileTypeId();

The plugin must return a unique identifier that is a name/alias for the plugin implementation. It is used internally for example if the user saved the file via this plugin and uses the “save again” function. In this case the application must know which plugin to use. The file extension is not unique enough. There could be several load/save plugins for “bmp-files”. The id may be a series of numbers/characters like a GUID, but it may also be a package descriptor like used in Java language, e.g. “de.mycompany.promotion.ioplugin.png”

Control
Return value	The unique identifier
May set error	No.

isReadSupported()

function isReadSupported: boolean; stdcall;

bool  __stdcall isReadSupported();

The application needs to know if the plugin can read the file format to place it into the file open/import dialogs.

Control
Return value	`true`, if read is supported, `false` otherwise.
May set error	No.

isWriteSupported()

function isWriteSupported: boolean; stdcall;

bool  __stdcall isWriteSupported();

The application needs to know if the plugin can write the file format to place it into the file save/export dialogs.

Control
Return value	`true`, if write is supported, `false` otherwise.
May set error	No.

isWriteTrueColorSupported()

function isWriteTrueColorSupported: boolean; stdcall;

bool  __stdcall isWriteTrueColorSupported();

The application needs to know if the plugin can write true color data to the file format. Certain processes like auto flattening layers may create colors that don’t fit into the 256 colors palette. In this case the image data can be optionally stored as true color. If the plugin does not support true color then the image colors are reduced to 256 indexed colors.

Control
Return value	`true`, if write is supported, `false` otherwise.
May set error	No.

getFileBoxDescription()

function getFileBoxDescription: PChar; stdcall;

char* __stdcall getFileBoxDescription();

To place the plugin into file i/o dialogs it must give a file type description that is displayed in the file filter box, e.g. “BMP Windows Bitmap RLE”. Please use the file type abbreviation (usually the file extension) at first place so that it can be sorted correctly.

Control
Return value	The file description in the selected language.
May set error	No.

getFileExtension()

function getFileExtension: PChar; stdcall;

char* __stdcall getFileExtension();

This function must return the file extension (without “.”) to be used in the file filter.

Control
Return value	The file extension supported by this plugin.
May set error	No.

setFilename()

procedure setFilename( filename: PChar ); stdcall;

void  __stdcall setFilename( char* filename );

Indicates that a new file is to be processed and gives the corresponding file name. The plugin should reset internal structures if the file name is different to the one set before. At this point it is undefined if the file is to be written or read!

Parameters
`filename`	Full path and name of the file to process.

Control
Return value	None.
May set error	No.

canHandle()

function canHandle: boolean; stdcall;

bool  __stdcall canHandle();

This function is called to check if the selected file can be handled for reading by the plugin. The plugin should open and check the file accordingly.

Control
Return value	`true`, if the file can be processed. If `false` is returned then an error message must be set saying why it can not be handled.
May set error	Yes.

loadBasicData()

function loadBasicData: boolean; stdcall;

bool  __stdcall loadBasicData();

Before reading graphic data this function is called to make the plugin check and load graphic file information such as dimensions, color palette and the like. Other functions rely on this function to be called first, such as getWidth()!

Control
Return value	`true`, if the file data could be loaded.
May set error	Yes.

getWidth()

function getWidth: integer; stdcall;

int   __stdcall getWidth();

Dimension request for width when loading the file.

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	The width of the image that is to be loaded in Pixels or -1 if the function fails.
May set error	No.

getHeight()

function getHeight: integer; stdcall;

int   __stdcall getHeight();

Dimension request for height when loading the file.

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	The height of the image that is to be loaded in Pixels or -1 if the function fails.
May set error	No.

getImageCount()

function getImageCount: integer; stdcall;

int   __stdcall getImageCount();

This function has to return the number of frames available to load from the file. If the file is just a single image then “1” is to be returned.

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	The number of frames of the image/animation that is to be loaded or -1 on failure.
May set error	Yes.

canExtractPalette()

function canExtractPalette: boolean; stdcall;

bool   __stdcall canExtractPalette();

The application may support functions to load the color palette from a graphic file without loading the graphic/bitmap data. It uses this function to determine if the plugin can be used there as well.

Control
Return value	If the plugin supports palette reading then this function must return `true`.
May set error	No.

getRgbPalette()

function getRgbPalette: pointer; stdcall;

unsigned char* __stdcall getRgbPalette();

If the plugin can extract the palette data then this function must return the palette with 768 bytes defining the 256 color values as RGB (one byte per channel). The palette bytes are RGBRGBRGB… and each RGB-tripel defines the corresponding color palette entry starting with “0”.

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	The RGB palette or `nil`/`NULL` if not supported.
May set error	No.

getTransparentColor()

function getTransparentColor: integer; stdcall;

int   __stdcall getTransparentColor();

If the image contains a transparent color then this function must return it.

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	The transparent color (pixel byte) or -1 if there is no transparent color.
May set error	No.

isAlphaEnabled()

function isAlphaEnabled: boolean; stdcall;

bool  __stdcall isAlphaEnabled();

Does the image/animation file contain alpha transparency data?

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Control
Return value	If the image contains alpha data then this function must return `true`.
May set error	No.

loadNextImage()

function loadNextImage( colorFrame,
                        colorFramePalette,
                        alphaFrame,
                        alphaFramePalette: Pointer;
                        var delayMs: word
): boolean; stdcall;

bool  __stdcall loadNextImage( unsigned char*  colorFrame,
                               unsigned char*  colorFramePalette,
                               unsigned char*  alphaFrame,
                               unsigned char*  alphaFramePalette,
                               unsigned short* delayMs
);

If the plugin supports reading then this function is used to load the image data. After reading this data the plugin must advance to the next frame, if any. The function will be called according to the number of frames returned by getImageCount().

loadBasicData() has been called by the application before using this function to ensure that this information is present.

Parameters
`colorFrame`	A pointer to the bitmap to hold the color pixels (color palette indexes). The memory portion has a size of `getWidth` * `getHeight` bytes!
`colorFramePalette`	A pointer to the RGB color table. There are 768 bytes being 256 colors with one byte for red, green and blue.
`alphaFrame`	A pointer to the bitmap to hold the alpha palette indexes. The memory portion has a size of `getWidth` * `getHeight` bytes! If alpha is not supported then this value is `nil`/`NULL` and must not be used.
`alphaFramePalette`	A pointer to the alpha value table. There are 256 bytes. Each byte is an alpha value ranging from 0 to 255. If alpha is not supported then this value is `nil`/`NULL` and must not be used.
`delayMs`	If the frame has a delay value (animation only) then it must be given here as milliseconds.

Control
Return value	If the data was transfered successfuly then `true` is to be returned.
May set error	Yes.

beginWrite()

function beginWrite(
    width, height, transparentColor: integer;
    alphaEnabled: boolean;
    numberOfFrames: integer
): boolean; stdcall;

bool  __stdcall beginWrite(
    int width,
    int height,
    int transparentColor,
    bool alphaEnabled,
    int numberOfFrames
);

Before writing graphic data this function is called once by the application to define dimensions of the data that will be stored. The file may stay opened until finishProcessing() is called.

Parameters
`width`	Width of the graphic (images)
`height`	Height of the graphic (images)
`transparentColor`	If a transparent color is used then it is given here or -1 otherwise
`alphaEnabled`	If the graphic will store alpha data then this flag is set to `true`.
`numberOfFrames`	Number of frames that will be written

Control
Return value	`true` on success
May set error	Yes.

writeNextImage()

function writeNextImage(
    colorFrame, colorFramePalette, alphaFrame, alphaFramePalette, rgba: Pointer;
    delayMs: word
): boolean; stdcall;

bool  __stdcall writeNextImage(
    unsigned char* colorFrame,
    unsigned char* colorFramePalette,
    unsigned char* alphaFrame,
    unsigned char* alphaFramePalette,
    unsigned char* rgba,
    unsigned short delayMs
);

If the plugin supports writing then this function is used to save the image data. The function will be called as often as there are more frames to be stored.

Parameters
`colorFrame`	A pointer to the bitmap having the color pixels (color palette indexes). The memory portion has a size width * height bytes!
`colorFramePalette`	A pointer to the RGB color table. There are 768 bytes being 256 colors with one byte for red, green and blue
`alphaFrame`	A pointer to the bitmap having the alpha palette indexes. The memory portion has a size of width * height bytes! If alpha is not supported then this value is nil and must not be used.
`alphaFramePalette`	A pointer to the alpha value table. There are 256 bytes. Each byte is an alpha value ranging from 0 to 255. If alpha is not supported then this value is `nil`/`NULL` and must not be used.
`rgba`	A pointer to the bitmap having the color pixels as dword per pixel RGBA where the lowest byte is the red channel. The memory portion has a size width * height * 4 bytes!
`width`	Width in pixels of the image
`height`	Height in pixels of the image
`delayMs`	If the frame has a delay value (animation only) then it is given here as milliseconds.

Control
Return value	If the data was transfered successfuly then `true` is to be returned.
May set error	Yes.

finishProcessing()

procedure finishProcessing; stdcall;

void  __stdcall finishProcessing();

This function is called if the read or write operation is finished. The plugin must then close the file that was processed.

Control
Return value	None.
May set error	No.

Sample File I/O Plugins

The sample file filters are two file i/o plugins to read and write a very simple image and animation file type. Both plugins come with full C++ source as MS Visual Studio project.

Download Docs & Sample Sources:

file_io_plugin_samples.zip

To see plugins working you can copy the precompiled DLLs sanAnimIo.dll and simImgIo.dll from the Release subfolder of the just downloaded and extracted zip to the plugins subfolder within your Pro Motion installation. After restarting pro motion you will have a new image file type “SIM Sample Image” and a new animation file type “SAN Sample Animation”. They can be found at all usual image or animation load/save functions where you can select file types.

The file format specification is very simple for both file types.

SIM file format

Parameters
Position (bytes)	Type	Description
`$00`	4 ASCII-chars	File type specifier: `SIMG`.
`$04`	Byte	Version, currently set to 1.
`$05`	DoubleWord	Image width in pixels.
`$09`	DoubleWord	Image height in pixels.
`$0d`	Integer	Transparent color or -1 of not defined.
`$11`	Boolean	Alpha layer enabled/present.
`$12`	256*3 Bytes	The 256 color table with the values Red, Green, Blue.
`$312`	256 Bytes	The 256 alpha value table if alpha is enabled.
`…`	width * height Bytes	The image color pixels.
`…`	width * height Bytes	The image alpha references if alpha is enabled.

SAN file format

Parameters
Position (bytes)	Type	Description
`$00`	4 ASCII-chars	File type specifier: `SANM`.
`$04`	Byte	Version, currently set to 1.
`$05`	DoubleWord	Image width in pixels.
`$09`	DoubleWord	Image height in pixels.
`$0d`	Integer	Transparent color or -1 of not defined.
`$11`	Boolean	Alpha layer enabled/present.
`$12`	DoubleWord	Number of frames.
`$16`	256*3 Bytes	The 256 color table with the values Red, Green, Blue.
`$316`	256 Bytes	The 256 alpha value table if alpha is enabled.
For every frame the following data is included:
`…`	Word	Delay in milliseconds before the next frame may be displayed.
`…`	width * height Bytes	The image color pixels.
`…`	width * height Bytes	The image alpha references if alpha is enabled.

Manipulation Plugin Interface

The basic idea of this interface is to exchange image/animation data between the host application (Pro Motion) and external programs (plugins). A plugin can access all basic project data, image and color palette contents. Data is exchanged using the Windows DDE (Dynamic Data Exchange) that allows an interprocess communication based on simple messages. Pro Motion contains a DDE-server and a plugin works as a DDE client sending command strings. For further information on how to program a DDE conversation please have a look at Microsoft’s development documentations.

Download Docs & Sample Sources:

dde_plugin_sample.zip

The plugin interface description and sample application package contains a complete documentation about plugin commands and how they have to be used. The sample application shows the use of all available commands. This program was developed with Embarcadero Delphi XE2 but might also be used for other versions of Delphi. There is also a small documentation for how to create DDE data transfer using Microsoft C/C++ APIs.

This document was ported to AsciiDoc by Tristano Ajmone and republished with the author’s permission under the Apache License v2.0 terms. Beside aesthetic tweaks and some marginal text changes, this document is a faithful reproduction of the original article on Cosmigo website.