summaryrefslogtreecommitdiff
path: root/html/en/func/color.html
blob: fbd4b526776f1a2228643f8b5f802498ce3b2898 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<!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>
    <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) -&gt; (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>
    <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) -&gt; (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>
    <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) -&gt; (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>
    <pre class="function"><span class="mainFunction">unsigned char <a name="cdDecodeAlpha">cdDecodeAlpha</a>(long int color) [in C]</span>

cd.DecodeAlpha(color: lightuserdata) -&gt; (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>
    <pre class="function"><span class="mainFunction">unsigned char <a name="cdRed0">cdAlpha</a>(long int color); [in C]</span>

cd.Alpha(color: lightuserdata) -&gt; (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>
    <pre class="function"><span class="mainFunction">unsigned char <a name="cdRed">cdRed</a>(long int color); [in C]</span>

cd.Red(color: lightuserdata) -&gt; (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>
    <pre class="function"><span class="mainFunction">unsigned char <a name="cdGreen">cdGreen</a>(long int color); [in C]</span>

cd.Green(color: lightuserdata) -&gt; (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>
    <pre class="function"><span class="mainFunction">unsigned char <a name="cdBlue">cdBlue</a>(long int color); [in C]</span>

cd.Blue(color: lightuserdata) -&gt; (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>
    <pre class="function"><span class="mainFunction">int <a name="cdGetColorPlanes">cdCanvasGetColorPlanes</a>(cdCanvas* canvas); [in C]</span>

canvas:GetColorPlanes() -&gt; (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>
    <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&nbsp; <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>

<h3><a name="Palette">Palette</a></h3>

    <pre class="function"><a name="cdCreatePalette">cd.CreatePalette</a>(size: number) -&gt; (palette: cdPalette) [in Lua Only]</pre>
    <p>Creates a palette.</p>
    <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>

<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>