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