FreeImage Library
The FreeImage module is a BlitzMax wrapper for the open source FreeImage library.
It adds support for the following image formats : GIF, BMP, DDS, EXR, HDR, ICO, IFF, JNG, JPG, JPEG 2000, KOALA, LBM, Kodak, MNG, PCS, PBM, PGM, PNG, PPM, Photoshop (PSD), Fax G3, SGI, RAS, TARGA, TIFF, WBMP, XBM and XPM.
Requirements
The FreeImage source compiles directly into the module so you have no external requirements.
Basic Usage
If you don't need anything other than an image loader, you just need to Import the module and use LoadPixmap as normal :
Import BaH.FreeImage
Local pixmap:TPixmap = LoadPixmap("myimage.gif")
The module will determine if the image is one of the above formats and load it accordingly.
Advanced Usage
The FreeImage module can also be used to load, convert and manipulate images. You can do this via the LoadFreeImage function.
Import BaH.FreeImage
Local image:TFreeImage = LoadFreeImage("myimage.gif")
TFreeImage has a selection of fields and methods that enable you to get information about the image, and manipulate it in various ways.
Image manipulation
This section explains what some of the advanced functionality does.
Note : The FreeImage module creates it's own displayable copy of an image so that the original data remains intact. The module creates
this display image in a format compatible with TPixmap, upsampling or downsampling as appropriate.
Conversion Methods
The following methods make it possible to convert a bitmap from one bit depth to another.
Tone Mapping
Tone mapping operators are used to compress a large range of pixel luminances into a smaller range that is suitable for display on devices with limited dynamic range (e.g. display devices such as CRTs or LCDs and print media).
In principle this problem is simple: we need to turn an image with a large range of numbers into an image containing integers in the range of 0 to 255 such that we can display it on a printer or a monitor. This suggests linear scaling as a possible solution. However, this approach is flawed because details in the light or dark areas of the image will be lost due to subsequent quantization, and the displayed image will therefore not be perceived the same as the scene that was photographed. For this reason, more elaborate algorithms, called tone mapping operators, have been proposed to accurately render High Dynamic Range images.
Rotation and Flipping
Upsampling / Downsampling
Color Manipulation
FreeImage uses the RGB(A) color model to represent color images in memory. A 8-bit greyscale image has a single channel, often called the black channel. A 24-bit image is made up of three 8-bit channels: one for each of the red, green and blue colors. For 32-bit images, a fourth 8-bit channel, called alpha channel, is used to create and store masks, which let you manipulate, isolate, and protect specific parts of an image. Unlike the others channels, the alpha channel doesn’t convey color information, in a physical sense.
Color manipulation functions used in FreeImage allow you to modify the histogram of a specific channel. This transformation is known as a point operation, and may be used to adjust brightness, contrast or gamma of an image, to perform image enhancement (e.g. histogram equalization, non-linear contrast adjustment) or even to invert or threshold an image.
Currently, the following channels are defined in FreeImage:
Channel | Description |
FICC_RGB | Function applies to red, green and blue channels |
FICC_RED | Function applies to red channel only |
FICC_GREEN | Function applies to green channel only |
FICC_BLUE | Function applies to blue channel only |
FICC_ALPHA | Function applies to alpha channel only |
FICC_BLACK | Function applies to black channel |
FICC_REAL | Complex images: function applies to the real part |
FICC_IMAG | Complex images: function applies to the imaginary part |
FICC_MAG | Complex images: function applies to the magnitude |
FICC_PHASE | Complex images: function applies to the phase |
Available methods :
Functions Summary
Types Summary
Functions
Function LoadAnimFreeImage:TImage(filename:String, flags:Int = -1, rMask:Int = 0, gMask:Int = 0, bMask:Int = 0) |
Returns | A TImage object or Null if not found or not a valid multi-page format. |
Description | Loads a multi-page image into a TImage object. |
Information | See LoadImage for valid flags values. |
Function LoadFreeImage:TFreeImage( url:Object ) |
Returns | A TFreeImage object or Null if not found or not a valid image format. |
Description | Loads an image into a TFreeImage object. |
Function LoadMultiFreeImage:TMultiFreeImage( filename:String, readOnly:Int = True ) |
Returns | A TMultiFreeImage object or Null if not found or not a valid multi-page format. |
Description | Loads a multi-page image into a TMultiFreeImage object. |
Function SetFreeImageErrorHandler(callback(imageFormat:Int, message:String)) |
Description | Set the user-defined error callback function. |
Types
Type TFreeImage |
Description | A FreeImage image. |
Information | The base type for loading and manipulating images with FreeImage. |
Methods Summary |
adjustBrightness |
Adjusts the brightness by a certain amount.
|
adjustColors |
|
adjustConstrast |
Adjusts the contrast by a certain amount.
|
adjustCurve |
|
adjustGamma |
Performs a Gamma correction.
|
clone |
Makes an exact reproduction of an existing image, including metadata and attached profile, if any.
|
colorQuantize |
Quantizes a high-color 24-bit bitmap to an 8-bit palette color bitmap.
|
convertTo16Bits555 |
Converts an image to 16 Bits, where each pixel has a color pattern of 5 bits red, 5 bits green and 5 bits blue.
|
convertTo16Bits565 |
Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 6 bits green and 5 bits blue.
|
convertTo24Bits |
Converts an image to 24 Bits.
|
convertTo32Bits |
Converts an image to 32 Bits.
|
convertTo4Bits |
Converts an image to 4 Bits.
|
convertTo8Bits |
Converts an image to 8 Bits.
|
convertToGreyscale |
Converts an image to 8-bit greyscale with a linear ramp.
|
convertToRGBF |
Converts an image to RGBF (RGB 32Bit Float).
|
convertToType |
Converts an image of any type to type destType.
|
copy |
Copy a sub part of the image.
|
dither |
Converts image to a 1-bit monochrome bitmap using a dithering algorithm.
|
enlargeCanvas |
Enlarges or shrinks an image selectively per side and fills newly added areas with the specified background color.
|
flipHorizontal |
Flip the image horizontally along the vertical axis.
|
flipVertical |
Flip the image vertically along the horizontal axis.
|
getBackgroundColor |
|
getChannel |
Retrieves the red, green, blue or alpha channel of an image.
|
getMetadataCount |
Returns the number of tags contained in the model metadata model attached to the image.
|
getPixelColor |
|
getPixmap |
Gets the current pixmap for the image.
|
GetScanline |
Gets a memory pointer to the first pixel of a scanline.
|
hasBackgroundColor |
Returns TRUE when the image has a file background color, FALSE otherwise.
|
invert |
Inverts each pixel.
|
makeThumbnail |
Creates a thumbnail so that the output fits inside a square of maxPixelSize, keeping aspect ratio.
|
metadata |
Returns a list enumerator for the metadata attached to this image.
|
paste |
Alpha blend or combine a sub part image with the image.
|
preMultiplyWithAlpha |
Pre-multiplies the 32-bit image's red-, green- and blue channels with its alpha channel for to be used with the Windows GDI function AlphaBlend().
|
rescale |
Resamples the image to the desired destination width and height using the specified filter.
|
rotate |
Rotates a standard image (1-, 8-bit greyscale or a 24-, 32-bit color), a RGB(A)16 or RGB(A)F image by means of 3 shears.
|
rotateEx |
Performs rotation and / or translation of an image using 3rd order (cubic) B-Spline.
|
save |
Saves the image to url, which can be a filename or Stream.
|
setBackgroundColor |
|
setMetadata |
Attaches a new FreeImage tag to a dib.
|
setPixelColor |
|
threshold |
Converts image to a 1-bit monochrome bitmap using a threshold t between [0..255].
|
tmoDrago03 |
Converts a High Dynamic Range image to a 24-bit RGB image using a global operator based on logarithmic compression of luminance values, imitating the human response to light.
|
tmoReinhard05 |
Converts a High Dynamic Range image to a 24-bit RGB image using a global operator inspired by photoreceptor physiology of the human visual system.
|
toneMapping |
Converts a High Dynamic Range image (48-bit RGB or 96-bit RGBF) to a 24-bit RGB image, suitable for display.
|
Field bitsPerPixel:Int |
Description | Bits per pixel. |
Field height:Int |
Description | The image height. |
Field paletteSize:Int |
Description | Image palette size, if appropriate. |
Field pitch:Int |
Description | The image pitch. |
Field width:Int |
Description | The image width. |
Method adjustBrightness(percentage:Double) |
Description | Adjusts the brightness by a certain amount. |
Information | The percentage should be between -100 and 100, where a value of 0 means no change,
less than 0 makes the image darker, and greater than 0 makes the image lighter. |
Method adjustColors:Int(brightness:Double, contrast:Double, Gamma:Double, invert:Int = False) |
Method adjustConstrast(percentage:Double) |
Description | Adjusts the contrast by a certain amount. |
Information | The percentage should be between -100 and 100, where a value of 0 means no change,
less than 0 decreases the contrast, and greater than 0 increases the contrast. |
Method adjustCurve:Int(lut:Byte[], channel:Int) |
Method adjustGamma(Gamma:Double) |
Description | Performs a Gamma correction. |
Information | A gamma value of 1, leaves the image alone, less than 1 darkens it, and greater than 1 lightens it. |
Method clone:TFreeImage() |
Returns | A clone of the image. |
Description | Makes an exact reproduction of an existing image, including metadata and attached profile, if any. |
Method colorQuantize:TFreeImage(quantize:Int) |
Returns | The converted image. |
Description | Quantizes a high-color 24-bit bitmap to an 8-bit palette color bitmap. |
Information | quantize specifies the color reduction algorithm to be used:
Constant | Description |
FIQ_WUQUANT | Xiaolin Wu color quantization algorithm |
FIQ_NNQUANT | NeuQuant neural-net quantization algorithm by Anthony Dekker |
|
Method convertTo16Bits555:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 16 Bits, where each pixel has a color pattern of 5 bits red, 5 bits green and 5 bits blue. |
Method convertTo16Bits565:TFreeImage() |
Returns | The converted image. |
Description | Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 6 bits green and 5 bits blue. |
Method convertTo24Bits:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 24 Bits. |
Method convertTo32Bits:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 32 Bits. |
Method convertTo4Bits:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 4 Bits. |
Information | If the image was a high-color bitmap (16, 24 or 32-bit) or if it was a monochrome or greyscale
bitmap (1 or 8-bit), the end result will be a greyscale bitmap, otherwise (1-bit palletised bitmaps)
it will be a palletised bitmap. A clone of the input bitmap is returned for 4-bit bitmaps. |
Method convertTo8Bits:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 8 Bits. |
Information | If the image was a high-color bitmap (16, 24 or 32-bit) or if it was a monochrome or greyscale bitmap
(1 or 4-bit), the end result will be a greyscale bitmap, otherwise (1 or 4-bit palletised bitmaps)
it will be a palletised bitmap. A clone of the input bitmap is returned for 8-bit bitmaps. |
Method convertToGreyscale:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to 8-bit greyscale with a linear ramp. |
Information | Contrary to the convertTo8Bits method, 1-, 4- and 8-bit palletised images are correctly converted. |
Method convertToRGBF:TFreeImage() |
Returns | The converted image. |
Description | Converts an image to RGBF (RGB 32Bit Float). |
Method convertToType:TFreeImage(destType:Int, scaleLinear:Int = True) |
Description | Converts an image of any type to type destType. |
Information | When destType is equal to FIT_BITMAP, the method calls ConvertToStandardType. Otherwise, conversion is
done using standard C language casting convention. When a conversion is not allowed, a NULL value is returned
and an error message is thrown (it can be caught using FreeImage_SetOutputMessage). The following conversions
are currently allowed by the library (other conversions may be added easily if needed):
|
Constant | Description |
FIT_UNKNOWN | unknown type |
FIT_BITMAP | standard image : 1-, 4-, 8-, 16-, 24-, 32-bit |
FIT_UINT16 | array of unsigned short : unsigned 16-bit |
FIT_INT16 | array of short : signed 16-bit |
FIT_UINT32 | array of unsigned long : unsigned 32-bit |
FIT_INT32 | array of long : signed 32-bit |
FIT_FLOAT | array of float : 32-bit IEEE floating point |
FIT_DOUBLE | array of double : 64-bit IEEE floating point |
FIT_COMPLEX | array of FICOMPLEX : 2 x 64-bit IEEE floating point |
FIT_RGB16 | 48-bit RGB image : 3 x 16-bit |
FIT_RGBA16 | 64-bit RGBA image : 4 x 16-bit |
FIT_RGBF | 96-bit RGB float image : 3 x 32-bit IEEE floating point |
FIT_RGBAF | 128-bit RGBA float image : 4 x 32-bit IEEE floating point |
Method copy:TFreeImage(x0:Int, y0:Int, x1:Int, y1:Int) |
Returns | The copied image if successful, or Null otherwise. |
Description | Copy a sub part of the image. |
Information | ( x0, y0 ) represents the top left of the rectangle to copy. ( x1, y1 ) the bottom right. |
Method dither:TFreeImage(algorithm:Int) |
Description | Converts image to a 1-bit monochrome bitmap using a dithering algorithm. |
Information | algorithm specifies the dithering algorithm to be used.
The function first converts the image to a 8-bit greyscale bitmap, then is dithered using one of the
following algorithms:
Algorithm | Description |
FID_FS | Floyd & Steinberg error diffusion algorithm |
FID_BAYER4x4 | Bayer ordered dispersed dot dithering (order 2 - 4x4 -dithering matrix) |
FID_BAYER8x8 | Bayer ordered dispersed dot dithering (order 3 - 8x8 -dithering matrix) |
FID_CLUSTER6x6 | Ordered clustered dot dithering (order 3 - 6x6 matrix) |
FID_CLUSTER8x8 | Ordered clustered dot dithering (order 4 - 8x8 matrix) |
FID_CLUSTER16x16 | Ordered clustered dot dithering (order 8 - 16x16 matrix) |
|
Method enlargeCanvas:TFreeImage(_left:Int, _top:Int, _right:Int, _bottom:Int, color:TRGBQuad, options:Int) |
Description | Enlarges or shrinks an image selectively per side and fills newly added areas with the specified background color. |
Method flipHorizontal() |
Description | Flip the image horizontally along the vertical axis. |
Method flipVertical() |
Description | Flip the image vertically along the horizontal axis. |
Method getBackgroundColor:TRGBQuad() |
Method getChannel:TFreeImage(channel:Int) |
Returns | The extracted channel or Null otherwise. |
Description | Retrieves the red, green, blue or alpha channel of an image. |
Method getPixelColor:TRGBQuad(x:Int, y:Int) |
Method getPixmap:TPixmap() |
Description | Gets the current pixmap for the image. |
Information | Note: Once the image data has changed, you should acquire a new pixmap via this method since
pixmap data is likely to be invalidated. |
Method GetScanline:Byte Ptr(scanline:Int) |
Description | Gets a memory pointer to the first pixel of a scanline. |
Information | For direct access to the freeimage pixel data, can be used to read or write raw data from the freeimage bitmap.
Make sure you know the pixel format of the bitmap before using it. |
Method hasBackgroundColor:Int() |
Description | Returns TRUE when the image has a file background color, FALSE otherwise. |
Method invert() |
Description | Inverts each pixel. |
Method makeThumbnail:TFreeImage(maxPixelSize:Int) |
Description | Creates a thumbnail so that the output fits inside a square of maxPixelSize, keeping aspect ratio. |
Information | Downsampling is done using a bilinear filter (see rescale). |
Method paste:Int(source:TFreeImage, x:Int, y:Int, alpha:Int) |
Returns | True if successful, or False otherwise. |
Description | Alpha blend or combine a sub part image with the image. |
Information | The images are alpha blended if alpha is between 0 and 255. For values over 255, the two images
are combined. |
Method preMultiplyWithAlpha:Int() |
Description | Pre-multiplies the 32-bit image's red-, green- and blue channels with its alpha channel for to be used with the Windows GDI function AlphaBlend(). |
Information | The transformation changes the red-, green- and blue channels according to the following equation:
channel(x, y) = channel(x, y) * alpha_channel(x, y) / 255
The method returns True on success, False otherwise (e.g. when the bitdepth of the source dib cannot be handled). |
Method rescale:TFreeImage(width:Int, height:Int, filter:Int) |
Description | Resamples the image to the desired destination width and height using the specified filter. |
Information | The following filters can be used for resampling :
Constant | Description |
FILTER_BOX | Box, pulse, Fourier window, 1st order (constant) b-spline |
FILTER_BICUBIC | Mitchell Netravali's two-param cubic filter |
FILTER_BILINEAR | Bilinear filter |
FILTER_BSPLINE | 4th order (cubic) b-spline |
FILTER_CATMULLROM | Catmull-Rom spline, Overhauser spline |
FILTER_LANCZOS3 | Lanczos3 filter |
|
Method rotate:TFreeImage(angle:Double, color:TRGBQuad = Null) |
Description | Rotates a standard image (1-, 8-bit greyscale or a 24-, 32-bit color), a RGB(A)16 or RGB(A)F image by means of 3 shears. |
Information | The angle of rotation is specified by the angle parameter in degrees. Rotation occurs around the center of the image area.
Rotated image retains size and aspect ratio of source image (destination image size is usually bigger), so that this method
should be used when rotating an image by 90, 180 or 270 degrees. |
Method rotateEx:TFreeImage(angle:Double, xShift:Double, yShift:Double, xOrigin:Double, yOrigin:Double, useMask:Int) |
Description | Performs rotation and / or translation of an image using 3rd order (cubic) B-Spline. |
Information | The rotated image will have the same width and height as the source image.
The angle of rotation is specified in degrees.
Horizontal and Vertical image translations (in pixels) are specified by the xShift and yShift
parameters.
Rotation occurs around the center specified by xOrigin and yOrigin.
When useMask is True, the irrelevant part of the image is set to a black colour, otherwise,
a mirroring technique is used to fill irrelevant pixels. |
Method save:Int(url:Object, format:Int, flags:Int = 0) |
Returns | True if successful, or False otherwise. |
Description | Saves the image to url, which can be a filename or Stream. |
Information | format defines the image type to save.
flags can be used to change the behaviour or enable a feature for saving. Or leave out for default behaviour.
A list of valid image formats and optional flags follows:
Format | Flag | Description |
FIF_BMP Windows Bitmap | BMP_DEFAULT | Save without any compression |
| BMP_SAVE_RLE | Compress the bitmap using RLE when saving |
FIF_GIF Graphics Interchange Format | | |
FIF_HDR High Dynamic Range | | |
FIF_ICO Windows Icon | | |
FIF_JPEG JPEG - JFIF Compliant | JPEG_DEFAULT | Saves with good quality (75:1) |
| JPEG_QUALITYSUPERB | Saves with superb quality (100:1) |
| JPEG_QUALITYGOOD | Saves with good quality (75:1) |
| JPEG_QUALITYNORMAL | Saves with normal quality (50:1) |
| JPEG_QUALITYAVERAGE | Saves with average quality (25:1) |
| JPEG_QUALITYBAD | Saves with bad quality (10:1) |
| Int X in [0..100] | Save with quality X:1 |
| JPEG_PROGRESSIVE | Saves as a progressive JPEG file (use | to combine with JPEG quality flags) |
FIF_PBM Portable Bitmap | PNM_DEFAULT | Saves the bitmap as a binary file |
| PNM_SAVE_RAW | Saves the bitmap as a binary file |
| PNM_SAVE_ASCII | Saves the bitmap as an ASCII file |
FIF_PGM Portable Greymap | PNM_DEFAULT | Saves the bitmap as a binary file |
| PNM_SAVE_RAW | Saves the bitmap as a binary file |
| PNM_SAVE_ASCII | Saves the bitmap as an ASCII file |
FIF_PNG Portable Network Graphics | | |
FIF_PPM Portable Pixelmap | PNM_DEFAULT | Saves the bitmap as a binary file |
| PNM_SAVE_RAW | Saves the bitmap as a binary file |
| PNM_SAVE_ASCII | Saves the bitmap as an ASCII file |
FIF_TARGA Truevision Targa | | |
FIF_TIFF Tagged Image File Format | TIFF_DEFAULT | Save using CCITTFAX4 compression for 1-bit bitmaps and LZW compression for any other bitmaps |
| TIFF_CMYK | Stores tags for separated CMYK (use | to combine with TIFF compression flags) |
| TIFF_PACKBITS | Save using PACKBITS compression. |
| TIFF_DEFLATE | Save using DEFLATE compression (also known as ZLIB compression) |
| TIFF_ADOBE_DEFLATE | Save using ADOBE DEFLATE compression |
| TIFF_NONE | Save without any compression |
| TIFF_CCITTFAX3 | Save using CCITT Group 3 fax encoding |
| TIFF_CCITTFAX4 | Save using CCITT Group 4 fax encoding |
| TIFF_LZW | Save using LZW compression |
| TIFF_JPEG | Save using JPEG compression (8-bit greyscale and 24-bit only. Default to LZW for other bitdepths). |
FIF_WBMP Wireless Bitmap | | |
FIF_XPM X11 Pixmap Format | | |
|
Method setBackgroundColor:Int(color:TRGBQuad) |
Method setPixelColor(x:Int, y:Int, color:TRGBQuad) |
Method threshold:TFreeImage(t:Byte) |
Description | Converts image to a 1-bit monochrome bitmap using a threshold t between [0..255]. |
Information | The method first converts the bitmap to a 8-bit greyscale bitmap. Then, any brightness level
that is less than t is set to zero, otherwise to 1. For 1-bit input bitmaps, the method clones the
input bitmap and builds a monochrome palette. |
Method tmoDrago03:TFreeImage(Gamma:Double = 2.2, exposure:Double = 0) |
Description | Converts a High Dynamic Range image to a 24-bit RGB image using a global operator based on logarithmic compression of luminance values, imitating the human response to light. |
Information | A bias power function is introduced to adaptively vary logarithmic bases, resulting in good preservation
of details and contrast.
Upon entry, gamma (where gamma > 0) is a gamma correction that is applied after the tone mapping.
A value of 1 means no correction. The default 2.2 value, used in the original author's paper, is
recommended as a good starting value.
The exposure parameter is an exposure scale factor allowing users to adjust the brightness
of the output image to their displaying conditions. The default value (0) means that no correction
is applied. Higher values will make the image lighter whereas lower values make the image darker. |
Method tmoReinhard05:TFreeImage(intensity:Double = 0, contrast:Double = 0) |
Description | Converts a High Dynamic Range image to a 24-bit RGB image using a global operator inspired by photoreceptor physiology of the human visual system. |
Information | Upon entry, the intensity parameter, in the range [-8, 8], controls the overall image intensity
The default value 0 means no correction. Higher values will make the image lighter whereas lower values
make the image darker.
The contrast parameter, in the range [0.3, 1.0], controls the overall image contrast. When using the default
value (0), this parameter is calculated automatically. |
Method toneMapping:TFreeImage(algorithm:Int, param1:Double, param2:Double) |
Description | Converts a High Dynamic Range image (48-bit RGB or 96-bit RGBF) to a 24-bit RGB image, suitable for display. |
Information | The meaning of param1 and param2 depends on the value of algorithm. See tmoDrago03 and tmoReinhard05
for details.
Algorithm | Description |
FITMO_DRAGO03 | Adaptive logarithmic mapping |
FITMO_REINHARD05 | Dynamic range reduction inspired by photoreceptor physiology |
FITMO_FATTAL02 | Gradient domain high dynamic range compression |
|
Function CreateFromPixmap:TFreeImage(pixmap:TPixmap) |
Description | Creates a TFreeImage from a pixmaps' pixel data. |
Function JPEGCrop:Int(source:String, dest:String, _left:Int, _top:Int, _right:Int, _bottom:Int) |
Type TFreeImageTag |
Description | Stores metadata information. |
Information | The notion of tag originates from the TIFF specification and because of its universality, it is widely used to store
metadata information in a file.
FreeImage provides an enhanced version of the standard TIFF or Exif tag structure.
Given a metadata model (e.g. Exif, Exif GPS, IPTC/NAA), the tag key (or tag field name) is
unique inside this data model. This uniqueness allows FreeImage to use this key to index the
tag inside a hash table, in order to speed up tag access. Whenever you store a tag inside a
metadata model, you thus need to provide a unique key with the tag to store.
A FreeImage tag may be used to store any kind of data (e.g. strings, integers, doubles,
rational numbers, etc.). The complete list of data type supported by FreeImage is given in
Table 12. For example, when the tag data type indicates a double and the tag count is 8, then
the tag value is an array of 8 doubles. Its length should be 64 bytes (8 x sizeof(double)). If the
tag data type indicates a rational and the length is 48 bytes, then there are (48 bytes / (2 x 4-bytes)) = 6 rational values in the tag.
As for ASCII strings, the value of the count part of an ASCII tag entry includes the NULL.
|
Methods Summary |
clone |
Creates and returns a copy of this tag.
|
Create |
Creates a new FreeImage tag.
|
getCount |
Returns the number of components in the tag (in tag type units).
|
getDescription |
Returns the tag description if available, returns NULL otherwise.
|
getID |
Returns the tag ID if available, returns 0 otherwise.
|
getKey |
Returns the tag field name (unique inside a metadata model).
|
getLength |
Returns the length of the tag value in bytes.
|
getType |
Returns the tag data type.
|
getValue |
Returns the tag value.
|
setCount |
Sets the number of data in the tag (always required, expressed in tag type unit).
|
setDescription |
Sets the (usually optional) tag description.
|
setID |
Sets the (usually optional) tad ID.
|
setKey |
Sets the tag field name (always required, must be unique inside a metadata model).
|
setLength |
Sets the length of the tag value, in bytes (always required).
|
setType |
Sets the tag data type (always required).
|
setValue |
Sets the tag value (always required).
|
tagToString |
Converts the tag to a string that represents the interpreted tag value.
|
Functions Summary |
CreateTag |
Creates a new FreeImage tag.
|
Method clone:TFreeImageTag() |
Description | Creates and returns a copy of this tag. |
Method Create:TFreeImageTag() |
Description | Creates a new FreeImage tag. |
Information | Tag creation is only needed when you use the FreeImage::setMetadata method. |
Method getCount:Int() |
Description | Returns the number of components in the tag (in tag type units). |
Information | For example, when the tag data type indicates a double (i.e. a FIDT_DOUBLE type) and the tag count is 8, then the tag
value is an array of 8 doubles. |
Method getDescription:String() |
Description | Returns the tag description if available, returns NULL otherwise. |
Method getID:Int() |
Description | Returns the tag ID if available, returns 0 otherwise. |
Method getKey:String() |
Description | Returns the tag field name (unique inside a metadata model). |
Method getLength:Int() |
Description | Returns the length of the tag value in bytes. |
Method getType:Int() |
Description | Returns the tag data type. |
Information | One of :
Constant | Description |
FIDT_NOTYPE | Placeholder (do not use this type) |
FIDT_BYTE | 8-bit unsigned integer |
FIDT_ASCII | 8-bit byte that contains a 7-bit ASCII code; the last byte must be NUL (binary zero) |
FIDT_SHORT | 16-bit (2-byte) unsigned integer |
FIDT_INT | 32-bit (4-byte) unsigned integer |
FIDT_RATIONAL | Two Ints: the first represents the numerator of a fraction; the second, the denominator |
FIDT_SBYTE | An 8-bit signed (twos-complement) integer |
FIDT_UNDEFINED | An 8-bit byte that may contain anything, depending on the definition of the field. |
FIDT_SSHORT | A 16-bit (2-byte) signed (twos-complement) integer |
FIDT_SINT | A 32-bit (4-byte) signed (twos-complement) integer |
FIDT_SRATIONAL | Two SLONG’s: the first represents the numerator of a fraction, the second the denominator |
FIDT_FLOAT | Single precision (4-byte) IEEE format |
FIDT_DOUBLE | Double precision (8-byte) IEEE format |
FIDT_IFD FIDT_IFD | data type is identical to INT, but is only used to store offsets |
FIDT_PALETTE | 32-bit (4-byte) RGBQUAD |
|
Method getValue:Byte Ptr() |
Description | Returns the tag value. |
Information | It is up to you to interpret the returned pointer correctly, according to the results of getType and getCount. |
Method setCount:Int(count:Int) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the number of data in the tag (always required, expressed in tag type unit). |
Method setDescription:Int(description:String) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the (usually optional) tag description. |
Information | The tag description is never stored in a file. FreeImage maintains an internal table for
all known tags, together with their description when available. Whenever you read a
known tag, the library is able to give the tag description (provided that the tag is known
by the library) using getDescription. However, provide a tag description when storing a tag. |
Method setID:Int(id:Int) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the (usually optional) tad ID. |
Method setKey:Int(key:String) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the tag field name (always required, must be unique inside a metadata model). |
Method setLength:Int(length:Int) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the length of the tag value, in bytes (always required). |
Method setType:Int(tagType:Int) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the tag data type (always required). |
Method setValue:Int(value:Byte Ptr) |
Returns | TRUE if successful and returns FALSE otherwise. |
Description | Sets the tag value (always required). |
Information | This must be called after the tag data type, tag count and tag length have been filled. Otherwise, you will
be unable to successfully call FreeImage::setMetadata. |
Method tagToString:String(model:Int, make:String = Null) |
Description | Converts the tag to a string that represents the interpreted tag value. |
Information | The tag value is interpreted according to the metadata model specification. For example, consider
a tag extracted from the FIMD_EXIF_EXIF metadata model, whose ID is 0x9209 and whose
key is "Flash". Then if the tag value is 0x0005, the function will return "Strobe return light not detected".
Upon entry, model is the metadata model from which the tag was extracted, tag is the
FreeImage tag to interpret and Make is the camera model. This last parameter is currently not
used by the library but will be used in the future to interpret the camera maker notes (FIMD_EXIF_MAKERNOTE metadata model). |
Function CreateTag:TFreeImageTag() |
Description | Creates a new FreeImage tag. |
Information | Tag creation is only needed when you use the FreeImage::setMetadata method. |
Type TMultiFreeImage |
Description | A multi-page image. |
Information | FreeImage currently supports GIF, TIFF and ICO multi-page image formats.
To modify a page in a multi-page image, it needs to be opened with readOnly set to False.
Use unlockPage to acquire a specific page image. Make your changes to it, and then use lockPage to
apply the changes.
When you close the multi-page image, the changes will be saved.
|
Methods Summary |
appendPage |
Appends a new page to the end of the image.
|
close |
Closes a previously opened multi-page image and, when the image was not opened read-only, applies any changes made to it.
|
deletePage |
Deletes the page on the given position.
|
getNext |
Gets the next page.
|
hasNext |
Returns True if there are more pages.
|
insertPage |
Inserts a new page before the given position.
|
lockPage |
Locks a page in memory for editing.
|
movePage |
Moves the source page to the position of the target page.
|
pageCount |
Returns the number of pages currently available in the multi-paged image.
|
reset |
Resets the internal page position back to the start (ie. zero).
|
toAnimImage |
Creates a TImage and fills the frames with all the pages from this TMultiFreeImage.
|
unlockPage |
Unlocks a previously locked page and gives it back to the multi-page engine.
|
Method appendPage(image:TFreeImage) |
Description | Appends a new page to the end of the image. |
Method close:Int() |
Description | Closes a previously opened multi-page image and, when the image was not opened read-only, applies any changes made to it. |
Method deletePage(page:Int) |
Description | Deletes the page on the given position. |
Method getNext:TFreeImage() |
Description | Gets the next page. |
Method hasNext:Int() |
Description | Returns True if there are more pages. |
Method insertPage(image:TFreeImage, page:Int) |
Description | Inserts a new page before the given position. |
Information | page has to be a number smaller than the current number of pages available. |
Method lockPage:TFreeImage(page:Int) |
Description | Locks a page in memory for editing. |
Information | The page can now be saved to a different file or inserted into another multi-page image.
When you are done with the image you must call unlockPage to give the page back to the multi-page image
and/or apply any changes made to the page. |
Method movePage:Int(source:Int, target:Int) |
Description | Moves the source page to the position of the target page. |
Information | Returns True on success, False on failure. |
Method pageCount:Int() |
Description | Returns the number of pages currently available in the multi-paged image. |
Method reset() |
Description | Resets the internal page position back to the start (ie. zero). |
Method toAnimImage:TImage(flags:Int = -1, rMask:Int = 0, gMask:Int = 0, bMask:Int = 0) |
Description | Creates a TImage and fills the frames with all the pages from this TMultiFreeImage. |
Information | The parameters are the same. |
Method unlockPage(image:TFreeImage, changed:Int = False) |
Description | Unlocks a previously locked page and gives it back to the multi-page engine. |
Information | When the changed parameter is True, the page is marked changed and the new page data is applied
in the multi-page image. |
Function Create:TMultiFreeImage(filename:String, format:Int) |
Description | Creates a new, empty, multi-page image. |
Information | Valid formats are : FIF_ICO, FIF_GIF, or FIF_TIFF. |
Function CreateFromFile:TMultiFreeImage(filename:String, readOnly:Int = True) |
Description | Creates a new TMultiFreeImage from the specified filename. |
Information | Set readOnly to False, if you intend making changes to pages. |
Method Create:TRGBQuad(r:Int, g:Int, b:Int, a:Int = 0) |
Method SetRGBA(r:Int, g:Int, b:Int, a:Int = 0) |
Module Information
Version | 1.06 |
License | Wrapper - MIT |
License | FreeImage - FreeImage Public License (FIPL) |
Copyright | Wrapper - 2007-2010 Bruce A Henderson |
Modserver | BRL |
History | 1.06 |
History | Updated to FreeImage 3.13.1. Adds PICT format. |
History | Added new methods. |
History | Added Metadata tag support. |
History | Fixed mac x86 rgba ordering. |
History | Fixed problem where original bitmap was used as the display bitmap, for greyscale images. |
History | Improved stream read/write. |
History | Added user error handler callback. |
History | 1.05 |
History | Fixed conversion issue with 4-bit paletted images. |
History | Fixed GC problems when loading large anim images. |
History | Fixed problem with creation of new multi-page images. |
History | 1.04 |
History | Fixed problem with TIFF images not loading if there are more than 1 alpha channel in the image. (fredborg) |
History | Added GetBitmap(), GetScanLine() and ConvertToRGBF() methods. (fredborg) |
History | Added GetFormatFromFile(), GetLoadFormats() and GetSaveFormats() helper functions. (fredborg) |
History | 1.03 |
History | Updated to FreeImage 3.10.0. Adds OpenEXR and OpenJPG(2000) formats. |
History | Win32 now compiles as a module, rather than using a DLL :-) |
History | Fixed colour problems when saving an image. |
History | Fixed seek->end not seeking from the end. |
History | Fixed multi-image bug where filename wasn't kept long enough. |
History | Fixed TIFF save issue. (A freeimage bug, most likely) |
History | Fixed win32 TIFF load issue. (Another freeimage bug, most likely) |
History | 1.02 |
History | Hacked MNG plugin to validate images using the .mng header. |
History | Re-applied internal LibPNG support. Do not Import Pub.Libpng |
History | Loaded TFreeImages bitmaps are now not y-flipped at load-time. Therefore when saving they should now be in the correct orientation. |
History | New TMultiFreeImage type for multi-page image support (gif, ico and tiff). |
History | New LoadAnimFreeImage() function to create a multi-frame TImage from a multi-page image. |
History | 1.01 |
History | Added CreateFromPixmap() function. |
History | Added colorQuantize, dither, threshold, toneMapping, tmoDrago03 and tmoReinhard05 methods. |
History | Added convertTo 4, 8, 16 methods. |
History | Added more documentation. |
History | 1.00 |
History | Initial Release. (FreeImage 3.9.3) |
CC_OPTS | -fexceptions |
CC_OPTS | -DPNG_iTXt_SUPPORTED |
CC_OPTS | -DHAVE_PROTOTYPES |
CC_OPTS | -DFREEIMAGE_LIB |
CC_OPTS | -DOPJ_STATIC |