im.im_palette source code

1 /** \file
2  * \brief Palette Generators
3  *
4  * See Copyright Notice in im_lib.h
5  */
6 module im.im_palette;
7 
8 version(IM) :
9 
10 import core.stdc.config : c_long;
11 
12 version(DigitalMars) version(Windows) { pragma(lib, "im.lib"); }
13 
14 extern @nogc nothrow :
15 
16 
17 /** \defgroup palette Palette Generators
18  * \par
19  * Creates several standard palettes. The palette is just an array of encoded color values.
20  * See also \ref colorutl.
21  * \par
22  * In Lua, to create a palette you can call im.PaletteCreate.
23  * \verbatim im.PaletteCreate([count: number]) -> pal: imPalette [in Lua 5] \endverbatim
24  * Default count is 256.
25  * IMLua and CDLua palettes are 100% compatible. The IM palette metatable name is "imPalette". \n
26  * When converted to a string will return "imPalete(%p)" where %p is replaced by the userdata address.
27  * If the palette is already destroyed by im.PaletteDestroy, then it will return also the suffix "-destroyed".
28  * \par
29  * In Lua, to destroy a palette you can call im.PaletteDestroy.
30  * If this function is not called, the palette is destroyed by the garbage collector.
31  * \verbatim im.PaletteDestroy(pal: imPalette) [in Lua 5] \endverbatim
32  * \par
33  * In Lua, array access is enabled so you can do:.
34  * \verbatim color = pal[index] \endverbatim
35  * \verbatim pal[index] = color \endverbatim
36  * \verbatim count = #pal \endverbatim
37  * \par
38  * See \ref im_palette.h
39  * \ingroup util */
40 
41 
42 /** Allocates memory for the palette data.
43  * This ensures allocation and release in the same module by the correct functions.
44  * \ingroup palette */
45 c_long* imPaletteNew(int count);
46 
47 /** Releases memory for the palette data.
48  * This ensures allocation and release in the same module by the correct functions.
49  * \ingroup palette */
50 void imPaletteRelease(c_long* palette);
51 
52 /** Duplicate a palette data using imPaletteNew.
53  * \ingroup palette */
54 c_long* imPaletteDuplicate(const(c_long)* palette, int count);
55 
56 
57 /** Searches for the nearest color on the table and returns the color index if successful. 
58  * It looks in all palette entries and finds the minimum euclidian square distance. 
59  * If the color matches the given color it returns immediately.
60  * See also \ref colorutl.
61  *
62  * \verbatim im.PaletteFindNearest(pal: imPalette, color: lightuserdata) -> index: number [in Lua 5] \endverbatim
63  * \ingroup palette */
64 int imPaletteFindNearest(const(c_long)* palette, int palette_count, c_long color);
65 
66 /** Searches for the color on the table and returns the color index if successful. 
67  * If the tolerance is 0 search for the exact match in the palette else search for the 
68  * first color that fits in the tolerance range.
69  * See also \ref colorutl.
70  *
71  * \verbatim im.PaletteFindColor(pal: imPalette, color: lightuserdata, tol: number) -> index: number [in Lua 5] \endverbatim
72  * \ingroup palette */
73 int imPaletteFindColor(const(c_long)* palette, int palette_count, c_long color, ubyte tol);
74 
75 /** Creates a palette of gray scale values.
76  * The colors are arranged from black to white.
77  *
78  * \verbatim im.PaletteGray() -> pal: imPalette [in Lua 5] \endverbatim
79  * \ingroup palette */
80 c_long* imPaletteGray();
81 
82 /** Creates a palette of a gradient of red colors.
83  * The colors are arranged from black to pure red.
84  *
85  * \verbatim im.PaletteRed() -> pal: imPalette [in Lua 5] \endverbatim
86  * \ingroup palette */
87 c_long* imPaletteRed();
88 
89 /** Creates a palette of a gradient of green colors.
90  * The colors are arranged from black to pure green.
91  *
92  * \verbatim im.PaletteGreen() -> pal: imPalette [in Lua 5] \endverbatim
93  * \ingroup palette */
94 c_long* imPaletteGreen();
95 
96 /** Creates a palette of a gradient of blue colors.
97  * The colors are arranged from black to pure blue.
98  *
99  * \verbatim im.PaletteBlue() -> pal: imPalette [in Lua 5] \endverbatim
100  * \ingroup palette */
101 c_long* imPaletteBlue();
102 
103 /** Creates a palette of a gradient of yellow colors.
104  * The colors are arranged from black to pure yellow.
105  *
106  * \verbatim im.PaletteYellow() -> pal: imPalette [in Lua 5] \endverbatim
107  * \ingroup palette */
108 c_long* imPaletteYellow();
109 
110 /** Creates a palette of a gradient of magenta colors.
111  * The colors are arranged from black to pure magenta.
112  *
113  * \verbatim im.PaletteMagenta() -> pal: imPalette [in Lua 5] \endverbatim
114  * \ingroup palette */
115 c_long* imPaletteMagenta();
116 
117 /** Creates a palette of a gradient of cian colors.
118  * The colors are arranged from black to pure cian.
119  *
120  * \verbatim im.PaletteCian() -> pal: imPalette [in Lua 5] \endverbatim
121  * \ingroup palette */
122 c_long* imPaletteCian();
123 
124 /** Creates a palette of rainbow colors.
125  * The colors are arranged in the light wave length spectrum order (starting from purple).
126  *
127  * \verbatim im.PaletteRainbow() -> pal: imPalette [in Lua 5] \endverbatim
128  * \ingroup palette */
129 c_long* imPaletteRainbow();
130 
131 /** Creates a palette of hues with maximum saturation.
132  *
133  * \verbatim im.PaletteHues() -> pal: imPalette [in Lua 5] \endverbatim
134  * \ingroup palette */
135 c_long* imPaletteHues();
136 
137 /** Creates a palette of a gradient of blue colors.
138  * The colors are arranged from pure blue to white.
139  *
140  * \verbatim im.PaletteBlueIce() -> pal: imPalette [in Lua 5] \endverbatim
141  * \ingroup palette */
142 c_long* imPaletteBlueIce();
143 
144 /** Creates a palette of a gradient from black to white passing trough red and orange.
145  *
146  * \verbatim im.PaletteHotIron() -> pal: imPalette [in Lua 5] \endverbatim
147  * \ingroup palette */
148 c_long* imPaletteHotIron();
149 
150 /** Creates a palette of a gradient from black to white passing trough red and yellow.
151  *
152  * \verbatim im.PaletteBlackBody() -> pal: imPalette [in Lua 5] \endverbatim
153  * \ingroup palette */
154 c_long* imPaletteBlackBody();
155 
156 /** Creates a palette with high contrast colors.
157  *
158  * \verbatim im.PaletteHighContrast() -> pal: imPalette [in Lua 5] \endverbatim
159  * \ingroup palette */
160 c_long* imPaletteHighContrast();
161 
162 /** Creates a palette of a sequence of colors from black to white 
163  *  with 32 linear intensity values combined with 8 hue variations.
164  *
165  * \verbatim im.PaletteLinear() -> pal: imPalette [in Lua 5] \endverbatim
166  * \ingroup palette */
167 c_long* imPaletteLinear();
168 
169 /** Creates a palette of an uniform sub-division of colors from black to white.
170 *  This is a 2^(2.6) bits per pixel palette.
171 *
172 * \verbatim im.PaletteUniform() -> pal: imPalette [in Lua 5] \endverbatim
173 * \ingroup palette */
174 c_long* imPaletteUniform();
175 
176 /** Returns the index of the correspondent RGB color of an uniform palette.
177  *
178  * \verbatim im.PaletteUniformIndex(color: lightuserdata) -> index: number [in Lua 5] \endverbatim
179  * \ingroup palette */
180 int imPaletteUniformIndex(c_long color);
181 
182 /** Returns the index of the correspondent RGB color of an uniform palette.
183  * Uses an 8x8 ordered dither to lookup the index in a halftone matrix.
184  * The spatial position used by the halftone method.
185  *
186  * \verbatim im.PaletteUniformIndexHalftoned(color: lightuserdata, x: number, y: number) -> index: number [in Lua 5] \endverbatim
187  * \ingroup palette */
188 int imPaletteUniformIndexHalftoned(c_long color, int x, int y);