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