00001 /** \file 00002 * \brief Image Manipulation 00003 * 00004 * See Copyright Notice in im_lib.h 00005 */ 00006 00007 #ifndef __IM_IMAGE_H 00008 #define __IM_IMAGE_H 00009 00010 #if defined(__cplusplus) 00011 extern "C" { 00012 #endif 00013 00014 00015 /** \defgroup imgclass imImage 00016 * 00017 * \par 00018 * Base definitions and functions for image representation. \n 00019 * Only the image processing operations depends on these definitions, 00020 * Image Storage and Image Capture are completely independent. 00021 * \par 00022 * You can also initialize a structure with your own memory buffer, see \ref imImageInit. 00023 * To release the structure without releasing the buffer, 00024 * set "data[0]" to NULL before calling imImageDestroy. 00025 * \par 00026 * See \ref im_image.h 00027 * \ingroup imagerep */ 00028 00029 00030 00031 /** \brief imImage Structure Definition. 00032 * 00033 * \par 00034 * An image representation than supports all the color spaces, 00035 * but planes are always unpacked and the orientation is always bottom up. 00036 * \ingroup imgclass */ 00037 typedef struct _imImage 00038 { 00039 /* main parameters */ 00040 int width; /**< Number of columns. image:Width() -> width: number [in Lua 5]. */ 00041 int height; /**< Number of lines. image:Height() -> height: number [in Lua 5]. */ 00042 int color_space; /**< Color space descriptor. See also \ref imColorSpace. image:ColorSpace() -> color_space: number [in Lua 5]. */ 00043 int data_type; /**< Data type descriptor. See also \ref imDataType. image:DataType() -> data_type: number [in Lua 5]. */ 00044 int has_alpha; /**< Indicates that there is an extra channel with alpha. image:HasAlpha() -> has_alpha: number [in Lua 5]. \n 00045 It will not affect the secondary parameters, i.e. the number of planes will be in fact depth+1. \n 00046 It is always 0 unless imImageAddAlpha is called, this is done in image load functions. */ 00047 00048 /* secondary parameters */ 00049 int depth; /**< Number of planes (ColorSpaceDepth) */ 00050 int line_size; /**< Number of bytes per line in one plane (width * DataTypeSize) */ 00051 int plane_size; /**< Number of bytes per plane. (line_size * height) */ 00052 int size; /**< Number of bytes occupied by the image (plane_size * depth) */ 00053 int count; /**< Number of pixels (width * height) */ 00054 00055 /* image data */ 00056 void** data; /**< Image data organized as a 2D matrix with several planes. \n 00057 But plane 0 is also a pointer to the full data. \n 00058 The remaining planes are: data[i] = data[0] + i*plane_size \n 00059 In Lua, data indexing is possible using: image[plane][row][column] */ 00060 00061 /* image attributes */ 00062 long *palette; /**< Color palette. image:GetPalette() -> palette: imPalette [in Lua 5]. \n 00063 Used when depth=1. Otherwise is NULL. */ 00064 int palette_count; /**< The palette is always 256 colors allocated, but can have less colors used. */ 00065 00066 void* attrib_table; /**< in fact is an imAttribTable, but we hide this here */ 00067 } imImage; 00068 00069 00070 /** Creates a new image. 00071 * See also \ref imDataType and \ref imColorSpace. Image data is cleared as \ref imImageClear. \n 00072 * In Lua the IM image metatable name is "imImage". 00073 * When converted to a string will return "imImage(%p) [width=%d,height=%d,color_space=%s,data_type=%s,depth=%d]" where %p is replaced by the userdata address, 00074 * and other values are replaced by the respective attributes. 00075 * If the image is already destroyed by im.ImageDestroy, then it will return also the suffix "-destroyed". 00076 * 00077 * \verbatim im.ImageCreate(width: number, height: number, color_space: number, data_type: number) -> image: imImage [in Lua 5] \endverbatim 00078 * \ingroup imgclass */ 00079 imImage* imImageCreate(int width, int height, int color_space, int data_type); 00080 00081 /** Initializes the image structure but does not allocates image data. 00082 * See also \ref imDataType and \ref imColorSpace. 00083 * \ingroup imgclass */ 00084 imImage* imImageInit(int width, int height, int color_space, int data_type, void* data_buffer, long* palette, int palette_count); 00085 00086 /** Creates a new image based on an existing one. \n 00087 * If the addicional parameters are -1, the given image parameters are used. \n 00088 * The image atributes always are copied. HasAlpha is copied. 00089 * See also \ref imDataType and \ref imColorSpace. 00090 * 00091 * \verbatim im.ImageCreateBased(image: imImage, [width: number], [height: number], [color_space: number], [data_type: number]) -> image: imImage [in Lua 5] \endverbatim 00092 * The addicional parameters in Lua can be nil, 00093 * and they can also be functions with the based image as a parameter to return the respective value. 00094 * \ingroup imgclass */ 00095 imImage* imImageCreateBased(const imImage* image, int width, int height, int color_space, int data_type); 00096 00097 /** Destroys the image and frees the memory used. 00098 * image data is destroyed only if its data[0] is not NULL. \n 00099 * In Lua if this function is not called, the image is destroyed by the garbage collector. 00100 * 00101 * \verbatim im.ImageDestroy(image: imImage) [in Lua 5] \endverbatim 00102 * \verbatim image:Destroy() [in Lua 5] \endverbatim 00103 * \ingroup imgclass */ 00104 void imImageDestroy(imImage* image); 00105 00106 /** Adds an alpha channel plane. 00107 * 00108 * \verbatim image:AddAlpha() [in Lua 5] \endverbatim 00109 * \ingroup imgclass */ 00110 void imImageAddAlpha(imImage* image); 00111 00112 /** Changes the buffer size. Reallocate internal buffers if the new size is larger than the original. 00113 * 00114 * \verbatim image:Reshape(width: number, height: number) [in Lua 5] \endverbatim 00115 * \ingroup imgclass */ 00116 void imImageReshape(imImage* image, int width, int height); 00117 00118 /** Copy image data and attributes from one image to another. \n 00119 * Images must have the same size and type. 00120 * 00121 * \verbatim image:Copy(dst_image: imImage) [in Lua 5] \endverbatim 00122 * \ingroup imgclass */ 00123 void imImageCopy(const imImage* src_image, imImage* dst_image); 00124 00125 /** Copy image data only fom one image to another. \n 00126 * Images must have the same size and type. 00127 * 00128 * \verbatim image:CopyData(dst_image: imImage) [in Lua 5] \endverbatim 00129 * \ingroup imgclass */ 00130 void imImageCopyData(const imImage* src_image, imImage* dst_image); 00131 00132 /** Creates a copy of the image. 00133 * 00134 * \verbatim image:Duplicate() -> new_image: imImage [in Lua 5] \endverbatim 00135 * \ingroup imgclass */ 00136 imImage* imImageDuplicate(const imImage* image); 00137 00138 /** Creates a clone of the image. i.e. same attributes but ignore contents. 00139 * 00140 * \verbatim image:Clone() -> new_image: imImage [in Lua 5] \endverbatim 00141 * \ingroup imgclass */ 00142 imImage* imImageClone(const imImage* image); 00143 00144 /** Changes an extended attribute. \n 00145 * The data will be internally duplicated. \n 00146 * If data is NULL and count==0 the attribute is removed. \n 00147 * If count is -1 and data_type is IM_BYTE then data is zero terminated. 00148 * See also \ref imDataType. 00149 * 00150 * \verbatim image:SetAttribute(attrib: string, data_type: number, data: table of numbers or string) [in Lua 5] \endverbatim 00151 * If data_type is IM_BYTE, as_string can be used as data. 00152 * \ingroup imgclass */ 00153 void imImageSetAttribute(const imImage* image, const char* attrib, int data_type, int count, const void* data); 00154 00155 /** Returns an extended attribute. \n 00156 * Returns NULL if not found. 00157 * See also \ref imDataType. 00158 * 00159 * \verbatim image:GetAttribute(attrib: string, [as_string: boolean]) -> data: table of numbers or string, data_type: number [in Lua 5] \endverbatim 00160 * If data_type is IM_BYTE, as_string can be used to return a string instead of a table. 00161 * \ingroup imgclass */ 00162 const void* imImageGetAttribute(const imImage* image, const char* attrib, int *data_type, int *count); 00163 00164 /** Returns a list of the attribute names. \n 00165 * "attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count. 00166 * 00167 * \verbatim image:GetAttributeList() -> data: table of strings [in Lua 5] \endverbatim 00168 * \ingroup imgclass */ 00169 void imImageGetAttributeList(const imImage* image, char** attrib, int *attrib_count); 00170 00171 /** Sets all image data to zero. But if color space is YCBCR, LAB or LUV, and data type is BYTE or USHORT, then 00172 * data is initialized with 128 or 32768 accordingly. Alpha is initialized as transparent (0). 00173 * 00174 * \verbatim image:Clear() [in Lua 5] \endverbatim 00175 * \ingroup imgclass */ 00176 void imImageClear(imImage* image); 00177 00178 /** Indicates that the image can be viewed in common graphic devices. 00179 * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY. 00180 * 00181 * \verbatim image:IsBitmap() -> is_bitmap: boolean [in Lua 5] \endverbatim 00182 * \ingroup imgclass */ 00183 int imImageIsBitmap(const imImage* image); 00184 00185 /** Changes the image palette. 00186 * This will destroy the existing palette and replace it with the given palette pointer. 00187 * Only the pointer is stored, so the palette should be a new palette and it can not be a static array. 00188 * 00189 * \verbatim image:SetPalette(palette: imPalette) [in Lua 5] \endverbatim 00190 * \ingroup imgclass */ 00191 void imImageSetPalette(imImage* image, long* palette, int palette_count); 00192 00193 /** Copies the image attributes from src to dst. 00194 * 00195 * \verbatim image:CopyAttributes(dst_image: imImage) [in Lua 5] \endverbatim 00196 * \ingroup imgclass */ 00197 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image); 00198 00199 /** Returns 1 if the images match width and height. Returns 0 otherwise. 00200 * 00201 * \verbatim image:MatchSize(image2: imImage) -> match: boolean [in Lua 5] \endverbatim 00202 * \ingroup imgclass */ 00203 int imImageMatchSize(const imImage* image1, const imImage* image2); 00204 00205 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise. 00206 * 00207 * \verbatim image:MatchColor(image2: imImage) -> match: boolean [in Lua 5] \endverbatim 00208 * \ingroup imgclass */ 00209 int imImageMatchColor(const imImage* image1, const imImage* image2); 00210 00211 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise. 00212 * 00213 * \verbatim image:MatchDataType(image2: imImage) -> match: boolean [in Lua 5] \endverbatim 00214 * \ingroup imgclass */ 00215 int imImageMatchDataType(const imImage* image1, const imImage* image2); 00216 00217 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise. 00218 * 00219 * \verbatim image:MatchColorSpace(image2: imImage) -> match: boolean [in Lua 5] \endverbatim 00220 * \ingroup imgclass */ 00221 int imImageMatchColorSpace(const imImage* image1, const imImage* image2); 00222 00223 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise. 00224 * 00225 * \verbatim image:Match(image2: imImage) -> match: boolean [in Lua 5] \endverbatim 00226 * \ingroup imgclass */ 00227 int imImageMatch(const imImage* image1, const imImage* image2); 00228 00229 /** Changes the image color space from gray to binary by just changing color_space and the palette. 00230 * 00231 * \verbatim image:SetBinary() [in Lua 5] \endverbatim 00232 * \ingroup imgclass */ 00233 void imImageSetBinary(imImage* image); 00234 00235 /** Changes a gray BYTE data (0,255) into a binary data (0,1), done in-place. Color space is not changed. 00236 * 00237 * \verbatim image:MakeBinary() [in Lua 5] \endverbatim 00238 * \ingroup imgclass */ 00239 void imImageMakeBinary(imImage *image); 00240 00241 /** Changes a binary data (0,1) into a gray BYTE data (0,255), done in-place. Color space is not changed. 00242 * 00243 * \verbatim image:MakeGray() [in Lua 5] \endverbatim 00244 * \ingroup imgclass */ 00245 void imImageMakeGray(imImage *image); 00246 00247 00248 00249 /** \defgroup imgfile imImage Storage 00250 * 00251 * \par 00252 * Functions to simplify the process of reading and writting imImage structures. 00253 * Will also load and save the alpha planes when possible. 00254 * \par 00255 * See \ref im_image.h 00256 * \ingroup file */ 00257 00258 00259 /** Loads an image from an already open file. Returns NULL if failed. \n 00260 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n 00261 * index specifies the image number between 0 and image_count-1. \n 00262 * The returned image will be of the same color_space and data_type of the image in the file. \n 00263 * Attributes from the file will be stored at the image. 00264 * See also \ref imErrorCodes. 00265 * 00266 * \verbatim ifile:LoadImage([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim 00267 * Default index is 0. 00268 * \ingroup imgfile */ 00269 imImage* imFileLoadImage(imFile* ifile, int index, int *error); 00270 00271 /** Loads an image from an already open file. Returns NULL if failed. \n 00272 * This function assumes that the image in the file has the same parameters as the given image. \n 00273 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n 00274 * index specifies the image number between 0 and image_count-1. \n 00275 * The returned image will be of the same color_space and data_type of the image in the file. \n 00276 * Attributes from the file will be stored at the image. 00277 * See also \ref imErrorCodes. 00278 * 00279 * \verbatim ifile:LoadImageFrame(index: number, image: imImage) -> error: number [in Lua 5] \endverbatim 00280 * Default index is 0. 00281 * \ingroup imgfile */ 00282 void imFileLoadImageFrame(imFile* ifile, int index, imImage* image, int *error); 00283 00284 /** Loads an image from an already open file, but forces the image to be a bitmap.\n 00285 * The returned imagem will be always a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n 00286 * index specifies the image number between 0 and image_count-1. \n 00287 * Returns NULL if failed. 00288 * Attributes from the file will be stored at the image. 00289 * See also \ref imErrorCodes. 00290 * 00291 * \verbatim ifile:LoadBitmap([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim 00292 * Default index is 0. 00293 * \ingroup imgfile */ 00294 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error); 00295 00296 /** Loads an image region from an already open file. Returns NULL if failed. \n 00297 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n 00298 * index specifies the image number between 0 and image_count-1. \n 00299 * The returned image will be of the same color_space and data_type of the image in the file, 00300 * or will be a Bitmap image. \n 00301 * Attributes from the file will be stored at the image. 00302 * See also \ref imErrorCodes. \n 00303 * For now, it works only for the ECW file format. 00304 * 00305 * \verbatim ifile:LoadRegion(index, bitmap, xmin, xmax, ymin, ymax, width, height: number) -> image: imImage, error: number [in Lua 5] \endverbatim 00306 * Default index is 0. 00307 * \ingroup imgfile */ 00308 imImage* imFileLoadImageRegion(imFile* ifile, int index, int bitmap, int *error, 00309 int xmin, int xmax, int ymin, int ymax, int width, int height); 00310 00311 /** Loads an image from an already open file, but forces the image to be a bitmap.\n 00312 * This function assumes that the image in the file has the same parameters as the given image. \n 00313 * The imagem must be a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n 00314 * index specifies the image number between 0 and image_count-1. \n 00315 * Returns NULL if failed. 00316 * Attributes from the file will be stored at the image. 00317 * See also \ref imErrorCodes. 00318 * 00319 * \verbatim ifile:LoadBitmapFrame(index: number, image: imImage) -> error: number [in Lua 5] \endverbatim 00320 * Default index is 0. 00321 * \ingroup imgfile */ 00322 void imFileLoadBitmapFrame(imFile* ifile, int index, imImage* image, int *error); 00323 00324 /** Saves the image to an already open file. \n 00325 * This will call \ref imFileWriteImageInfo and \ref imFileWriteImageData. \n 00326 * Attributes from the image will be stored at the file. 00327 * Returns error code. 00328 * 00329 * \verbatim ifile:SaveImage(image: imImage) -> error: number [in Lua 5] \endverbatim 00330 * \ingroup imgfile */ 00331 int imFileSaveImage(imFile* ifile, const imImage* image); 00332 00333 /** Loads an image from file. Open, loads and closes the file. \n 00334 * index specifies the image number between 0 and image_count-1. \n 00335 * Returns NULL if failed. 00336 * Attributes from the file will be stored at the image. 00337 * See also \ref imErrorCodes. 00338 * 00339 * \verbatim im.FileImageLoad(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim 00340 * Default index is 0. 00341 * \ingroup imgfile */ 00342 imImage* imFileImageLoad(const char* file_name, int index, int *error); 00343 00344 /** Loads an image from file, but forces the image to be a bitmap. Open, loads and closes the file. \n 00345 * index specifies the image number between 0 and image_count-1. \n 00346 * Returns NULL if failed. 00347 * Attributes from the file will be stored at the image. 00348 * See also \ref imErrorCodes. 00349 * 00350 * \verbatim im.FileImageLoadBitmap(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim 00351 * Default index is 0. 00352 * \ingroup imgfile */ 00353 imImage* imFileImageLoadBitmap(const char* file_name, int index, int *error); 00354 00355 /** Loads an image region from file. Open, loads and closes the file. \n 00356 * index specifies the image number between 0 and image_count-1. \n 00357 * Returns NULL if failed. 00358 * Attributes from the file will be stored at the image. 00359 * See also \ref imErrorCodes. \n 00360 * For now, it works only for the ECW file format. 00361 * 00362 * \verbatim im.FileImageLoadRegion(file_name: string, index, bitmap, xmin, xmax, ymin, ymax, width, height: number, ) -> image: imImage, error: number [in Lua 5] \endverbatim 00363 * Default index is 0. 00364 * \ingroup imgfile */ 00365 imImage* imFileImageLoadRegion(const char* file_name, int index, int bitmap, int *error, 00366 int xmin, int xmax, int ymin, int ymax, int width, int height); 00367 00368 /** Saves the image to file. Open, saves and closes the file. \n 00369 * Returns error code. \n 00370 * Attributes from the image will be stored at the file. 00371 * 00372 * \verbatim im.FileImageSave(file_name: string, format: string, image: imImage) -> error: number [in Lua 5] \endverbatim 00373 * \verbatim image:Save(file_name: string, format: string) -> error: number [in Lua 5] \endverbatim 00374 * \ingroup imgfile */ 00375 int imFileImageSave(const char* file_name, const char* format, const imImage* image); 00376 00377 00378 00379 /** Utility macro to draw the image in a CD library canvas. 00380 * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY. 00381 * \ingroup imgclass */ 00382 #define imcdCanvasPutImage(_canvas, _image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \ 00383 { \ 00384 if (_image->color_space == IM_RGB) \ 00385 { \ 00386 if (_image->has_alpha) \ 00387 cdCanvasPutImageRectRGBA(_canvas, _image->width, _image->height, \ 00388 (unsigned char*)_image->data[0], \ 00389 (unsigned char*)_image->data[1], \ 00390 (unsigned char*)_image->data[2], \ 00391 (unsigned char*)_image->data[3], \ 00392 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \ 00393 else \ 00394 cdCanvasPutImageRectRGB(_canvas, _image->width, _image->height, \ 00395 (unsigned char*)_image->data[0], \ 00396 (unsigned char*)_image->data[1], \ 00397 (unsigned char*)_image->data[2], \ 00398 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \ 00399 } \ 00400 else \ 00401 cdCanvasPutImageRectMap(_canvas, _image->width, _image->height, \ 00402 (unsigned char*)_image->data[0], _image->palette, \ 00403 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \ 00404 } 00405 00406 00407 #if defined(__cplusplus) 00408 } 00409 #endif 00410 00411 #endif