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.2 2005/07/01 22:13:09 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 0 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, but no alpha channel, 00036 * 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 */ 00042 int height; /**< Number of lines. */ 00043 int color_space; /**< Color space descriptor. */ 00044 int data_type; /**< Data type descriptor. */ 00045 00046 /* secondary parameters */ 00047 int depth; /**< Number of planes (ColorSpaceDepth) */ 00048 int line_size; /**< Number of bytes per line in one plane (width * DataTypeSize) */ 00049 int plane_size; /**< Number of bytes per plane. (line_size * height) */ 00050 int size; /**< Number of bytes occupied by the image (plane_size * depth) */ 00051 int count; /**< Number of pixels (width * height) */ 00052 00053 /* image data */ 00054 void** data; /**< Image data organized as a 2D matrix with several planes. 00055 But plane 0 is also a pointer to the full data. (data[i] = data[0] + i*plane_size) */ 00056 00057 /* image attributes */ 00058 long *palette; /**< Used when depth=1. Otherwise is NULL. */ 00059 int palette_count; /**< The palette is always 256 colors allocated, but can have less colors used. */ 00060 00061 void* attrib_table; /**< in fact is a imAttribTable, but we hide this here */ 00062 } imImage; 00063 00064 00065 /** Creates a new image. 00066 * \ingroup imgclass */ 00067 imImage* imImageCreate(int width, int height, int color_space, int data_type); 00068 00069 /** Initializes the image structure but does not allocates image data. 00070 * \ingroup imgclass */ 00071 imImage* imImageInit(int width, int height, int color_space, int data_type, void* data_buffer, long* palette, int palette_count); 00072 00073 /** Destroys the image and frees the memory used. 00074 * image data is destroyed only if its data[0] is not NULL. 00075 * \ingroup imgclass */ 00076 void imImageDestroy(imImage* image); 00077 00078 /** Changes the buffer size. Reallocate internal buffers if they are larger than original. 00079 * \ingroup imgclass */ 00080 void imImageReshape(imImage* image, int width, int height); 00081 00082 /** Copy image data and attributes from one image to another. \n 00083 * Images must have the same size and type. 00084 * \ingroup imgclass */ 00085 void imImageCopy(const imImage* src_image, imImage* dst_image); 00086 00087 /** Copy image data only one image to another. \n 00088 * Images must have the same size and type. 00089 * \ingroup imgclass */ 00090 void imImageCopyData(const imImage* src_image, imImage* dst_image); 00091 00092 /** Creates a copy of the image. 00093 * \ingroup imgclass */ 00094 imImage* imImageDuplicate(const imImage* image); 00095 00096 /** Creates a clone of the image. i.e. same attributes but ignore contents. 00097 * \ingroup imgclass */ 00098 imImage* imImageClone(const imImage* image); 00099 00100 /** Changes an extended attribute. \n 00101 * The data will be internally duplicated. \n 00102 * If data is NULL the attribute is removed. \n 00103 * If count is -1 and data_type is IM_BYTE then data is zero terminated. 00104 * \ingroup imgclass */ 00105 void imImageSetAttribute(imImage* image, const char* attrib, int data_type, int count, const void* data); 00106 00107 /** Returns an extended attribute. \n 00108 * Returns NULL if not found. 00109 * \ingroup imgclass */ 00110 const void* imImageGetAttribute(const imImage* image, const char* attrib, int *data_type, int *count); 00111 00112 /** Returns a list of the attribute names. \n 00113 * "attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count. 00114 * \ingroup imgclass */ 00115 void imImageGetAttributeList(const imImage* image, char** attrib, int *attrib_count); 00116 00117 /** Sets all image data to zero. 00118 * \ingroup imgclass */ 00119 void imImageClear(imImage* image); 00120 00121 /** Indicates that the image can be viewed in common graphic devices. 00122 * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY. 00123 * \ingroup imgclass */ 00124 int imImageIsBitmap(const imImage* image); 00125 00126 /** Changes the image palette. 00127 * This will destroy the existing palette and replace it with the given palette buffer. 00128 * \ingroup imgclass */ 00129 void imImageSetPalette(imImage* image, long* palette, int palette_count); 00130 00131 /** Copies the image attributes from src to dst. 00132 * \ingroup imgclass */ 00133 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image); 00134 00135 /** Returns 1 if the images match width and height. Returns 0 otherwise. 00136 * \ingroup imgclass */ 00137 int imImageMatchSize(const imImage* image1, const imImage* image2); 00138 00139 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise. 00140 * \ingroup imgclass */ 00141 int imImageMatchColor(const imImage* image1, const imImage* image2); 00142 00143 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise. 00144 * \ingroup imgclass */ 00145 int imImageMatchDataType(const imImage* image1, const imImage* image2); 00146 00147 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise. 00148 * \ingroup imgclass */ 00149 int imImageMatchColorSpace(const imImage* image1, const imImage* image2); 00150 00151 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise. 00152 * \ingroup imgclass */ 00153 int imImageMatch(const imImage* image1, const imImage* image2); 00154 00155 /** Changes the image space from gray to binary by just changing color_space and the palette. 00156 * \ingroup imgclass */ 00157 void imImageSetBinary(imImage* image); 00158 00159 /** Changes a gray data into a binary data. 00160 * \ingroup imgclass */ 00161 void imImageMakeBinary(imImage *image); 00162 00163 00164 00165 /** \defgroup imgfile imImage Storage 00166 * 00167 * \par 00168 * Functions to simplify the process of reading and writting imImage structures. 00169 * \par 00170 * See \ref im_image.h 00171 * \ingroup file */ 00172 00173 00174 /** Loads an image from an already open file. Returns NULL if failed. \n 00175 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n 00176 * index specifies the image number between 0 and image_count-1. \n 00177 * The returned imagem will be of the same color_space and data_type of the image in the file. \n 00178 * \ingroup imgfile */ 00179 imImage* imFileLoadImage(imFile* ifile, int index, int *error); 00180 00181 /** Loads an image from an already open file. Returns NULL if failed. \n 00182 * This function assumes that the image in the file has the same parameters as the given image. \n 00183 * This will call \ref imFileReadImageInfo and \ref imFileReadImageData. \n 00184 * index specifies the image number between 0 and image_count-1. \n 00185 * The returned imagem will be of the same color_space and data_type of the image in the file. \n 00186 * \ingroup imgfile */ 00187 void imFileLoadImageFrame(imFile* ifile, int index, imImage* image, int *error); 00188 00189 /** Loads an image from an already open file, but forces the image to be a bitmap.\n 00190 * The returned imagem will be always a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n 00191 * index specifies the image number between 0 and image_count-1. \n 00192 * Returns NULL if failed. 00193 * \ingroup imgfile */ 00194 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error); 00195 00196 /** Loads an image from an already open file, but forces the image to be a bitmap.\n 00197 * This function assumes that the image in the file has the same parameters as the given image. \n 00198 * The imagem must be a Bitmap image, with color_space RGB, MAP, GRAY or BINARY, and data_type IM_BYTE. \n 00199 * index specifies the image number between 0 and image_count-1. \n 00200 * Returns NULL if failed. 00201 * \ingroup imgfile */ 00202 void imFileLoadBitmapFrame(imFile* ifile, int index, imImage* image, int *error); 00203 00204 /** Saves the image to an already open file. \n 00205 * This will call \ref imFileWriteImageInfo and \ref imFileWriteImageData. \n 00206 * Returns error code. 00207 * \ingroup imgfile */ 00208 int imFileSaveImage(imFile* ifile, const imImage* image); 00209 00210 /** Loads an image from file. Open, loads and closes the file. \n 00211 * index specifies the image number between 0 and image_count-1. \n 00212 * Returns NULL if failed. 00213 * \ingroup imgfile */ 00214 imImage* imFileImageLoad(const char* file_name, int index, int *error); 00215 00216 /** Loads an image from file, but forces the image to be a bitmap. Open, loads and closes the file. \n 00217 * index specifies the image number between 0 and image_count-1. \n 00218 * Returns NULL if failed. 00219 * \ingroup imgfile */ 00220 imImage* imFileImageLoadBitmap(const char* file_name, int index, int *error); 00221 00222 /** Saves the image to file. Open, saves and closes the file. \n 00223 * Returns error code. 00224 * \ingroup imgfile */ 00225 int imFileImageSave(const char* file_name, const char* format, const imImage* image); 00226 00227 00228 00229 /** Utility macro to draw the image in a CD library canvas. 00230 * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY. 00231 * \ingroup imgclass */ 00232 #define imPutBitmap(_image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \ 00233 { \ 00234 if (_image->color_space == IM_RGB) \ 00235 cdPutImageRectRGB(_image->width, _image->height, \ 00236 (unsigned char*)_image->data[0], \ 00237 (unsigned char*)_image->data[1], \ 00238 (unsigned char*)_image->data[2], \ 00239 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \ 00240 else \ 00241 cdPutImageRectMap(_image->width, _image->height, \ 00242 (unsigned char*)_image->data[0], _image->palette, \ 00243 _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax); \ 00244 } 00245 00246 00247 #if defined(__cplusplus) 00248 } 00249 #endif 00250 00251 #endif