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.

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.
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
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
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. In that case the plugin is added in dialogs used when loading color palettes.

Control

Return value If the plugin supports palette reading then this function must return true
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 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.
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. It is only called if canExtractPalette returns
true.

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!
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 of image data is finished. Upon call the plugin must then close the file that was processed and do other internally required clean up.
It is also called if there was an error during read and write.

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 san-animation.dll and sim-image.dll from the corresponding Release sub-folder of the just downloaded and extracted zip to the plugins sub-folder 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.