IM: im_image.h Source File

previous page next page
im_image.h

00001 /** \file
00002  * \brief Image Manipulation
00003  *
00004  * See Copyright Notice in im_lib.h
00005  * $Id: 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 Image Structure 
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 /** \brief Image Structure Definition.  
00032  *
00033  * \par
00034  * An image representation than supports all the color spaces, but no alpha channel, 
00035  * 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 */
00041   int height;         /**< Number of lines.  */
00042   int color_space;    /**< Color space descriptor. */
00043   int data_type;      /**< Data type descriptor.   */
00044 
00045   /* secondary parameters */
00046   int depth;          /**< Number of planes                      (ColorSpaceDepth)         */
00047   int line_size;      /**< Number of bytes per line in one plane (width * DataTypeSize)    */
00048   int plane_size;     /**< Number of bytes per plane.            (line_size * height)      */
00049   int size;           /**< Number of bytes occupied by the image (plane_size * depth)      */
00050   int count;          /**< Number of pixels                      (width * height)          */
00051 
00052   /* image data */
00053   void** data;        /**< Image data organized as a 2D matrix with several planes. 
00054                            But plane 0 is also a pointer to the full data.  (data[i] = data[0] + i*plane_size) */
00055 
00056   /* image attributes */
00057   long *palette;      /**< Used when depth=1. Otherwise is NULL. */
00058   int palette_count;  /**< The palette is always 256 colors allocated, but can have less colors used. */
00059 
00060   void* attrib_table; /**< in fact is a imAttribTable, but we hide this here */
00061 } imImage;
00062 
00063 
00064 /** Creates a new image.
00065  * \ingroup imgclass */
00066 imImage* imImageCreate(int width, int height, int color_space, int data_type);
00067 
00068 /** Initializes the image structure but does not allocates image data.
00069  * \ingroup imgclass */
00070 imImage* imImageInit(int width, int height, int color_space, int data_type, void* data_buffer, long* palette, int palette_count);
00071 
00072 /** Destroys the image and frees the memory used.
00073  * image data is destroyed only if it data[0] is not NULL.
00074  * \ingroup imgclass */
00075 void imImageDestroy(imImage* image);
00076 
00077 /** Changes the buffer size. Reallocate internal buffers if they are larger than original.
00078  * \ingroup imgclass */
00079 void imImageReshape(imImage* image, int width, int height);
00080 
00081 /** Copy image data and attributes from one image to another. \n
00082  * Images must have the same size and type.
00083  * \ingroup imgclass */
00084 void imImageCopy(const imImage* src_image, imImage* dst_image);
00085 
00086 /** Copy image data only one image to another. \n
00087  * Images must have the same size and type.
00088  * \ingroup imgclass */
00089 void imImageCopyData(const imImage* src_image, imImage* dst_image);
00090 
00091 /** Creates a copy of the image.
00092  * \ingroup imgclass */
00093 imImage* imImageDuplicate(const imImage* image);
00094 
00095 /** Creates a clone of the image. i.e. same attributes but ignore contents.
00096  * \ingroup imgclass */
00097 imImage* imImageClone(const imImage* image);
00098 
00099 /** Changes an extended attribute. \n
00100  * The data will be internally duplicated. \n
00101  * If data is NULL the attribute is removed. \n
00102  * If count is -1 and data_type is IM_BYTE then data is zero terminated.
00103  * \ingroup imgclass */
00104 void imImageSetAttribute(imImage* image, const char* attrib, int data_type, int count, const void* data);
00105 
00106 /** Returns an extended attribute. \n
00107  * Returns NULL if not found.
00108  * \ingroup imgclass */
00109 const void* imImageGetAttribute(const imImage* image, const char* attrib, int *data_type, int *count);
00110 
00111 /** Returns a list of the attribute names. \n
00112  * "attrib" must contain room enough for "attrib_count" names. Use "attrib=NULL" to return only the count.
00113  * \ingroup imgclass */
00114 void imImageGetAttributeList(const imImage* image, char** attrib, int *attrib_count);
00115 
00116 /** Sets all image data to zero.
00117  * \ingroup imgclass */
00118 void imImageClear(imImage* image);
00119 
00120 /** Indicates that the image can be viewed in common graphic devices.     
00121  * Data type must be IM_BYTE. Color mode can be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY.
00122  * \ingroup imgclass */
00123 int imImageIsBitmap(const imImage* image);
00124 
00125 /** Changes the image palette.
00126  * This will destroy the existing palette and replace it with the given palette buffer.
00127  * \ingroup imgclass */
00128 void imImageSetPalette(imImage* image, long* palette, int palette_count);
00129 
00130 /** Copies the image attributes from src to dst.
00131  * \ingroup imgclass */
00132 void imImageCopyAttributes(const imImage* src_image, imImage* dst_image);
00133 
00134 /** Returns 1 if the images match width and height. Returns 0 otherwise.
00135  * \ingroup imgclass */
00136 int imImageMatchSize(const imImage* image1, const imImage* image2);
00137 
00138 /** Returns 1 if the images match color mode and data type. Returns 0 otherwise.
00139  * \ingroup imgclass */
00140 int imImageMatchColor(const imImage* image1, const imImage* image2);
00141 
00142 /** Returns 1 if the images match width, height and data type. Returns 0 otherwise.
00143  * \ingroup imgclass */
00144 int imImageMatchDataType(const imImage* image1, const imImage* image2);
00145 
00146 /** Returns 1 if the images match width, height and color space. Returns 0 otherwise.
00147  * \ingroup imgclass */
00148 int imImageMatchColorSpace(const imImage* image1, const imImage* image2);
00149 
00150 /** Returns 1 if the images match in width, height, data type and color space. Returns 0 otherwise.
00151  * \ingroup imgclass */
00152 int imImageMatch(const imImage* image1, const imImage* image2);
00153 
00154 /** Loads an image from file. Returns NULL if failed.
00155  * This will call imFileReadImageInfo and imFileReadImageData.
00156  * \ingroup imgclass */
00157 imImage* imFileLoadImage(imFile* ifile, int index, int *error);
00158 
00159 /** Loads an image from file, but forces the image to be a bitmap.\n
00160  * Returns NULL if failed.
00161  * \ingroup imgclass */
00162 imImage* imFileLoadBitmap(imFile* ifile, int index, int *error);
00163 
00164 /** Saves the image to file. Returns error code. \n
00165  * This will call imFileWriteImageInfo and imFileWriteImageData.
00166  * \ingroup imgclass */
00167 int imFileSaveImage(imFile* ifile, const imImage* image);
00168 
00169 /** Loads an image from file. \n
00170  * Returns NULL if failed.
00171  * \ingroup imgclass */
00172 imImage* imImageLoad(const char* file_name, int index, int *error);
00173 
00174 /** Loads an image from file, but forces the image to be a bitmap. \n
00175  * Returns NULL if failed.
00176  * \ingroup imgclass */
00177 imImage* imImageLoadBitmap(const char* file_name, int index, int *error);
00178 
00179 /** Changes the image space from gray to binary by just changing color_space and the palette.
00180  * \ingroup imgclass */
00181 void imImageSetBinary(imImage* image);
00182 
00183 /** Changes a gray data into a binary data.
00184  * \ingroup imgclass */
00185 void imImageMakeBinary(imImage *image);
00186 
00187 /** Utility macro to draw the image in a CD library canvas.
00188  * Works only for data_type IM_BYTE, and color spaces: IM_RGB, IM_MAP, IMGRAY and IM_BINARY.
00189  * \ingroup imgclass */
00190 #define cdPutBitmap(_image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax)     \
00191   {                                                                         \
00192     if (_image->color_space == IM_RGB)                                      \
00193       cdPutImageRectRGB(_image->width, _image->height,                      \
00194                         (unsigned char*)_image->data[0],                    \
00195                         (unsigned char*)_image->data[1],                    \
00196                         (unsigned char*)_image->data[2],                    \
00197                         _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax);        \
00198     else                                                                    \
00199       cdPutImageRectMap(_image->width, _image->height,                      \
00200                         (unsigned char*)_image->data[0], _image->palette,   \
00201                         _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax);        \
00202   }                                                                               
00203 
00204 
00205 #if defined(__cplusplus)
00206 }
00207 #endif
00208 
00209 #endif
previous page start next page