freesave.ew is a Euphoria library that links to the freeimage.dll library to allow bitmaps to be saved in a small number of formats. It may be used in conjunction with the freedib library and win32lib for loading bitmaps but does not require them. However, almost all testing has been done using freedib and the version of win32lib found on the archive as win32lib4.zip by Mike. The installation assumes that freeimage.dll is already on the system, as would be the case if freedib has been installed.
This library has been tested mostly using Euphoria version 4 beta 2. A brief test using Euphoria version 3.1 and win32lib was also successful.
Thanks go to:
FreeSave has a constant that contains information about the version:
FreeSaveVersion, which is a sequence of length 4:
FreeSaveVersion[1] is the Major version (integer).
FreeSaveVersion[2] is the Minor version (integer).
FreeSaveVersion[3] is the Patch/Revision (integer).
FreeSaveVersion[4] is the release date (string sequence).
If the return code from SaveFreeDib is zero, an error message will have been saved as a sequence and may be obtained from the global variable named freeimage_error. A more direct report is not used because the error handler could also respond to errors from freedib which could cause problems with its return values.
If freedib is being used in conjunction with freesave, the error handler in freesave.ew will respond to errors in loadFreeDib as well and may store a message from FreeImage in freeimage_error. However, freeimage_error is not always set from an error in freedib. When using both freedib and freesave, the variable freeimage_error is cleared on entry to SaveFreeDib but not on entry to loadFreeImage. Therefore, if it is intended to continue after an error, freeimage_error should be cleared before calling loadFreeImage.
You can save a bitmap with several file formats with the SaveFreeDib function. This function returns 0 if the bitmap couldn't be saved, or a non-zero integer if the save appeared to be successful. The following file formats are supported: BMP, JPEG, PNG, TARGA, TIFF, XPM, PPM, ICO. Most of these are not supported for all values of bits per pixel which are valid for the format.
integer status status = SaveFreeDib(dib, filename, bpp, flags) -- saves the bitmapExample (using win32lib):
integer status status = SaveFreeDib(getHandle(pixmap_id), filename, 0, 0) -- saves a Pixmap if status = 0 then -- couldn't save the Pixmap abort(0) -- A bit drastic, but only an example. end if
| object | dib | The Windows handle of a DIBsection or a sequence containing the Windows handle of a DIBsection as its first element. In the latter case, the remaining elements of the sequence are ignored. The function loadFreeDib in the FreeDib library returns such a sequence as its DIB. The Windows handle of a win32lib Pixmap or bitmap may be obtained by using getHandle(win32lib_id). |
|---|---|---|
| sequence | filename | The name of the file to be saved,
including a path if required. The file extension determines the format of the file, according to table 1 below. |
| integer | bpp | The number of bits per pixel (bit depth) to be used in the file. May be zero to indicate that the default should be used. The default is the same as that of the source bitmap unless it is not supported for the chosen format, in which case a prefered bit depth for that format will be used. |
| integer | flags | Optional encoder constants. Zero, the default, is recommended but alternative values may be found in the freesave.ew file. The encoder constants are documented in Table 4 of the FreeImage documentation. However, the latest version of freeimage has constants not yet included in freesave. |
| Format | File extensions | Description |
|---|---|---|
| JPEG | .jpg .jif .jpeg .jpe | Indpendent JPEG group - the most common image compression |
| BMP | .bmp | Windows or OS/2 bitmap file. No compression or run length compression |
| PNG | .png | JPEG Network Grapics. The best compression for the UK flags in the tests |
| TARGA | .tga .targa | Truevision TARGA files |
| TIFF | .tif .tiff | Tagged Image File Format. With or without various compressions |
| XPM | .xpm | X11 Pixmap format - uncompressed ASCII text. |
| PPM | .ppm | Portable pixelmap (24 bits per pixel) ASCII or Binary |
| ICO | .ico | Windows Icons: No attempt has been made to implement transparency |
| GIF | .gif | ** Currently refused by freesave because it saves an incorrect image ** |
The program TestFreeSave.exw was used for a brief test of the capabilities and
limitations of the freesave library.
To run this requires the libraries win32lib and freedib,
neither of which is included in this distribution.
The program draws a United Kingdom flag, commonly known as the Union Jack.
The program provides its own instructions for its use.
SaveFreeDib was originally written to save a display that was created by a program, using compression. There was no prior bitmap input, so FreeDib was not required at that stage and it was written as a separate library. However, I could not link to FreeImage until I had found out how it was done in FreeDib.
On seeing a request from the Euphoria forum, I decided that I should document it and try to test it a little more thoroughly so that I could offer it. Testing has been fairly minimal and there can be no guarantees that it will be useful.
There is no reason why it could not be combined with freedib, but it would not then be in its original location and, in any case, I did not want to take the liberty of doing so. However, anyone is welcome to take liberties with this offering.