summaryrefslogtreecommitdiff
path: root/html/en/drv/cairo.html
blob: 04cb3e936f7813db3a5ef79a3d4afce984713d5f (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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
<!doctype HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>CAIRO</title>
<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
.style1 {
	font-family: Courier;
}
.style3 {
	text-decoration: underline;
}
</style>
</head>

<body>

<h2>CAIRO Base Driver</h2>

  <p>This driver represents a basic driver for all system-dependent drivers 
  implemented in the X-Windows and MS-Windows systems. The implementation uses the
  <a href="http://library.gnome.org/devel/pango/">Cairo</a> and Pango functions. This driver can be 
  compiled and used in all systems Cairo is supported. The drivers <b>Native Window</b>, 
	<b>Image</b>, <b>EMF</b>, <b>Printer</b> and <b>Double Buffer</b> were implemented.</p>
<p>The main motivation for the use of Cairo was transparency for all the 
primitives. Beyond that we got other features like anti-aliasing, gradient 
filling, transformations and other back-ends (support to rendering: PDF, PS, SVG and 
IMAGERGB surfaces).</p>
<p>This driver still does not completely replace the X-Windows and GDI Windows 
base drivers, because Cairo does not have support for bitwise XOR operations and 
for complex clipping regions.</p>
  <p>So we let the programmer to choose what to use. We created the function <font face="Courier"><strong>
  cdUseContextPlus</strong></font> that allows to activate or to deactivate the use of 
	Cairo for the available GDK, Win32 or X-Windows based drivers. 
  This function affects only the <font face="Courier"><strong>cdCreateCanvas</strong></font> function call, once created 
  the canvas will be always a Cairo canvas. In fact the function affects primary the definitions 
	<font face="Courier"><strong>CD_NATIVEWINDOW</strong></font>, 
  <strong><span style="font-family: Courier">CD_IMAGE</span></strong>, 
  <strong><span style="font-family: Courier">CD_EMF</span></strong>, 
  <strong><span style="font-family: Courier">CD_PRINTER</span></strong> and <strong>
  <span style="font-family: Courier">CD_DBUFFER</span></strong>, because they are 
  function calls and not static defines. 
  <strong><span style="font-family: Courier">CD_PRINTER</span></strong> can be used with 
	the GDK base driver in UNIX, or with the Win32 base driver in Windows. 
  <strong><span style="font-family: Courier">CD_EMF </span></strong> can be used 
	in Windows only, with GDK or Win32 base drivers.</p>
  <p>Using Cairo it is allowed to create more that one canvas at the same time for the same Window. And they can co-exist 
  with a standard GDK, Win32 or X-Windows canvas.</p>
  <p>To enable the use of Cairo based drivers you must call the initialization function <font face="Courier"><strong>
  cdInitContextPlus()</strong></font> once and link to the libraries &quot;<strong>cdcairo</strong>&quot; and &quot;<strong>cairo</strong>&quot;. Also the Cairo library must be installed in your system. 
	When using the GDK base driver you do not need to link with the &quot;<strong>cdcairo</strong>&quot; 
	library. </p>
  <p>In CDLua it is not necessary any additional initialization, and <strong>require&quot;cdluacairo&quot;</strong> can be used when 
	using dynamic libraries. But when using require there are some restrictions, 
	in Win32 the GDK base driver can NOT be used, in Linux the X11 base driver 
	can NOT be used, and in other UNICES the GDK base driver can NOT be used.</p>

<h3>Extra Drivers (cdcairo.h)</h3>
<p>Only available in Lua when <strong>require&quot;cdluacairo&quot;</strong> is 
used.</p>

<h4>CD_CAIRO_PS - PostScript Driver</h4>

  <p>Similar to <a href="ps.html">CD_PS</a>, uses the same creation parameters. 
	But margins are not supported and Postscript level can be 2 (parameter -2) 
	or 3 (parameter -3). The &quot;CMD&quot; attribute is not supported, and the new 
	attribute &quot;DSCCOMMENT&quot; accepts a string that is saved as a DSC comment.</p>

<h4>CD_CAIRO_PDF - PDF Driver</h4>

  <p>Similar to <a href="pdf.html">CD_PDF</a>, uses the same creation 
	parameters. The driver also does not depends on the PDFLib. The additional 
	attributes &quot;OPACITY&quot;, &quot;PATTERN&quot;, &quot;PDF&quot;, &quot;PDFLIBVERSION&quot; and the description 
	strings, are not supported.</p>
<h4>CD_CAIRO_SVG - Scalable Vector Graphics Driver</h4>

  <p>Similar to <a href="svg.html">CD_SVG</a>, uses the same creation 
	parameters. The additional attributes &quot;OPACITY&quot; and &quot;CMD&quot; are not supported.</p>

<h4>CD_CAIRO_IMAGERGB - RGB Client Image Driver</h4>

  <p>Similar to <a href="irgb.html">CD_IMAGERGB</a>, uses <span class="style3">
	almost</span> the same creation parameters. The main difference is that the 
	data pointers are packed in RGBARGBARGBA... format. So it is used only 1 
	pointer for data, instead of 3. Also the attributes &quot;REDIMAGE&quot;, 
	&quot;GREENIMAGE&quot;, &quot;BLUEIMAGE&quot; and &quot;ALPHAIMAGE are not supported and replaced by 
	the &quot;RGBDATA&quot; attribute. There are also two new attributes, &quot;STRIDE&quot; that 
	returns the line size in bytes, when data is specified during creation then 
	stride is always width*32. Even when there is not alpha channel, data is 
	stored in 32 bits per pixel. Image data is also organized in top-bottom 
	orientation, it means the data pointer points to the top-left corner. And 
	the &quot;WRITE2PNG&quot; attribute that accepts a filename to save the image as a PNG 
	file (this does not depends of the
	<a href="http://www.tecgraf.puc-rio.br/im">IM</a> library).</p>

<h3>Behavior of Functions</h3>
<h4>Control&nbsp; </h4>
<ul>
  <li><a href="../func/other.html#cdPlay">
  <font face="Courier"><strong>Play</strong></font></a>: does nothing, returns
  <font face="Courier">CD_ERROR</font>. </li>
</ul>
<h4>Coordinate System and Clipping </h4>
<ul>
  <li>
  <a href="../func/coordinates.html#cdUpdateYAxis">
  <font face="Courier"><strong>UpdateYAxis</strong></font></a>: the 
  orientation of axis Y is the opposite to its orientation in the CD library.</li>
</ul>
<h4>Primitives</h4>
<ul>
	<li>Floating point primitives are supported.</li>
</ul>
<h4>Attributes </h4>
<ul>
  <li>
  <a href="http://www.tecgraf.puc-rio.br/cd/en/func/attributes.html#cdWriteMode">
  <font face="Courier"><strong>WriteMode</strong></font></a>: does nothing. 
  There is no support for XOR or NOT_XOR.</li>
  <li>
  <a href="../func/text.html#cdNativeFont">
  <font face="Courier"><strong>NativeFont</strong></font></a>: also accepts the 
  X-Windows font string format.</li>
    <li><a href="../func/text.html#cdFont">
  <font face="Courier"><strong>Font</strong></font></a>: &quot;Courier&quot; is mapped to 
	&quot;Monospace&quot;, &quot;Helvetica&quot; is mapped to &quot;Sans&quot;, and &quot;Times&quot; is mapped to 
	&quot;Serif&quot;. Underline and Strikeout are supported.</li>
</ul>
<h4>Colors </h4>
<ul>
  <li>
  <a href="../func/color.html#cdPalette">
  <font face="Courier"><strong>Palette</strong></font></a>: NOT supported.</li>
</ul>
<h4>Exclusive Attributes</h4>

<ul>
  <li>&quot;<b><font face="Courier">ANTIALIAS</font></b>&quot;:&nbsp;controls 
  the use of anti-aliasing for the text and drawing shapes. Assumes values &quot;1&quot; 
  (active) and &quot;0&quot; (inactive). Default value: &quot;1&quot;.</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">CAIRODC</font></b>&quot;:&nbsp;returns the 
  Cairo drawing context (get only). In Lua is returned as a user data.</li>
</ul>

<ul>
    <li><b><font face="Courier">&quot;CAIROVERSION&quot;: </font></b>returns a string with 
  the Cairo version number. It is empty if the Cairo is not available.</li>
</ul>

<ul>
  <li><strong><span style="font-family: Courier">&quot;HATCHBOXSIZE&quot;</span></strong>: 
  defines the size of smallest hatch box pattern. This affects the spacing 
  between the hatch lines. The value passed must be a string containing an 
  integer (&quot;%d&quot;). If the value of the attribute passed is NULL, the value is 
  rest to the default. When consulted returns the current value (&quot;%d&quot;). Default: 
  &quot;8&quot;.</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">IMGINTERP</font></b>&quot;:&nbsp;changes how 
  interpolation is used in image scale. Can be &quot;BEST&quot; (highest-quality), 
  &quot;BILINEAR&quot; (linear interpolation), &quot;GOOD&quot; (quality similar to BILINEAR), 
  &quot;NEAREST&quot; (nearest-neighbor filtering) or &quot;FAST&quot; (quality similar to NEAREST). 
  Default: &quot;GOOD&quot;.</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">LINEGRADIENT</font></b>&quot;:&nbsp;defines 
  a filled interior style that uses a line gradient between two colors. It uses 
  2 points (&quot;%d %d %d %d&quot; = x1 y1 x2 y2), one for the starting point using 
  (using the foreground color), and another one for the end point (using the 
  background color).</li>
</ul>

<ul>
  <li>&quot;<span class="style1"><strong>PATTERNIMAGE</strong></span>&quot;:&nbsp;defines 
  a filled interior style using a server image as pattern. Data must be a server 
	image handle created with he Cairo base driver.</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">POLYHOLE</font></b>&quot;:&nbsp;defines the index of 
  the vertex where there is a hole in a closed polygon. It will affect the next
  <strong>cdEnd</strong>. Can be called several times between <strong>cdBegin</strong> 
  and <strong>cdEnd</strong> to define holes. The value passed must be a string 
  containing an integer (&quot;%d&quot;). If the value of the attribute passed is NULL, 
  all holes will no longer be considered.&nbsp;When consulted returns the current 
  number of holes (&quot;%d&quot;). It can have a maximum of 500 holes. Default: NULL.</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">RADIALGRADIENT</font></b>&quot;:&nbsp;defines 
  a filled interior style that uses a radial gradient between two colors. It 
  uses 2 points and 2 radius (&quot;%d %d %g %d %d %g&quot; = x1 y1 rad1 x2 y2 rad2), one 
  for the starting point using (using the foreground color), and another one for 
  the end point (using the background color).</li>
</ul>

<ul>
  <li>&quot;<b><font face="Courier">ROTATE</font></b>&quot;:&nbsp; allows the usage of 1 
	angle and 1 coordinate (x, y), that define a global rotation transformation 
	centered in the specified coordinate. Use 1 real and 2 integer values inside 
	a string (&quot;%g %d %d&quot; = angle x y). Can not be set if a transformation is 
	already set.</li>
</ul>

</body>

</html>