00001 /** \file
00002  * \brief Palette Generators
00003  *
00004  * See Copyright Notice in im_lib.h
00005  */
00006 
00007 #ifndef __IM_PALETTE_H
00008 #define __IM_PALETTE_H
00009 
00010 #if defined(__cplusplus)
00011 extern "C" {
00012 #endif
00013 
00014 
00015 /** \defgroup palette Palette Generators
00016  * \par
00017  * Creates several standard palettes. The palette is just an array of encoded color values.
00018  * See also \ref colorutl.
00019  * \par
00020  * In Lua, to create a palette you can call im.PaletteCreate.
00021  * \verbatim im.PaletteCreate([count: number]) -> pal: imPalette [in Lua 5] \endverbatim
00022  * Default count is 256.
00023  * IMLua and CDLua palettes are 100% compatible. The IM palette metatable name is "imPalette". \n
00024  * When converted to a string will return "imPalete(%p)" where %p is replaced by the userdata address.
00025  * If the palette is already destroyed by im.PaletteDestroy, then it will return also the suffix "-destroyed".
00026  * \par
00027  * In Lua, to destroy a palette you can call im.PaletteDestroy.
00028  * If this function is not called, the palette is destroyed by the garbage collector.
00029  * \verbatim im.PaletteDestroy(pal: imPalette) [in Lua 5] \endverbatim
00030  * \par
00031  * In Lua, array access is enabled so you can do:.
00032  * \verbatim color = pal[index] \endverbatim
00033  * \verbatim pal[index] = color \endverbatim
00034  * \verbatim count = #pal \endverbatim
00035  * \par
00036  * See \ref im_palette.h
00037  * \ingroup util */
00038 
00039 
00040 /** Searches for the nearest color on the table and returns the color index if successful. 
00041  * It looks in all palette entries and finds the minimum euclidian square distance. 
00042  * If the color matches the given color it returns immediately.
00043  * See also \ref colorutl.
00044  *
00045  * \verbatim im.PaletteFindNearest(pal: imPalette, color: lightuserdata) -> index: number [in Lua 5] \endverbatim
00046  * \ingroup palette */
00047 int imPaletteFindNearest(const long *palette, int palette_count, long color);
00048 
00049 /** Searches for the color on the table and returns the color index if successful. 
00050  * If the tolerance is 0 search for the exact match in the palette else search for the 
00051  * first color that fits in the tolerance range.
00052  * See also \ref colorutl.
00053  *
00054  * \verbatim im.PaletteFindColor(pal: imPalette, color: lightuserdata, tol: number) -> index: number [in Lua 5] \endverbatim
00055  * \ingroup palette */
00056 int imPaletteFindColor(const long *palette, int palette_count, long color, unsigned char tol);
00057 
00058 /** Creates a palette of gray scale values.
00059  * The colors are arranged from black to white.
00060  *
00061  * \verbatim im.PaletteGray() -> pal: imPalette [in Lua 5] \endverbatim
00062  * \ingroup palette */
00063 long* imPaletteGray(void);
00064 
00065 /** Creates a palette of a gradient of red colors.
00066  * The colors are arranged from black to pure red.
00067  *
00068  * \verbatim im.PaletteRed() -> pal: imPalette [in Lua 5] \endverbatim
00069  * \ingroup palette */
00070 long* imPaletteRed(void);
00071 
00072 /** Creates a palette of a gradient of green colors.
00073  * The colors are arranged from black to pure green.
00074  *
00075  * \verbatim im.PaletteGreen() -> pal: imPalette [in Lua 5] \endverbatim
00076  * \ingroup palette */
00077 long* imPaletteGreen(void);
00078 
00079 /** Creates a palette of a gradient of blue colors.
00080  * The colors are arranged from black to pure blue.
00081  *
00082  * \verbatim im.PaletteBlue() -> pal: imPalette [in Lua 5] \endverbatim
00083  * \ingroup palette */
00084 long* imPaletteBlue(void);
00085 
00086 /** Creates a palette of a gradient of yellow colors.
00087  * The colors are arranged from black to pure yellow.
00088  *
00089  * \verbatim im.PaletteYellow() -> pal: imPalette [in Lua 5] \endverbatim
00090  * \ingroup palette */
00091 long* imPaletteYellow(void);
00092 
00093 /** Creates a palette of a gradient of magenta colors.
00094  * The colors are arranged from black to pure magenta.
00095  *
00096  * \verbatim im.PaletteMagenta() -> pal: imPalette [in Lua 5] \endverbatim
00097  * \ingroup palette */
00098 long* imPaletteMagenta(void);
00099 
00100 /** Creates a palette of a gradient of cian colors.
00101  * The colors are arranged from black to pure cian.
00102  *
00103  * \verbatim im.PaletteCian() -> pal: imPalette [in Lua 5] \endverbatim
00104  * \ingroup palette */
00105 long* imPaletteCian(void);
00106 
00107 /** Creates a palette of rainbow colors.
00108  * The colors are arranged in the light wave length spectrum order (starting from purple).
00109  *
00110  * \verbatim im.PaletteRainbow() -> pal: imPalette [in Lua 5] \endverbatim
00111  * \ingroup palette */
00112 long* imPaletteRainbow(void);
00113 
00114 /** Creates a palette of hues with maximum saturation.
00115  *
00116  * \verbatim im.PaletteHues() -> pal: imPalette [in Lua 5] \endverbatim
00117  * \ingroup palette */
00118 long* imPaletteHues(void);
00119 
00120 /** Creates a palette of a gradient of blue colors.
00121  * The colors are arranged from pure blue to white.
00122  *
00123  * \verbatim im.PaletteBlueIce() -> pal: imPalette [in Lua 5] \endverbatim
00124  * \ingroup palette */
00125 long* imPaletteBlueIce(void);
00126 
00127 /** Creates a palette of a gradient from black to white passing trough red and orange.
00128  *
00129  * \verbatim im.PaletteHotIron() -> pal: imPalette [in Lua 5] \endverbatim
00130  * \ingroup palette */
00131 long* imPaletteHotIron(void);
00132 
00133 /** Creates a palette of a gradient from black to white passing trough red and yellow.
00134  *
00135  * \verbatim im.PaletteBlackBody() -> pal: imPalette [in Lua 5] \endverbatim
00136  * \ingroup palette */
00137 long* imPaletteBlackBody(void);
00138 
00139 /** Creates a palette with high contrast colors.
00140  *
00141  * \verbatim im.PaletteHighContrast() -> pal: imPalette [in Lua 5] \endverbatim
00142  * \ingroup palette */
00143 long* imPaletteHighContrast(void);
00144 
00145 /** Creates a palette of an uniform range of colors from black to white.
00146  *  This is a 2^(2.6) bits per pixel palette.
00147  *
00148  * \verbatim im.PaletteUniform() -> pal: imPalette [in Lua 5] \endverbatim
00149  * \ingroup palette */
00150 long* imPaletteUniform(void);
00151 
00152 /** Returns the index of the correspondent RGB color of an uniform palette.
00153  *
00154  * \verbatim im.PaletteUniformIndex(color: lightuserdata) -> index: number [in Lua 5] \endverbatim
00155  * \ingroup palette */
00156 int imPaletteUniformIndex(long color);
00157 
00158 /** Returns the index of the correspondent RGB color of an uniform palette.
00159  * Uses an 8x8 ordered dither to lookup the index in a halftone matrix.
00160  * The spatial position used by the halftone method.
00161  *
00162  * \verbatim im.PaletteUniformIndexHalftoned(color: lightuserdata, x: number, y: number) -> index: number [in Lua 5] \endverbatim
00163  * \ingroup palette */
00164 int imPaletteUniformIndexHalftoned(long color, int x, int y);
00165 
00166 
00167 #if defined(__cplusplus)
00168 }
00169 #endif
00170 
00171 #endif
00172