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.
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 |
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
|
Control
| Return value | none |
| May set error | no |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 SourcesTo 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.