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

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.

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.

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 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”

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.

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.

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

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

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.

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

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.