00001 /** \file
00002  * \brief Utilities
00003  *
00004  * See Copyright Notice in im_lib.h
00005  * $Id: Exp $
00006  */
00007 
00008 #ifndef __IM_UTIL_H
00009 #define __IM_UTIL_H
00010 
00011 #if defined(__cplusplus)
00012 extern "C" {
00013 #endif
00014 
00015 
00016 /** \defgroup util Utilities
00017  * \par
00018  * See \ref im_util.h
00019  * @{
00020  */
00021 
00022 #define IM_MIN(_a, _b) (_a < _b? _a: _b)
00023 #define IM_MAX(_a, _b) (_a > _b? _a: _b)
00024 
00025 /** @} */
00026 
00027 
00028 /** \defgroup str String Utilities
00029  * \par
00030  * See \ref im_util.h
00031  * \ingroup util */
00032 
00033 /** Check if the two strings are equal.
00034  * \ingroup str */
00035 int imStrEqual(const char* str1, const char* str2);
00036 
00037 /** Calculate the size of the string but limited to max_len.
00038  * \ingroup str */
00039 int imStrNLen(const char* str, int max_len);
00040 
00041 /** Check if the data is a string.
00042  * \ingroup str */
00043 int imStrCheck(const void* data, int count);
00044 
00045 
00046 
00047 /** \defgroup imageutil Image Utilities
00048  * \par
00049  * See \ref im_util.h
00050  * \ingroup imagerep */
00051 
00052 /** Returns the size of the data buffer.
00053  * \ingroup imageutil */
00054 int imImageDataSize(int width, int height, int color_mode, int data_type);
00055 
00056 /** Returns the size of one line of the data buffer. \n
00057  * This depends if the components are packed. If packed includes all components, if not includes only one.
00058  * \ingroup imageutil */
00059 int imImageLineSize(int width, int color_mode, int data_type);
00060 
00061 /** Returns the number of elements of one line of the data buffer. \n
00062  * This depends if the components are packed. If packed includes all components, if not includes only one.
00063  * \ingroup imageutil */
00064 int imImageLineCount(int width, int color_mode);
00065 
00066 /** Check the combination color_mode+data_type.
00067  * \ingroup imageutil */
00068 int imImageCheckFormat(int color_mode, int data_type);
00069 
00070 
00071 
00072 /** \defgroup colorutl Color Utilities
00073  * \par
00074  * See \ref im_util.h
00075  * \ingroup util */
00076 
00077 /** Encode RGB components in a long for palete usage. \n
00078  * "long" definition is compatible with the CD library definition.
00079  * \ingroup colorutl */
00080 long imColorEncode(unsigned char red, unsigned char green, unsigned char blue);
00081 
00082 /** Decode RGB components from a long for palete usage. \n
00083  * "long" definition is compatible with the CD library definition.
00084  * \ingroup colorutl */
00085 void imColorDecode(unsigned char *red, unsigned char *green, unsigned char *blue, long color);
00086 
00087 
00088 
00089 /** \defgroup colormodeutl Color Mode Utilities
00090  * \par
00091  * See \ref im_util.h
00092  * \ingroup imagerep */
00093 
00094 /** Returns the color mode name.
00095  * \ingroup colormodeutl */
00096 const char* imColorModeSpaceName(int color_mode);
00097 
00098 /** Returns the number of components of the color space including alpha.
00099  * \ingroup colormodeutl */
00100 int imColorModeDepth(int color_mode);
00101 
00102 /** Returns the color space of the color mode.
00103  * \ingroup colormodeutl */
00104 #define imColorModeSpace(_cm) (_cm & 0xFF)
00105 
00106 /** Check if the two color modes match. Only the color space is compared.
00107  * \ingroup colormodeutl */
00108 #define imColorModeMatch(_cm1, _cm2) (imColorModeSpace(_cm1) == imColorModeSpace(_cm2))
00109 
00110 /** Check if the color mode has an alpha channel.
00111  * \ingroup colormodeutl */
00112 #define imColorModeHasAlpha(_cm) (_cm & IM_ALPHA)
00113 
00114 /** Check if the color mode components are packed in one plane.
00115  * \ingroup colormodeutl */
00116 #define imColorModeIsPacked(_cm) (_cm & IM_PACKED)
00117 
00118 /** Check if the color mode orients the image from top down to bottom.
00119  * \ingroup colormodeutl */
00120 #define imColorModeIsTopDown(_cm) (_cm & IM_TOPDOWN)
00121 
00122 /** Returns the color mode of the equivalent display bitmap image. \n
00123  * Original packing and alpha are ignored. Returns IM_RGB, IM_GRAY, IM_MAP or IM_BINARY.
00124  * \ingroup colormodeutl */
00125 int imColorModeToBitmap(int color_mode);
00126 
00127 /** Check if the color mode and data_type defines a display bitmap image.
00128  * \ingroup colormodeutl */
00129 int imColorModeIsBitmap(int color_mode, int data_type);
00130 
00131 
00132 
00133 /** \defgroup datatypeutl Data Type Utilities
00134  * \par
00135  * See \ref im_util.h
00136  * \ingroup util
00137  * @{
00138  */
00139 
00140 typedef unsigned char imbyte;
00141 typedef unsigned short imushort;
00142 
00143 #define IM_BYTECROP(_v) (_v < 0? 0: _v > 255? 255: _v)
00144 #define IM_CROPMAX(_v, _max) (_v < 0? 0: _v > _max? _max: _v)
00145 
00146 /** @} */
00147 
00148 /** Returns the size in bytes of a specified numeric data type.
00149  * \ingroup datatypeutl */
00150 int imDataTypeSize(int data_type);
00151 
00152 /** Returns the numeric data type name given its identifier.
00153  * \ingroup datatypeutl */
00154 const char* imDataTypeName(int data_type);
00155 
00156 /** Returns the maximum value of an integer data type. For floating point returns 0.
00157  * \ingroup datatypeutl */
00158 unsigned long imDataTypeIntMax(int data_type);
00159 
00160 /** Returns the minimum value of an integer data type. For floating point returns 0. 
00161  * \ingroup datatypeutl */
00162 long imDataTypeIntMin(int data_type);
00163            
00164 
00165 
00166 /** \defgroup bin Binary Data Utilities
00167  * \par
00168  * See \ref im_util.h
00169  * \ingroup util */
00170 
00171 /** CPU Byte Orders. 
00172   * \ingroup bin */
00173 enum imByteOrder
00174 {
00175   IM_LITTLEENDIAN, /**< Little Endian - The most significant byte is on the right end of a word. Used by Intel processors. */
00176   IM_BIGENDIAN     /**< Big Endian - The most significant byte is on the left end of a word. Used by Motorola processors, also is the network standard byte order. */
00177 };
00178 
00179 /** Returns the current CPU byte order.
00180  * \ingroup bin */
00181 int imBinCPUByteOrder(void);
00182 
00183 /** Changes the byte order of an array of 2, 4 or 8 byte values.
00184  * \ingroup bin */
00185 void imBinSwapBytes(void *data, int count, int size);
00186 
00187 /** Changes the byte order of an array of 2 byte values.
00188  * \ingroup bin */
00189 void imBinSwapBytes2(void *data, int count);
00190 
00191 /** Inverts the byte order of the 4 byte values 
00192  * \ingroup bin */
00193 void imBinSwapBytes4(void *data, int count);
00194             
00195 /** Inverts the byte order of the 8 byte values 
00196  * \ingroup bin */
00197 void imBinSwapBytes8(void *data, int count);
00198 
00199 
00200 
00201 /** \defgroup compress Data Compression Utilities
00202  * \par
00203  * See \ref im_util.h
00204  * \ingroup util */
00205 
00206 /** Compresses the data using the ZLIB Deflate compression. \n
00207  * The destination buffer must be at least 0.1% larger than source_size plus 12 bytes. \n
00208  * It compresses raw byte data. zip_quality can be 1 to 9. \n
00209  * Returns the size of the compressed buffer.
00210  * \ingroup compress */
00211 int imCompressDataZ(const void* src_data, int src_size, void* dst_data, int dst_size, int zip_quality);
00212 
00213 /** Uncompresses the data compressed with the ZLIB Deflate compression.
00214  * \ingroup compress */
00215 int imCompressDataUnZ(const void* src_data, int src_size, void* dst_data, int dst_size);
00216 
00217 
00218 #if defined(__cplusplus)
00219 }
00220 #endif
00221 
00222 #endif