<!doctype HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Color Coding</title>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../style.css">
</head>
<body>
<h2 align="center">Color Coding</h2>
<p>The library's color system is RGB. In order to simplify some functions, a
compact representation was created for the 3 values. To make a conversion from
this representation to the 3 separate values and vice-versa, use functions
<b> <font>cdDecodeColor</font></b>
and <b> <font>cdEncodeColor</font></b>.
</p>
<p>When the canvas used does not support more than 8 bpp of color resolution, you
can use function <b> <font>Palette</font></b> to give the driver an idea of which
colors to prioritize. <b> <font>Palette</font>'s</b> behavior is driver dependent.</p>
<p>There are some predefined colors:</p>
<pre>CD_RED = (255, 0, 0)
CD_DARK_RED = (128, 0, 0)
CD_GREEN = (0 ,255, 0)
CD_DARK_GREEN = ( 0,128, 0)
CD_BLUE = ( 0, 0,255)
CD_DARK_BLUE = ( 0, 0,128)
CD_YELLOW = (255,255, 0)
CD_DARK_YELLOW = (128,128, 0)
CD_MAGENTA = (255, 0,255)
CD_DARK_MAGENTA = (128, 0,128)
CD_CYAN = ( 0,255,255)
CD_DARK_CYAN = ( 0,128,128)
CD_WHITE = (255,255,255)
CD_BLACK = ( 0, 0 , 0)
CD_DARK_GRAY = (128,128,128)
CD_GRAY = (192,192,192)
</pre>
<hr>
<div class="function"><pre class="function"><span class="mainFunction">long int <a name="cdEncodeColor">cdEncodeColor</a>(unsigned char red, unsigned char green, unsigned char blue) [in C]</span>
cd.EncodeColor(r, g, b: number) -> (old_color: lightuserdata) [in Lua]</pre>
<p>Returns a codified triple (<em>r,g,b</em>) in a long integer such as <b><tt>0x00RRGGBB</tt></b>,
where <tt><b>RR</b> </tt>are the red components, <b><tt>GG</tt></b> are the
green ones and <b><tt>BB</tt></b> are the blue ones. The code is used in the CD
library to define colors. It can be used without an active canvas.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">void <a name="cdDecodeColor">cdDecodeColor</a>(long int color, unsigned char *red, unsigned char *green, unsigned char *blue) [in C]</span>
cd.DecodeColor(color: lightuserdata) -> (r, g, b: number) [in Lua]</pre>
<p>Returns the red, green and blue components of a color in the CD library. Can
be used without an active canvas.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">long int <a name="cdEncodeAlpha">cdEncodeAlpha</a>(long int color, unsigned char alpha) [in C]</span>
cd.EncodeAlpha(color: lightuserdata, alpha: number) -> (color: lightuserdata) [in Lua]</pre>
<p>Returns the given color coded with the alpha information. ATENTION: At the
moment only the <a href="../drv/cairo.html">Cairo</a>,
<a href="../drv/gdiplus.html">GDI+</a>, <a href="../drv/xrender.html">XRender</a>
and <a href="../drv/irgb.html">IMAGERGB</a>
drivers support alpha components in color coding. The
internal representation of the component is inverted, because the default value
must be 0 and opaque for backward compatibility, so you should use the <strong>cdDecodeAlpha</strong>
function or the <strong>cdAlpha</strong> macro to retrieve the alpha component.
0 is transparent, 255 is opaque.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">unsigned char <a name="cdDecodeAlpha">cdDecodeAlpha</a>(long int color) [in C]</span>
cd.DecodeAlpha(color: lightuserdata) -> (a: number) [in Lua]</pre>
<p>Returns the alpha component of a color in the CD library. Can be used without
an active canvas. 0 is transparent, 255 is opaque.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">unsigned char <a name="cdRed0">cdAlpha</a>(long int color); [in C]</span>
cd.Alpha(color: lightuserdata) -> (r: number) [in Lua]</pre>
<p>Macro that returns the alpha component of a color in the CD library. Can be
used without an active canvas.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">unsigned char <a name="cdRed">cdRed</a>(long int color); [in C]</span>
cd.Red(color: lightuserdata) -> (r: number) [in Lua]</pre>
<p>Macro that returns the red component of a color in the CD library. Can be used
without an active canvas.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">unsigned char <a name="cdGreen">cdGreen</a>(long int color); [in C]</span>
cd.Green(color: lightuserdata) -> (g: number) [in Lua]</pre>
<p>Macro that returns the green component of a color in the CD library. Can be
used without an active canvas.</p>
</div><div class="function"><pre class="function"><span class="mainFunction">unsigned char <a name="cdBlue">cdBlue</a>(long int color); [in C]</span>
cd.Blue(color: lightuserdata) -> (b: number) [in Lua]</pre>
<p>Macro that returns the blue component of a color in the CD library. Can be
used without an active canvas.</p>
<hr>
</div><div class="function"><pre class="function"><span class="mainFunction">int <a name="cdGetColorPlanes">cdCanvasGetColorPlanes</a>(cdCanvas* canvas); [in C]</span>
canvas:GetColorPlanes() -> (bpp: number) [in Lua]</pre>
<p>Returns a given number, for instance <i>p</i>, which defines the number of
colors supported by the current device as <i>2<sup>p</sup></i>, representing
the number of bits by pixel.
</p>
</div><div class="function"><pre class="function"><span class="mainFunction">void <a name="cdPalette">cdCanvasPalette</a>(cdCanvas* canvas, int n, const long int *color, int mode); [in C]</span>
canvas:Palette(palette: cdPalette; mode: number) [in Lua]</pre>
<p>In systems limited to 256 palette colors, this function aims at adding <b><tt>
n</tt></b> colors to the system's palette. In such systems, the colors
demanded forward or backward which are not in the palette are approximated to
the closest available color. The type can be <tt><b>CD_FORCE</b> </tt>or <b><tt>CD_POLITE</tt></b>.
<b><tt>CD_FORCE</tt></b> ignores the system colors and interface elements,
since the menus and dialogues may be in illegible colors, but there will be
more colors available. <tt><b>CD_POLITE</b></tt> is the recommended type. It
must always be used before drawing. It cannot be queried.</p>
</div>
<h3><a name="Palette">Palette</a></h3>
<div class="function"><pre class="function"><a name="cdCreatePalette">cd.CreatePalette</a>(size: number) -> (palette: cdPalette) [in Lua Only]</pre>
<p>Creates a palette.</p>
</div><div class="function"><pre class="function"><a name="cdKillPalette">cd.KillPalette</a>(palette: cdPalette) [in Lua Only]</pre>
<p>Destroys the created palette and liberates allocated memory. If this
function is not called in Lua, the garbage collector will call it.</p>
</div>
<h3>Palette <a name="DataAccess">Data Access</a></h3>
<p>Data access in Lua is done directly using the array access operators. The
colors can have their values checked or changed directly as if they
were Lua tables:</p>
<pre>palette[index] = cd.EncodeColor(r, g, b)
count = #palette
...
color = palette[index]
r, g, b = cd.DecodeColor(color)</pre>
<p>Notice that the type of value returned or received by
<font size="3">palette[index]</font><font size="2"> </font>is a
<font>lightuserdata</font>, the same type used with functions <b>
<font size="3">cdEncodeColor</font></b>, <b>
<font size="3">cdDecodeColor</font></b>, <b>
<font size="3">cdPixel</font></b>, <b>
<font size="3">cdForeground</font></b><font size="2">
</font>and <b> <font size="3">cdBackground</font></b>.</p>
</body>
</html>