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.

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 defined as procedure (percent: integer); stdcall;

May set error: yes

type TProgressCallback= procedure (percent: integer); stdcall;
typedef void (__stdcall *ProgressCallback)( int progress );

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.

Return value: the error message or nil/NULL.

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"

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.

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.

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.

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.

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

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.

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!

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.

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.

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.

Return value: the number of frames of the image/animation that is to be loaded
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.

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.

Return value: the RGB palette or nil 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.

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();

Is alpha data of the file to be read.

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

Return value: If the image contains alpha data then this function returns 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

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

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 and must not be used.
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

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.

May set error: no