00001 /** \file
00002 * \brief Image Manipulation
00003 *
00004 * See Copyright Notice in im_lib.h
00005 * $Id: im_image.h,v 1.2 2005/07/01 22:13:09 scuri Exp $
00006 */
00007
00008 #ifndef __IM_IMAGE_H
00009 #define __IM_IMAGE_H
00010
00011 #if defined(__cplusplus)
00012 extern "C" {
00013 #endif
00014
00015
00016 /** \defgroup imgclass imImage
00017 *
00018 * \par
00019 * Base definitions and functions for image representation. \n
00020 * Only the image processing operations depends on these definitions,
00021 * Image Storage and Image Capture are completely independent.
00022 * \par
00023 * You can also initialize a structure with your own memory buffer, see \ref imImageInit.
00024 * To release the structure without releasing the buffer,
00025 * set "data[0]" to 0 before calling imImageDestroy.
00026 * \par
00027 * See \ref im_image.h
00028 * \ingroup imagerep */
00029
00030
00031
00032 /** \brief imImage Structure Definition.
00033 *
00034 * \par
00035 * An image representation than supports all the color spaces, but no alpha channel,
00036 * planes are always unpacked and the orientation is always bottom up.
00037 * \ingroup imgclass */
00038 typedef struct _imImage
00039 {
00040 /* main parameters */
00041 int width; /**< Number of columns */
00042 int height; /**< Number of lines. */
00043 int color_space; /**< Color space descriptor. */
00044 int data_type; /**< Data type descriptor. */
00045
00046 /* secondary parameters */
00047 int depth; /**< Number of planes (ColorSpaceDepth) */
00048 int line_size; /**< Number of bytes per line in one plane (width * DataTypeSize) */
00049 int plane_size; /**< Number of bytes per plane. (line_size * height) */
00050 int size; /**< Number of bytes occupied by the image (plane_size * depth) */
00051 int count; /**< Number of pixels (width * height) */
00052
00053 /* image data */
00054 void** data; /**< Image data organized as a 2D matrix with several planes.
00055 But plane 0 is also a pointer to the full data. (data[i] = data[0] + i*plane_size) */
00056
00057 /* image attributes */
00058 long *palette; /**< Used when depth=1. Otherwise is NULL. */
00059 int palette_count; /**< The palette is always 256 colors allocated, but can have less colors used. */
00060
00061 void* attrib_table; /**< in fact is a imAttribTable, but we hide this here */
00062 } imImage;
00063
00064
00065 /** Creates a new image.
00066 * \ingroup imgclass */
00067 imImage* imImageCreate(int width, int height, int color_space, int data_type);
00068
00069 /** Initializes the image structure but does not allocates image data.
00070 * \ingroup imgclass */
00071 imImage* imImageInit(int width, int height, int color_space, int data_type, void* data_buffer, long* palette, int palette_count);
00072
00073 /** Destroys the image and frees the memory used.
00074 * image data is destroyed only if its data[0] is not NULL.
00075 * \ingroup imgclass */
00076 void imImageDestroy(imImage* image);
00077
00078 /** Changes the buffer size. Reallocate internal buffers if they are larger than original.
00079 * \ingroup imgclass */
00080 void imImageReshape(imImage* image, int width, int height);
00081
00082 /** Copy image data and attributes from one image to another. \n
00083 * Images must have the same size and type.
00084 * \ingroup imgclass */
00085 void imImageCopy(const imImage* src_image, imImage* dst_image);
00086
00087 /** Copy image data only one image to another. \n
00088 * Images must have the same size and type.
00089 * \ingroup imgclass */
00090 void imImageCopyData(const imImage* src_image, imImage* dst_image);
00091
00092 /** Creates a copy of the image.
00093 * \ingroup imgclass */
00094 imImage* imImageDuplicate(const imImage* image);
00095
00096 /** Creates a clone of the image. i.e. same attributes but ignore contents.
00097 * \ingroup imgclass */
00098 imImage* imImageClone(const imImage* image);
00099
00100 /** Changes an extended attribute. \n
00101 * The data will be internally duplicated. \n
00102 * If data is NULL the attribute is removed. \n
00103 * If count is -1 and data_type is IM_BYTE then data is zero terminated.
00104 * \ingroup imgclass */
00105 void imImageSetAttribute(imImage* image, const char* attrib, int data_type, int count, const void* data);
00106
00107 /** Returns an extended attribute. \n
00108 * Returns NULL if not found.
00109 * \ingroup imgclass */
00110 const void* imImageGetAttribute(const imImage* image, const char* attrib, int *data_type, int *count);
00111
00112 /** Returns a list of the attribute names. \n
00113 * "attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count.
00114 * \ingroup imgclass */
00115 void imImageGetAttributeList(const imImage* image, char** attrib, int *attrib_count);
00116
00117 /** Sets all image data to zero.
00118 * \ingroup imgclass */
00119 void imImageClear(imImage* image);
00120
00121 /** Indicates that the image can be viewed in common graphic devices.
00122 * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY.
00123 * \ingroup imgclass */
00124 int imImageIsBitmap(const imImage* image);
00125
00126 /** Changes the image palette.
00127 * This will destroy the existing palette and replace it with the given palette buffer.
00128 * \ingroup imgclass */
00129 void imImageSetPalette(imImage* image, long* palette, int palette_count);
00130
00131 /** Copies the image attributes from src to dst.
00132 * \ingroup imgclass */
00133 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image);
00134
00135 /** Returns 1 if the images match width and height. Returns 0 otherwise.
00136 * \ingroup imgclass */
00137 int imImageMatchSize(const imImage* image1, const imImage* image2);
00138
00139 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise.
00140 * \ingroup imgclass */
00141 int imImageMatchColor(const imImage* image1, const imImage* image2);
00142
00143 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise.
00144 * \ingroup imgclass */
00145 int imImageMatchDataType(const imImage* image1, const imImage* image2);
00146
00147 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise.
00148 * \ingroup imgclass */
00149 int imImageMatchColorSpace(const imImage* image1, const imImage* image2);
00150
00151 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise.
00152 * \ingroup imgclass */
00153 int imImageMatch(const imImage* image1, const imImage* image2);
00154
00155 /** Changes the image space from gray to binary by just changing color_space and the palette.
00156 * \ingroup imgclass */
00157 void imImageSetBinary(imImage* image);
00158
00159 /** Changes a gray data into a binary data.
00160 * \ingroup imgclass */
00161 void imImageMakeBinary(imImage *image);
00162
00163
00164
00165 /** \defgroup imgfile imImage Storage
00166 *
00167 * \par
00168 * Functions to simplify the process of reading and writting imImage structures.
00169 * \par
00170 * See \ref im_image.h
00171 * \ingroup file */
00172
00173
00174 /** Loads an image from an already open file. Returns NULL if failed. \n
00175 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00176 * index specifies the image number between 0 and image_count-1. \n
00177 * The returned imagem will be of the same color_space and data_type of the image in the file. \n
00178 * \ingroup imgfile */
00179 imImage* imFileLoadImage(imFile* ifile, int index, int *error);
00180
00181 /** Loads an image from an already open file. Returns NULL if failed. \n
00182 * This function assumes that the image in the file has the same parameters as the given image. \n
00183 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00184 * index specifies the image number between 0 and image_count-1. \n
00185 * The returned imagem will be of the same color_space and data_type of the image in the file. \n
00186 * \ingroup imgfile */
00187 void imFileLoadImageFrame(imFile* ifile, int index, imImage* image, int *error);
00188
00189 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00190 * The returned imagem will be always a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00191 * index specifies the image number between 0 and image_count-1. \n
00192 * Returns NULL if failed.
00193 * \ingroup imgfile */
00194 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error);
00195
00196 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00197 * This function assumes that the image in the file has the same parameters as the given image. \n
00198 * The imagem must be a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00199 * index specifies the image number between 0 and image_count-1. \n
00200 * Returns NULL if failed.
00201 * \ingroup imgfile */
00202 void imFileLoadBitmapFrame(imFile* ifile, int index, imImage* image, int *error);
00203
00204 /** Saves the image to an already open file. \n
00205 * This will call \ref imFileWriteImageInfo and \ref imFileWriteImageData. \n
00206 * Returns error code.
00207 * \ingroup imgfile */
00208 int imFileSaveImage(imFile* ifile, const imImage* image);
00209
00210 /** Loads an image from file. Open, loads and closes the file. \n
00211 * index specifies the image number between 0 and image_count-1. \n
00212 * Returns NULL if failed.
00213 * \ingroup imgfile */
00214 imImage* imFileImageLoad(const char* file_name, int index, int *error);
00215
00216 /** Loads an image from file, but forces the image to be a bitmap. Open, loads and closes the file. \n
00217 * index specifies the image number between 0 and image_count-1. \n
00218 * Returns NULL if failed.
00219 * \ingroup imgfile */
00220 imImage* imFileImageLoadBitmap(const char* file_name, int index, int *error);
00221
00222 /** Saves the image to file. Open, saves and closes the file. \n
00223 * Returns error code.
00224 * \ingroup imgfile */
00225 int imFileImageSave(const char* file_name, const char* format, const imImage* image);
00226
00227
00228
00229 /** Utility macro to draw the image in a CD library canvas.
00230 * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY.
00231 * \ingroup imgclass */
00232 #define imPutBitmap(_image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \
00233 { \
00234 if (_image->color_space == IM_RGB) \
00235 cdPutImageRectRGB(_image->width, _image->height, \
00236 (unsigned char*)_image->data[0], \
00237 (unsigned char*)_image->data[1], \
00238 (unsigned char*)_image->data[2], \
00239 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00240 else \
00241 cdPutImageRectMap(_image->width, _image->height, \
00242 (unsigned char*)_image->data[0], _image->palette, \
00243 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00244 }
00245
00246
00247 #if defined(__cplusplus)
00248 }
00249 #endif
00250
00251 #endif