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. \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.
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 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(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.
00172 *
00173 * \verbatim image:Clear() [in Lua 5] \endverbatim
00174 * \ingroup imgclass */
00175 void imImageClear(imImage* image);
00176
00177 /** Indicates that the image can be viewed in common graphic devices.
00178 * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY.
00179 *
00180 * \verbatim image:IsBitmap() -> is_bitmap: boolean [in Lua 5] \endverbatim
00181 * \ingroup imgclass */
00182 int imImageIsBitmap(const imImage* image);
00183
00184 /** Changes the image palette.
00185 * This will destroy the existing palette and replace it with the given palette buffer.
00186 *
00187 * \verbatim image:SetPalette(palette: imPalette) [in Lua 5] \endverbatim
00188 * \ingroup imgclass */
00189 void imImageSetPalette(imImage* image, long* palette, int palette_count);
00190
00191 /** Copies the image attributes from src to dst.
00192 *
00193 * \verbatim image:CopyAttributes(dst_image: imImage) [in Lua 5] \endverbatim
00194 * \ingroup imgclass */
00195 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image);
00196
00197 /** Returns 1 if the images match width and height. Returns 0 otherwise.
00198 *
00199 * \verbatim image:MatchSize(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00200 * \ingroup imgclass */
00201 int imImageMatchSize(const imImage* image1, const imImage* image2);
00202
00203 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise.
00204 *
00205 * \verbatim image:MatchColor(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00206 * \ingroup imgclass */
00207 int imImageMatchColor(const imImage* image1, const imImage* image2);
00208
00209 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise.
00210 *
00211 * \verbatim image:MatchDataType(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00212 * \ingroup imgclass */
00213 int imImageMatchDataType(const imImage* image1, const imImage* image2);
00214
00215 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise.
00216 *
00217 * \verbatim image:MatchColorSpace(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00218 * \ingroup imgclass */
00219 int imImageMatchColorSpace(const imImage* image1, const imImage* image2);
00220
00221 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise.
00222 *
00223 * \verbatim image:Match(image2: imImage) -> match: boolean [in Lua 5] \endverbatim
00224 * \ingroup imgclass */
00225 int imImageMatch(const imImage* image1, const imImage* image2);
00226
00227 /** Changes the image space from gray to binary by just changing color_space and the palette.
00228 *
00229 * \verbatim image:SetBinary() [in Lua 5] \endverbatim
00230 * \ingroup imgclass */
00231 void imImageSetBinary(imImage* image);
00232
00233 /** Changes a gray data into a binary data, done in-place.
00234 *
00235 * \verbatim image:MakeBinary() [in Lua 5] \endverbatim
00236 * \ingroup imgclass */
00237 void imImageMakeBinary(imImage *image);
00238
00239
00240
00241 /** \defgroup imgfile imImage Storage
00242 *
00243 * \par
00244 * Functions to simplify the process of reading and writting imImage structures.
00245 * Will also load and save the alpha planes when possible.
00246 * \par
00247 * See \ref im_image.h
00248 * \ingroup file */
00249
00250
00251 /** Loads an image from an already open file. Returns NULL if failed. \n
00252 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00253 * index specifies the image number between 0 and image_count-1. \n
00254 * The returned image will be of the same color_space and data_type of the image in the file. \n
00255 * Attributes from the file will be stored at the image.
00256 * See also \ref imErrorCodes.
00257 *
00258 * \verbatim ifile:LoadImage([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00259 * Default index is 0.
00260 * \ingroup imgfile */
00261 imImage* imFileLoadImage(imFile* ifile, int index, int *error);
00262
00263 /** Loads an image from an already open file. Returns NULL if failed. \n
00264 * This function assumes that the image in the file has the same parameters as the given image. \n
00265 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00266 * index specifies the image number between 0 and image_count-1. \n
00267 * The returned image will be of the same color_space and data_type of the image in the file. \n
00268 * Attributes from the file will be stored at the image.
00269 * See also \ref imErrorCodes.
00270 *
00271 * \verbatim ifile:LoadImageFrame(index: number, image: imImage) -> error: number [in Lua 5] \endverbatim
00272 * Default index is 0.
00273 * \ingroup imgfile */
00274 void imFileLoadImageFrame(imFile* ifile, int index, imImage* image, int *error);
00275
00276 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00277 * The returned imagem will be always a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00278 * index specifies the image number between 0 and image_count-1. \n
00279 * Returns NULL if failed.
00280 * Attributes from the file will be stored at the image.
00281 * See also \ref imErrorCodes.
00282 *
00283 * \verbatim ifile:LoadBitmap([index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00284 * Default index is 0.
00285 * \ingroup imgfile */
00286 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error);
00287
00288 /** Loads an image region from an already open file. Returns NULL if failed. \n
00289 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n
00290 * index specifies the image number between 0 and image_count-1. \n
00291 * The returned image will be of the same color_space and data_type of the image in the file,
00292 * or will be a Bitmap image. \n
00293 * Attributes from the file will be stored at the image.
00294 * See also \ref imErrorCodes. \n
00295 * For now works only for ECW file format.
00296 *
00297 * \verbatim ifile:LoadRegion(index, bitmap, xmin, xmax, ymin, ymax, width, height: number) -> image: imImage, error: number [in Lua 5] \endverbatim
00298 * Default index is 0.
00299 * \ingroup imgfile */
00300 imImage* imFileLoadImageRegion(imFile* ifile, int index, int bitmap, int *error,
00301 int xmin, int xmax, int ymin, int ymax, int width, int height);
00302
00303 /** Loads an image from an already open file, but forces the image to be a bitmap.\n
00304 * This function assumes that the image in the file has the same parameters as the given image. \n
00305 * The imagem must be a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n
00306 * index specifies the image number between 0 and image_count-1. \n
00307 * Returns NULL if failed.
00308 * Attributes from the file will be stored at the image.
00309 * See also \ref imErrorCodes.
00310 *
00311 * \verbatim ifile:LoadBitmapFrame(index: number, image: imImage) -> error: number [in Lua 5] \endverbatim
00312 * Default index is 0.
00313 * \ingroup imgfile */
00314 void imFileLoadBitmapFrame(imFile* ifile, int index, imImage* image, int *error);
00315
00316 /** Saves the image to an already open file. \n
00317 * This will call \ref imFileWriteImageInfo and \ref imFileWriteImageData. \n
00318 * Attributes from the image will be stored at the file.
00319 * Returns error code.
00320 *
00321 * \verbatim ifile:SaveImage(image: imImage) -> error: number [in Lua 5] \endverbatim
00322 * \ingroup imgfile */
00323 int imFileSaveImage(imFile* ifile, const imImage* image);
00324
00325 /** Loads an image from file. Open, loads and closes the file. \n
00326 * index specifies the image number between 0 and image_count-1. \n
00327 * Returns NULL if failed.
00328 * Attributes from the file will be stored at the image.
00329 * See also \ref imErrorCodes.
00330 *
00331 * \verbatim im.FileImageLoad(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00332 * Default index is 0.
00333 * \ingroup imgfile */
00334 imImage* imFileImageLoad(const char* file_name, int index, int *error);
00335
00336 /** Loads an image from file, but forces the image to be a bitmap. Open, loads and closes the file. \n
00337 * index specifies the image number between 0 and image_count-1. \n
00338 * Returns NULL if failed.
00339 * Attributes from the file will be stored at the image.
00340 * See also \ref imErrorCodes.
00341 *
00342 * \verbatim im.FileImageLoadBitmap(file_name: string, [index: number]) -> image: imImage, error: number [in Lua 5] \endverbatim
00343 * Default index is 0.
00344 * \ingroup imgfile */
00345 imImage* imFileImageLoadBitmap(const char* file_name, int index, int *error);
00346
00347 /** Loads an image region from file. Open, loads and closes the file. \n
00348 * index specifies the image number between 0 and image_count-1. \n
00349 * Returns NULL if failed.
00350 * Attributes from the file will be stored at the image.
00351 * See also \ref imErrorCodes. \n
00352 * For now works only for ECW file format.
00353 *
00354 * \verbatim im.FileImageLoadRegion(file_name: string, index, bitmap, xmin, xmax, ymin, ymax, width, height: number, ) -> image: imImage, error: number [in Lua 5] \endverbatim
00355 * Default index is 0.
00356 * \ingroup imgfile */
00357 imImage* imFileImageLoadRegion(const char* file_name, int index, int bitmap, int *error,
00358 int xmin, int xmax, int ymin, int ymax, int width, int height);
00359
00360 /** Saves the image to file. Open, saves and closes the file. \n
00361 * Returns error code. \n
00362 * Attributes from the image will be stored at the file.
00363 *
00364 * \verbatim im.FileImageSave(file_name: string, format: string, image: imImage) -> error: number [in Lua 5] \endverbatim
00365 * \verbatim image:Save(file_name: string, format: string) -> error: number [in Lua 5] \endverbatim
00366 * \ingroup imgfile */
00367 int imFileImageSave(const char* file_name, const char* format, const imImage* image);
00368
00369
00370
00371 /** Utility macro to draw the image in a CD library canvas.
00372 * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY.
00373 * \ingroup imgclass */
00374 #define imcdCanvasPutImage(_canvas, _image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \
00375 { \
00376 if (_image->color_space == IM_RGB) \
00377 { \
00378 if (_image->has_alpha) \
00379 cdCanvasPutImageRectRGBA(_canvas, _image->width, _image->height, \
00380 (unsigned char*)_image->data[0], \
00381 (unsigned char*)_image->data[1], \
00382 (unsigned char*)_image->data[2], \
00383 (unsigned char*)_image->data[3], \
00384 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00385 else \
00386 cdCanvasPutImageRectRGB(_canvas, _image->width, _image->height, \
00387 (unsigned char*)_image->data[0], \
00388 (unsigned char*)_image->data[1], \
00389 (unsigned char*)_image->data[2], \
00390 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00391 } \
00392 else \
00393 cdCanvasPutImageRectMap(_canvas, _image->width, _image->height, \
00394 (unsigned char*)_image->data[0], _image->palette, \
00395 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \
00396 }
00397
00398
00399 #if defined(__cplusplus)
00400 }
00401 #endif
00402
00403 #endif