im.h

Go to the documentation of this file.
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

Generated on Thu Oct 1 11:40:01 2009 for IM by  doxygen 1.6.1