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