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