00001 /** \file
00002 * \brief Image Manipulation
00003 *
00004 * See Copyright Notice in im_lib.h
00005 * $Id: im_image.h,v 1.7 2005/12/12 13:31:08 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 NULL 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,
00036 * but 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. image:Width() -> width: number [in Lua 5]. */
00042 int height; /**< Number of lines. image:Height() -> height: number [in Lua 5]. */
00043 int color_space; /**< Color space descriptor. image:ColorSpace() -> color_space: number [in Lua 5]. */
00044 int data_type; /**< Data type descriptor. image:DataType() -> data_type: number [in Lua 5]. */
00045 int has_alpha; /**< Indicates that there is an extra channel with alpha. image:HasAlpha() -> has_alpha: number [in Lua 5]. \n
00046 It will not affect the secondary parameters, i.e. the number of planes will be in fact depth+1. \n
00047 It is always 0 unless imImageAddAlpha is called, this is done in image load functions. */
00048
00049 /* secondary parameters */
00050 int depth; /**< Number of planes (ColorSpaceDepth) */
00051 int line_size; /**< Number of bytes per line in one plane (width * DataTypeSize) */
00052 int plane_size; /**< Number of bytes per plane. (line_size * height) */
00053 int size; /**< Number of bytes occupied by the image (plane_size * depth) */
00054 int count; /**< Number of pixels (width * height) */
00055
00056 /* image data */
00057 void** data; /**< Image data organized as a 2D matrix with several planes. \n
00058 But plane 0 is also a pointer to the full data. \n
00059 The remaining planes are: data[i] = data[0] + i*plane_size \n
00060 In Lua, indexing is possible using: image[plane][row][column] */
00061
00062 /* image attributes */
00063 long *palette; /**< Color palette. image:GetPalette() -> palette: imPalette [in Lua 5]. \n
00064 Used when depth=1. Otherwise is NULL. */
00065 int palette_count; /**< The palette is always 256 colors allocated, but can have less colors used. */
00066
00067 void* attrib_table; /**< in fact is an imAttribTable, but we hide this here */
00068 } imImage;
00069
00070
00071 /** Creates a new image.
00072 *
00073 * \verbatim im.ImageCreate(width: number, height: number, color_space: number, data_type: number) -> image: imImage [in Lua 5] \endverbatim
00074 * \ingroup imgclass */
00075 imImage* imImageCreate(int width, int height, int color_space, int data_type);
00076
00077 /** Initializes the image structure but does not allocates image data.
00078 * \ingroup imgclass */
00079 imImage* imImageInit(int width, int height, int color_space, int data_type, void* data_buffer, long* palette, int palette_count);
00080
00081 /** Creates a new image based on an existing one. \n
00082 * If the addicional parameters are -1, the given image parameters are used. \n
00083 * The image atributes always are copied.
00084 *
00085 * \verbatim im.ImageCreateBased(image: imImage, [width: number], [height: number], [color_space: number], [data_type: number]) -> image: imImage [in Lua 5] \endverbatim
00086 * The addicional parameters in Lua should be nil, and they can also be functions with the based image as a parameter.
00087 * \ingroup imgclass */
00088 imImage* imImageCreateBased(imImage* image, int width, int height, int color_space, int data_type);
00089
00090 /** Destroys the image and frees the memory used.
00091 * image data is destroyed only if its data[0] is not NULL.
00092 *
00093 * \verbatim im.ImageDestroy(image: imImage) [in Lua 5] \endverbatim
00094 * \verbatim image:Destroy() [in Lua 5] \endverbatim
00095 * \ingroup imgclass */
00096 void imImageDestroy(imImage* image);
00097
00098 /** Adds an alpha channel plane.
00099 *
00100 * \verbatim image:AddAlpha() [in Lua 5] \endverbatim
00101 * \ingroup imgclass */
00102 void imImageAddAlpha(imImage* image);
00103
00104 /** Changes the buffer size. Reallocate internal buffers if the new size is larger than the original.
00105 *
00106 * \verbatim image:Reshape(width: number, height: number) [in Lua 5] \endverbatim
00107 * \ingroup imgclass */
00108 void imImageReshape(imImage* image, int width, int height);
00109
00110 /** Copy image data and attributes from one image to another. \n
00111 * Images must have the same size and type.
00112 *
00113 * \verbatim image:Copy(dst_image: imImage) [in Lua 5] \endverbatim
00114 * \ingroup imgclass */
00115 void imImageCopy(const imImage* src_image, imImage* dst_image);
00116
00117 /** Copy image data only fom one image to another. \n
00118 * Images must have the same size and type.
00119 *
00120 * \verbatim image:CopyData(dst_image: imImage) [in Lua 5] \endverbatim
00121 * \ingroup imgclass */
00122 void imImageCopyData(const imImage* src_image, imImage* dst_image);
00123
00124 /** Creates a copy of the image.
00125 *
00126 * \verbatim image:Duplicate() -> new_image: imImage [in Lua 5] \endverbatim
00127 * \ingroup imgclass */
00128 imImage* imImageDuplicate(const imImage* image);
00129
00130 /** Creates a clone of the image. i.e. same attributes but ignore contents.
00131 *
00132 * \verbatim image:Clone() -> new_image: imImage [in Lua 5] \endverbatim
00133 * \ingroup imgclass */
00134 imImage* imImageClone(const imImage* image);
00135
00136 /** Changes an extended attribute. \n
00137 * The data will be internally duplicated. \n
00138 * If data is NULL the attribute is removed. \n
00139 * If count is -1 and data_type is IM_BYTE then data is zero terminated.
00140 *
00141 * \verbatim image:SetAttribute(attrib: string, data_type: number, data: table of numbers or string) [in Lua 5] \endverbatim
00142 * If data_type is IM_BYTE, as_string can be used as data.
00143 * \ingroup imgclass */
00144 void imImageSetAttribute(imImage* image, const char* attrib, int data_type, int count, const void* data);
00145
00146 /** Returns an extended attribute. \n
00147 * Returns NULL if not found.
00148 *
00149 * \verbatim image:GetAttribute(attrib: string, [as_string: boolean]) -> data: table of numbers or string, data_type: number [in Lua 5] \endverbatim
00150 * If data_type is IM_BYTE, as_string can be used to return a string instead of a table.
00151 * \ingroup imgclass */
00152 const void* imImageGetAttribute(const imImage* image, const char* attrib, int *data_type, int *count);
00153
00154 /** Returns a list of the attribute names. \n
00155 * "attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count.
00156 *
00157 * \verbatim image:GetAttributeList() -> data: table of strings [in Lua 5] \endverbatim
00158 * \ingroup imgclass */
00159 void imImageGetAttributeList(const imImage* image, char** attrib, int *attrib_count);
00160
00161 /** Sets all image data to zero.
00162 *
00163 * \verbatim image:Clear() [in Lua 5] \endverbatim
00164 * \ingroup imgclass */
00165 void imImageClear(imImage* image);
00166
00167 /** Indicates that the image can be viewed in common graphic devices.
00168 * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY.
00169 *
00170 * \verbatim image:IsBitmap() -> is_bitmap: boolean [in Lua 5] \endverbatim
00171 * \ingroup imgclass */
00172 int imImageIsBitmap(const imImage* image);
00173
00174 /** Changes the image palette.
00175 * This will destroy the existing palette and replace it with the given palette buffer.
00176 *
00177 * \verbatim image:SetPalette(palette: imPalette) [in Lua 5] \endverbatim
00178 * \ingroup imgclass */
00179 void imImageSetPalette(imImage* image, long* palette, int palette_count);
00180
00181 /** Copies the image attributes from src to dst.
00182 *
00183 * \verbatim image:CopyAttributes(dst_image: imImage) [in Lua 5] \endverbatim
00184 * \ingroup imgclass */
00185 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image);
00186
00187 /** Returns 1 if the images match width and height. Returns 0 otherwise.
00188 *
00189 * \verbatim image:MatchSize(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00190 * \ingroup imgclass */
00191 int imImageMatchSize(const imImage* image1, const imImage* image2);
00192
00193 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise.
00194 *
00195 * \verbatim image:MatchColor(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00196 * \ingroup imgclass */
00197 int imImageMatchColor(const imImage* image1, const imImage* image2);
00198
00199 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise.
00200 *
00201 * \verbatim image:MatchDataType(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00202 * \ingroup imgclass */
00203 int imImageMatchDataType(const imImage* image1, const imImage* image2);
00204
00205 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise.
00206 *
00207 * \verbatim image:MatchColorSpace(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00208 * \ingroup imgclass */
00209 int imImageMatchColorSpace(const imImage* image1, const imImage* image2);
00210
00211 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise.
00212 *
00213 * \verbatim image:Match(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00214 * \ingroup imgclass */
00215 int imImageMatch(const imImage* image1, const imImage* image2);
00216
00217 /** Changes the image space from gray to binary by just changing color_space and the palette.
00218 *
00219 * \verbatim image:SetBinary() [in Lua 5] \endverbatim
00220 * \ingroup imgclass */
00221 void imImageSetBinary(imImage* image);
00222
00223 /** Changes a gray data into a binary data, done in-place.
00224 *
00225 * \verbatim image:MakeBinary() [in Lua 5] \endverbatim
00226 * \ingroup imgclass */
00227 void imImageMakeBinary(imImage *image);
00228
00229
00230
00231 /** \defgroup imgfile imImage Storage
00232 *
00233 * \par
00234 * Functions to simplify the process of reading and writting imImage structures.
00235 * Will also load and save the alpha planes when possible.
00236 * \par
00237 * See \ref im_image.h
00238 * \ingroup file */
00239
00240
00241 /** Loads an image from an already open file. Returns NULL if failed. \n
00242 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00243 * index specifies the image number between 0 and image_count-1. \n
00244 * The returned imagem will be of the same color_space and data_type of the image in the file. \n
00245 *
00246 * \verbatim ifile:ImageLoad([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00247 * Default index is 0.
00248 * \ingroup imgfile */
00249 imImage* imFileLoadImage(imFile* ifile, int index, int *error);
00250
00251 /** Loads an image from an already open file. Returns NULL if failed. \n
00252 * This function assumes that the image in the file has the same parameters as the given image. \n
00253 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00254 * index specifies the image number between 0 and image_count-1. \n
00255 * The returned imagem will be of the same color_space and data_type of the image in the file. \n
00256 *
00257 * \verbatim ifile:ImageLoadFrame([index: number], image: imImage) -> error: number [in Lua 5] \endverbatim
00258 * Default index is 0.
00259 * \ingroup imgfile */
00260 void imFileLoadImageFrame(imFile* ifile, int index, imImage* image, int *error);
00261
00262 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00263 * The returned imagem will be always a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00264 * index specifies the image number between 0 and image_count-1. \n
00265 * Returns NULL if failed.
00266 *
00267 * \verbatim ifile:LoadBitmap([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00268 * Default index is 0.
00269 * \ingroup imgfile */
00270 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error);
00271
00272 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00273 * This function assumes that the image in the file has the same parameters as the given image. \n
00274 * The imagem must be a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00275 * index specifies the image number between 0 and image_count-1. \n
00276 * Returns NULL if failed.
00277 *
00278 * \verbatim ifile:LoadBitmapFrame([index: number], image: imImage) -> error: number [in Lua 5] \endverbatim
00279 * Default index is 0.
00280 * \ingroup imgfile */
00281 void imFileLoadBitmapFrame(imFile* ifile, int index, imImage* image, int *error);
00282
00283 /** Saves the image to an already open file. \n
00284 * This will call \ref imFileWriteImageInfo and \ref imFileWriteImageData. \n
00285 * Returns error code.
00286 *
00287 * \verbatim ifile:SaveImage(image: imImage) -> error: number [in Lua 5] \endverbatim
00288 * \ingroup imgfile */
00289 int imFileSaveImage(imFile* ifile, const imImage* image);
00290
00291 /** Loads an image from file. Open, loads and closes the file. \n
00292 * index specifies the image number between 0 and image_count-1. \n
00293 * Returns NULL if failed.
00294 *
00295 * \verbatim im.FileImageLoad(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00296 * Default index is 0.
00297 * \ingroup imgfile */
00298 imImage* imFileImageLoad(const char* file_name, int index, int *error);
00299
00300 /** Loads an image from file, but forces the image to be a bitmap. Open, loads and closes the file. \n
00301 * index specifies the image number between 0 and image_count-1. \n
00302 * Returns NULL if failed.
00303 *
00304 * \verbatim im.FileImageLoadBitmap(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00305 * Default index is 0.
00306 * \ingroup imgfile */
00307 imImage* imFileImageLoadBitmap(const char* file_name, int index, int *error);
00308
00309 /** Saves the image to file. Open, saves and closes the file. \n
00310 * Returns error code.
00311 *
00312 * \verbatim im.FileImageLoadBitmap(file_name: string, format: string, image: imImage) -> error: number [in Lua 5] \endverbatim
00313 * \ingroup imgfile */
00314 int imFileImageSave(const char* file_name, const char* format, const imImage* image);
00315
00316
00317
00318 /** Utility macro to draw the image in a CD library canvas.
00319 * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY.
00320 * \ingroup imgclass */
00321 #define imPutBitmap(_image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \
00322 { \
00323 if (_image->color_space == IM_RGB) \
00324 { \
00325 if (image->has_alpha) \
00326 cdPutImageRectRGBA(_image->width, _image->height, \
00327 (unsigned char*)_image->data[0], \
00328 (unsigned char*)_image->data[1], \
00329 (unsigned char*)_image->data[2], \
00330 (unsigned char*)_image->data[3], \
00331 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00332 else \
00333 cdPutImageRectRGB(_image->width, _image->height, \
00334 (unsigned char*)_image->data[0], \
00335 (unsigned char*)_image->data[1], \
00336 (unsigned char*)_image->data[2], \
00337 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00338 } \
00339 else \
00340 cdPutImageRectMap(_image->width, _image->height, \
00341 (unsigned char*)_image->data[0], _image->palette, \
00342 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00343 }
00344
00345
00346 #if defined(__cplusplus)
00347 }
00348 #endif
00349
00350 #endif