00001 /** \file 00002 * \brief Main API 00003 * 00004 * See Copyright Notice in im_lib.h 00005 */ 00006 00007 #ifndef __IM_H 00008 #define __IM_H 00009 00010 #if defined(__cplusplus) 00011 extern "C" { 00012 #endif 00013 00014 00015 /** Image data type descriptors. \n 00016 * See also \ref datatypeutl. 00017 * \ingroup imagerep */ 00018 enum imDataType 00019 { 00020 IM_BYTE, /**< "unsigned char". 1 byte from 0 to 255. */ 00021 IM_USHORT, /**< "unsigned short". 2 bytes from 0 to 65,535. */ 00022 IM_INT, /**< "int". 4 bytes from -2,147,483,648 to 2,147,483,647. */ 00023 IM_FLOAT, /**< "float". 4 bytes single precision IEEE floating point. */ 00024 IM_CFLOAT /**< complex "float". 2 float values in sequence, real and imaginary parts. */ 00025 }; 00026 00027 /** Image color mode color space descriptors (first byte). \n 00028 * See also \ref colormodeutl. 00029 * \ingroup imagerep */ 00030 enum imColorSpace 00031 { 00032 IM_RGB, /**< Red, Green and Blue (nonlinear). */ 00033 IM_MAP, /**< Indexed by RGB color map (data_type=IM_BYTE). */ 00034 IM_GRAY, /**< Shades of gray, luma (nonlinear Luminance), or an intensity value that is not related to color. */ 00035 IM_BINARY, /**< Indexed by 2 colors: black (0) and white (1) (data_type=IM_BYTE). */ 00036 IM_CMYK, /**< Cian, Magenta, Yellow and Black (nonlinear). */ 00037 IM_YCBCR, /**< ITU-R 601 Y'CbCr. Y' is luma (nonlinear Luminance). */ 00038 IM_LAB, /**< CIE L*a*b*. L* is Lightness (nonlinear Luminance, nearly perceptually uniform). */ 00039 IM_LUV, /**< CIE L*u*v*. L* is Lightness (nonlinear Luminance, nearly perceptually uniform). */ 00040 IM_XYZ /**< CIE XYZ. Linear Light Tristimulus, Y is linear Luminance. */ 00041 }; 00042 00043 /** Image color mode configuration/extra descriptors (1 bit each in the second byte). \n 00044 * See also \ref colormodeutl. 00045 * \ingroup imagerep */ 00046 enum imColorModeConfig 00047 { 00048 IM_ALPHA = 0x100, /**< adds an Alpha channel */ 00049 IM_PACKED = 0x200, /**< packed components (rgbrgbrgb...) */ 00050 IM_TOPDOWN = 0x400 /**< orientation from top down to bottom */ 00051 }; 00052 00053 00054 00055 /** File Access Error Codes 00056 * \ingroup file */ 00057 enum imErrorCodes 00058 { 00059 IM_ERR_NONE, /**< No error. */ 00060 IM_ERR_OPEN, /**< Error while opening the file (read or write). */ 00061 IM_ERR_ACCESS, /**< Error while accessing the file (read or write). */ 00062 IM_ERR_FORMAT, /**< Invalid or unrecognized file format. */ 00063 IM_ERR_DATA, /**< Invalid or unsupported data. */ 00064 IM_ERR_COMPRESS, /**< Invalid or unsupported compression. */ 00065 IM_ERR_MEM, /**< Insuficient memory */ 00066 IM_ERR_COUNTER /**< Interrupted by the counter */ 00067 }; 00068 00069 /* Internal Image File Structure. */ 00070 typedef struct _imFile imFile; 00071 00072 /** Opens the file for reading. It must exists. Also reads file header. 00073 * It will try to identify the file format. 00074 * See also \ref imErrorCodes. \n 00075 * In Lua the IM file metatable name is "imFile". 00076 * When converted to a string will return "imFile(%p)" where %p is replaced by the userdata address. 00077 * If the file is already closed by im.FileClose, then it will return also the suffix "-closed". 00078 * 00079 * \verbatim im.FileOpen(file_name: string) -> ifile: imFile, error: number [in Lua 5] \endverbatim 00080 * \ingroup file */ 00081 imFile* imFileOpen(const char* file_name, int *error); 00082 00083 /** Opens the file for reading using a specific format. It must exists. Also reads file header. 00084 * See also \ref imErrorCodes and \ref format. 00085 * 00086 * \verbatim im.FileOpenAs(file_name, format: string) -> ifile: imFile, error: number [in Lua 5] \endverbatim 00087 * \ingroup file */ 00088 imFile* imFileOpenAs(const char* file_name, const char* format, int *error); 00089 00090 /** Creates a new file for writing using a specific format. If the file exists will be replaced. \n 00091 * It will only initialize the format driver and create the file, no data is actually written. 00092 * See also \ref imErrorCodes and \ref format. 00093 * 00094 * \verbatim im.FileNew(file_name: string, format: string) -> ifile: imFile, error: number [in Lua 5] \endverbatim 00095 * \ingroup file */ 00096 imFile* imFileNew(const char* file_name, const char* format, int *error); 00097 00098 /** Closes the file. \n 00099 * In Lua if this function is not called, the file is closed by the garbage collector. 00100 * 00101 * \verbatim im.FileClose(ifile: imFile) [in Lua 5] \endverbatim 00102 * \verbatim ifile:Close() [in Lua 5] \endverbatim 00103 * \ingroup file */ 00104 void imFileClose(imFile* ifile); 00105 00106 /** Returns an internal handle. 00107 * index=0 returns always an imBinFile* handle, 00108 * but for some formats returns NULL because they do not use imBinFile (like AVI and WMV). 00109 * index=1 return an internal structure used by the format, usually is a handle 00110 * to a third party library structure. This is file format dependent. 00111 * 00112 * \verbatim ifile:Handle() -> handle: userdata [in Lua 5] \endverbatim 00113 * \ingroup file */ 00114 void* imFileHandle(imFile* ifile, int index); 00115 00116 /** Returns file information. 00117 * image_count is the number of images in a stack or 00118 * the number of frames in a video/animation or the depth of a volume data. \n 00119 * compression and image_count can be NULL. \n 00120 * These informations are also available as attributes: 00121 * \verbatim FileFormat (string) \endverbatim 00122 * \verbatim FileCompression (string) \endverbatim 00123 * \verbatim FileImageCount IM_INT (1) \endverbatim 00124 * See also \ref format. 00125 * 00126 * \verbatim ifile:GetInfo() -> format: string, compression: string, image_count: number [in Lua 5] \endverbatim 00127 * \ingroup file */ 00128 void imFileGetInfo(imFile* ifile, char* format, char* compression, int *image_count); 00129 00130 /** Changes the write compression method. \n 00131 * If the compression is not supported will return an error code when writting. \n 00132 * Use NULL to set the default compression. You can use the imFileGetInfo to retrieve the actual compression 00133 * but only after \ref imFileWriteImageInfo. Only a few formats allow you to change the compression between frames. 00134 * 00135 * \verbatim ifile:SetInfo(compression: string) [in Lua 5] \endverbatim 00136 * \ingroup file */ 00137 void imFileSetInfo(imFile* ifile, const char* compression); 00138 00139 /** Changes an extended attribute. \n 00140 * The data will be internally duplicated. \n 00141 * If data is NULL the attribute is removed. 00142 * If data_type is BYTE then count can be -1 to indicate a NULL terminated string. 00143 * See also \ref imDataType. 00144 * 00145 * \verbatim ifile: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 file */ 00148 void imFileSetAttribute(imFile* ifile, const char* attrib, int data_type, int count, const void* data); 00149 00150 /** Returns an extended attribute. \n 00151 * Returns NULL if not found. data_type and count can be NULL. 00152 * See also \ref imDataType. 00153 * 00154 * \verbatim ifile: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 file */ 00157 const void* imFileGetAttribute(imFile* ifile, 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 ifile:GetAttributeList() -> data: table of strings [in Lua 5] \endverbatim 00163 * \ingroup file */ 00164 void imFileGetAttributeList(imFile* ifile, char** attrib, int *attrib_count); 00165 00166 /** Returns the pallete if any. \n 00167 * "palette" must be a 256 colors alocated array. \n 00168 * Returns zero in "palette_count" if there is no palette. "palette_count" is >0 and <=256. 00169 * 00170 * \verbatim ifile:GetPalette() -> palette: imPalette [in Lua 5] \endverbatim 00171 * \ingroup file */ 00172 void imFileGetPalette(imFile* ifile, long* palette, int *palette_count); 00173 00174 /** Changes the pallete. \n 00175 * "palette_count" is >0 and <=256. 00176 * 00177 * \verbatim ifile:SetPalette(palette: imPalette) [in Lua 5] \endverbatim 00178 * \ingroup file */ 00179 void imFileSetPalette(imFile* ifile, long* palette, int palette_count); 00180 00181 /** Reads the image header if any and returns image information. \n 00182 * Reads also the extended image attributes, so other image attributes will be available only after calling this function. \n 00183 * Returns an error code. 00184 * index specifies the image number between 0 and image_count-1. \n 00185 * Some drivers reads only in sequence, so "index" can be ignored by the format driver. \n 00186 * Any parameters can be NULL. This function must be called at least once, check each format documentation. 00187 * See also \ref imErrorCodes, \ref imDataType, \ref imColorSpace and \ref imColorModeConfig. 00188 * 00189 * \verbatim ifile:ReadImageInfo([index: number]) -> error: number, width: number, height: number, file_color_mode: number, file_data_type: number [in Lua 5] \endverbatim 00190 * Default index is 0. 00191 * \ingroup file */ 00192 int imFileReadImageInfo(imFile* ifile, int index, int *width, int *height, int *file_color_mode, int *file_data_type); 00193 00194 /** Writes the image header. Writes the file header at the first time it is called. 00195 * Writes also the extended image attributes. \n 00196 * Must call imFileSetPalette and set other attributes before calling this function. \n 00197 * In some formats the color space will be converted to match file format specification. \n 00198 * Returns an error code. This function must be called at least once, check each format documentation. 00199 * See also \ref imErrorCodes, \ref imDataType, \ref imColorSpace and \ref imColorModeConfig. 00200 * 00201 * \verbatim ifile:WriteImageInfo(width: number, height: number, user_color_mode: number, user_data_type: number) -> error: number [in Lua 5] \endverbatim 00202 * \ingroup file */ 00203 int imFileWriteImageInfo(imFile* ifile, int width, int height, int user_color_mode, int user_data_type); 00204 00205 /** Reads the image data with or without conversion. \n 00206 * The data can be converted to bitmap when reading. 00207 * Data type conversion to byte will always scan for min-max then scale to 0-255, 00208 * except integer values that min-max are already between 0-255. Complex to real conversions will use the magnitude. \n 00209 * Color mode flags contains packed, alpha and top-botttom information. 00210 * If flag is 0 means unpacked, no alpha and bottom up. If flag is -1 the file original flags are used. \n 00211 * Returns an error code. 00212 * See also \ref imErrorCodes, \ref imDataType, \ref imColorSpace and \ref imColorModeConfig. 00213 * 00214 * \verbatim ifile:ReadImageData(data: userdata, convert2bitmap: boolean, color_mode_flags: number) -> error: number [in Lua 5] \endverbatim 00215 * \ingroup file */ 00216 int imFileReadImageData(imFile* ifile, void* data, int convert2bitmap, int color_mode_flags); 00217 00218 /** Writes the image data. \n 00219 * Returns an error code. 00220 * 00221 * \verbatim ifile:WriteImageData(data: userdata) -> error: number [in Lua 5] \endverbatim 00222 * \ingroup file */ 00223 int imFileWriteImageData(imFile* ifile, void* data); 00224 00225 00226 00227 00228 /** Registers all the internal formats. \n 00229 * It is automatically called internally when a format is accessed, 00230 * but can be called to force the internal formats to be registered before other formats. 00231 * Notice that additional formats when registered will be registered before the internal formats 00232 * if imFormatRegisterInternal is not called yet. \n 00233 * To control the register order is usefull when two format drivers handle the same format. 00234 * The first registered format will always be used first. 00235 * \ingroup format */ 00236 void imFormatRegisterInternal(void); 00237 00238 /** Remove all registered formats. 00239 * \ingroup format */ 00240 void imFormatRemoveAll(void); 00241 00242 /** Returns a list of the registered formats. \n 00243 * format_list is an array of format identifiers. 00244 * Each format identifier is 10 chars max, maximum of 50 formats. 00245 * You can use "char* format_list[50]". 00246 * 00247 * \verbatim im.FormatList() -> format_list: table of strings [in Lua 5] \endverbatim 00248 * \ingroup format */ 00249 void imFormatList(char** format_list, int *format_count); 00250 00251 /** Returns the format description. \n 00252 * Format description is 50 chars max. \n 00253 * Extensions are separated like "*.tif;*.tiff;", 50 chars max. \n 00254 * Returns an error code. The parameters can be NULL, except format. 00255 * See also \ref format. 00256 * 00257 * \verbatim im.FormatInfo(format: string) -> error: number, desc: string, ext: string, can_sequence: boolean [in Lua 5] \endverbatim 00258 * \ingroup format */ 00259 int imFormatInfo(const char* format, char* desc, char* ext, int *can_sequence); 00260 00261 /** Returns the format compressions. \n 00262 * Compressions are 20 chars max each, maximum of 50 compressions. You can use "char* comp[50]". \n 00263 * color_mode and data_type are optional, use -1 to ignore them. \n 00264 * If you use them they will select only the allowed compressions checked like in \ref imFormatCanWriteImage. \n 00265 * Returns an error code. 00266 * See also \ref format, \ref imErrorCodes, \ref imDataType, \ref imColorSpace and \ref imColorModeConfig. 00267 * 00268 * \verbatim im.FormatCompressions(format: string, [color_mode: number], [data_type: number]) -> error: number, comp: table of strings [in Lua 5] \endverbatim 00269 * \ingroup format */ 00270 int imFormatCompressions(const char* format, char** comp, int *comp_count, int color_mode, int data_type); 00271 00272 /** Checks if the format suport the given image class at the given compression. \n 00273 * Returns an error code. 00274 * See also \ref format, \ref imErrorCodes, \ref imDataType, \ref imColorSpace and \ref imColorModeConfig. 00275 * 00276 * \verbatim im.FormatCanWriteImage(format: string, compression: string, color_mode: number, data_type: number) -> can_write: boolean [in Lua 5] \endverbatim 00277 * \ingroup format */ 00278 int imFormatCanWriteImage(const char* format, const char* compression, int color_mode, int data_type); 00279 00280 00281 #if defined(__cplusplus) 00282 } 00283 #endif 00284 00285 #include "old_im.h" 00286 00287 #endif