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

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.
This only works with the registered version. The Free Edition does not load file i/o plugins.

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.

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 yes

getErrorMessage()

function getErrorMessage: PChar; stdcall;
char* __stdcall getErrorMessage();

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.

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

isWriteTrue ColorSupported()

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 io 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 yes

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 yes

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: Pointer; delayMs: word ): boolean; stdcall;
bool __stdcall writeNextImage( unsigned char* colorFrame, unsigned char* colorFramePalette, unsigned char* alphaFrame, unsigned char* alphaFramePalette, 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 Sample Sources

To see plugins working you can copy the precomiled 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

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

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