root/trunk/cairo/README.html

Revision 228, 21.3 kB (checked in by DRK, 4 years ago)

* Updated the bindings to support cairo 1.2 and cairo 1.4. Support for these can be enabled with the cairo_1_2 and cairo_1_4 version identifiers.
* Added pdf, ps and svg support.
* Updated the build script appropriately.
* Note that cairooo is not likely to receive any further updates in its current form. It is being forked and rewritten for Tango's graphics package, although a port back to Phobos isn't out of the question.

Line 
1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7 <title>cairo bindings for D</title>
8 <style type="text/css">
9
10 /*
11 :Author: David Goodger
12 :Contact: goodger@python.org
13 :Date: $Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006) $
14 :Revision: $Revision: 4564 $
15 :Copyright: This stylesheet has been placed in the public domain.
16
17 Default cascading style sheet for the HTML output of Docutils.
18
19 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
20 customize this style sheet.
21 */
22
23 /* used to remove borders from tables and images */
24 .borderless, table.borderless td, table.borderless th {
25   border: 0 }
26
27 table.borderless td, table.borderless th {
28   /* Override padding for "table.docutils td" with "! important".
29      The right padding separates the table cells. */
30   padding: 0 0.5em 0 0 ! important }
31
32 .first {
33   /* Override more specific margin styles with "! important". */
34   margin-top: 0 ! important }
35
36 .last, .with-subtitle {
37   margin-bottom: 0 ! important }
38
39 .hidden {
40   display: none }
41
42 a.toc-backref {
43   text-decoration: none ;
44   color: black }
45
46 blockquote.epigraph {
47   margin: 2em 5em ; }
48
49 dl.docutils dd {
50   margin-bottom: 0.5em }
51
52 /* Uncomment (and remove this text!) to get bold-faced definition list terms
53 dl.docutils dt {
54   font-weight: bold }
55 */
56
57 div.abstract {
58   margin: 2em 5em }
59
60 div.abstract p.topic-title {
61   font-weight: bold ;
62   text-align: center }
63
64 div.admonition, div.attention, div.caution, div.danger, div.error,
65 div.hint, div.important, div.note, div.tip, div.warning {
66   margin: 2em ;
67   border: medium outset ;
68   padding: 1em }
69
70 div.admonition p.admonition-title, div.hint p.admonition-title,
71 div.important p.admonition-title, div.note p.admonition-title,
72 div.tip p.admonition-title {
73   font-weight: bold ;
74   font-family: sans-serif }
75
76 div.attention p.admonition-title, div.caution p.admonition-title,
77 div.danger p.admonition-title, div.error p.admonition-title,
78 div.warning p.admonition-title {
79   color: red ;
80   font-weight: bold ;
81   font-family: sans-serif }
82
83 /* Uncomment (and remove this text!) to get reduced vertical space in
84    compound paragraphs.
85 div.compound .compound-first, div.compound .compound-middle {
86   margin-bottom: 0.5em }
87
88 div.compound .compound-last, div.compound .compound-middle {
89   margin-top: 0.5em }
90 */
91
92 div.dedication {
93   margin: 2em 5em ;
94   text-align: center ;
95   font-style: italic }
96
97 div.dedication p.topic-title {
98   font-weight: bold ;
99   font-style: normal }
100
101 div.figure {
102   margin-left: 2em ;
103   margin-right: 2em }
104
105 div.footer, div.header {
106   clear: both;
107   font-size: smaller }
108
109 div.line-block {
110   display: block ;
111   margin-top: 1em ;
112   margin-bottom: 1em }
113
114 div.line-block div.line-block {
115   margin-top: 0 ;
116   margin-bottom: 0 ;
117   margin-left: 1.5em }
118
119 div.sidebar {
120   margin-left: 1em ;
121   border: medium outset ;
122   padding: 1em ;
123   background-color: #ffffee ;
124   width: 40% ;
125   float: right ;
126   clear: right }
127
128 div.sidebar p.rubric {
129   font-family: sans-serif ;
130   font-size: medium }
131
132 div.system-messages {
133   margin: 5em }
134
135 div.system-messages h1 {
136   color: red }
137
138 div.system-message {
139   border: medium outset ;
140   padding: 1em }
141
142 div.system-message p.system-message-title {
143   color: red ;
144   font-weight: bold }
145
146 div.topic {
147   margin: 2em }
148
149 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
150 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
151   margin-top: 0.4em }
152
153 h1.title {
154   text-align: center }
155
156 h2.subtitle {
157   text-align: center }
158
159 hr.docutils {
160   width: 75% }
161
162 img.align-left {
163   clear: left }
164
165 img.align-right {
166   clear: right }
167
168 ol.simple, ul.simple {
169   margin-bottom: 1em }
170
171 ol.arabic {
172   list-style: decimal }
173
174 ol.loweralpha {
175   list-style: lower-alpha }
176
177 ol.upperalpha {
178   list-style: upper-alpha }
179
180 ol.lowerroman {
181   list-style: lower-roman }
182
183 ol.upperroman {
184   list-style: upper-roman }
185
186 p.attribution {
187   text-align: right ;
188   margin-left: 50% }
189
190 p.caption {
191   font-style: italic }
192
193 p.credits {
194   font-style: italic ;
195   font-size: smaller }
196
197 p.label {
198   white-space: nowrap }
199
200 p.rubric {
201   font-weight: bold ;
202   font-size: larger ;
203   color: maroon ;
204   text-align: center }
205
206 p.sidebar-title {
207   font-family: sans-serif ;
208   font-weight: bold ;
209   font-size: larger }
210
211 p.sidebar-subtitle {
212   font-family: sans-serif ;
213   font-weight: bold }
214
215 p.topic-title {
216   font-weight: bold }
217
218 pre.address {
219   margin-bottom: 0 ;
220   margin-top: 0 ;
221   font-family: serif ;
222   font-size: 100% }
223
224 pre.literal-block, pre.doctest-block {
225   margin-left: 2em ;
226   margin-right: 2em }
227
228 span.classifier {
229   font-family: sans-serif ;
230   font-style: oblique }
231
232 span.classifier-delimiter {
233   font-family: sans-serif ;
234   font-weight: bold }
235
236 span.interpreted {
237   font-family: sans-serif }
238
239 span.option {
240   white-space: nowrap }
241
242 span.pre {
243   white-space: pre }
244
245 span.problematic {
246   color: red }
247
248 span.section-subtitle {
249   /* font-size relative to parent (h1..h6 element) */
250   font-size: 80% }
251
252 table.citation {
253   border-left: solid 1px gray;
254   margin-left: 1px }
255
256 table.docinfo {
257   margin: 2em 4em }
258
259 table.docutils {
260   margin-top: 0.5em ;
261   margin-bottom: 0.5em }
262
263 table.footnote {
264   border-left: solid 1px black;
265   margin-left: 1px }
266
267 table.docutils td, table.docutils th,
268 table.docinfo td, table.docinfo th {
269   padding-left: 0.5em ;
270   padding-right: 0.5em ;
271   vertical-align: top }
272
273 table.docutils th.field-name, table.docinfo th.docinfo-name {
274   font-weight: bold ;
275   text-align: left ;
276   white-space: nowrap ;
277   padding-left: 0 }
278
279 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
280 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
281   font-size: 100% }
282
283 ul.auto-toc {
284   list-style-type: none }
285
286 </style>
287 </head>
288 <body>
289 <div class="document" id="cairo-bindings-for-d">
290 <h1 class="title">cairo bindings for D</h1>
291
292 <!-- This document is written in reStructuredText. -->
293 <!-- Build command:
294 rst2html.py - -date - -time README.rst README.html -->
295 <div class="contents topic">
296 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
297 <ul class="simple">
298 <li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>
299 <li><a class="reference" href="#installation" id="id4" name="id4">Installation</a><ul>
300 <li><a class="reference" href="#cairo-binding" id="id5" name="id5">cairo binding</a></li>
301 <li><a class="reference" href="#cairooo-binding" id="id6" name="id6">cairooo binding</a></li>
302 <li><a class="reference" href="#cairo-snippets" id="id7" name="id7">cairo snippets</a></li>
303 <li><a class="reference" href="#cairooo-tutorial" id="id8" name="id8">cairooo tutorial</a></li>
304 <li><a class="reference" href="#demos" id="id9" name="id9">demos</a></li>
305 <li><a class="reference" href="#documentation" id="id10" name="id10">documentation</a></li>
306 <li><a class="reference" href="#cairo-for-windows" id="id11" name="id11">cairo for Windows</a></li>
307 </ul>
308 </li>
309 <li><a class="reference" href="#usage" id="id12" name="id12">Usage</a><ul>
310 <li><a class="reference" href="#cairo" id="id13" name="id13">cairo</a></li>
311 <li><a class="reference" href="#cairooo" id="id14" name="id14">cairooo</a></li>
312 </ul>
313 </li>
314 <li><a class="reference" href="#contributing" id="id15" name="id15">Contributing</a></li>
315 <li><a class="reference" href="#thanks" id="id16" name="id16">Thanks</a></li>
316 <li><a class="reference" href="#credits" id="id17" name="id17">Credits</a></li>
317 </ul>
318 </div>
319 <div class="section">
320 <h1><a class="toc-backref" href="#id3" id="introduction" name="introduction">Introduction</a></h1>
321 <p>This project's aim is to provide a complete, up-to-date D binding for the
322 <a class="reference" href="http://cairographics.org/">cairo</a> 2D drawing API.  Currently, the binding supports the base cairo
323 functions and PNG functions.  It also contains support for the Glitz, Win32
324 and Xlib backends, but these are largely untested.</p>
325 <p>This project also provides an object-oriented layer above the raw bindings
326 called <tt class="docutils literal"><span class="pre">cairooo</span></tt> which adds support for objects and exceptions, integrating
327 cairo more seamlessly with D style programming.  In time, we hope to also
328 provide a library of additional, high-level functionality with this layer.</p>
329 </div>
330 <div class="section">
331 <h1><a class="toc-backref" href="#id4" id="installation" name="installation">Installation</a></h1>
332 <div class="section">
333 <h2><a class="toc-backref" href="#id5" id="cairo-binding" name="cairo-binding">cairo binding</a></h2>
334 <p>To install, simply copy the <tt class="docutils literal"><span class="pre">cairo</span></tt> directory to a place in your D
335 compiler's import path.  That's all there is to it.</p>
336 <p>If you really want to have import libraries to use, then you can build these
337 using the <tt class="docutils literal"><span class="pre">cairo-build.d</span></tt> script, which will place them in the <tt class="docutils literal"><span class="pre">lib</span></tt>
338 directory.  It can be run using either:</p>
339 <pre class="literal-block">
340 dmd -run cairo-build.d ARGS
341 </pre>
342 <p>Or, if that fails:</p>
343 <pre class="literal-block">
344 build cairo-build.d
345 cairo-build ARGS
346 </pre>
347 <p>The command line arguments may be empty (signifying a default build), or
348 contain one or more targets to build.  You may also use the <tt class="docutils literal"><span class="pre">--verbose</span></tt>
349 switch to get more verbose output, and the <tt class="docutils literal"><span class="pre">--debug</span></tt> switch to produce
350 libraries with debug symbols <a class="footnote-reference" href="#debuglibs" id="id1" name="id1">[1]</a>.</p>
351 <p>Use the <tt class="docutils literal"><span class="pre">--help</span></tt> switch for full usage information.</p>
352 <p>Also, please note that if you are building static libraries that these
353 libraries only compile for one particular version of cairo at a time.  To
354 select which version of the cairo API you want to compile for, you need to use
355 the following additional arguments to the build script:</p>
356 <ul class="simple">
357 <li>cairo 1.0: no arguments needed.</li>
358 <li>cairo 1.2: <tt class="docutils literal"><span class="pre">+--version=cairo_1_2</span></tt></li>
359 <li>cairo 1.4: <tt class="docutils literal"><span class="pre">+--version=cairo_1_4</span></tt></li>
360 </ul>
361 <p>You will also need to specify the same version identifier when you compile
362 your programs.</p>
363 </div>
364 <div class="section">
365 <h2><a class="toc-backref" href="#id6" id="cairooo-binding" name="cairooo-binding">cairooo binding</a></h2>
366 <p>To install the cairooo binding, simply copy both the <tt class="docutils literal"><span class="pre">cairo</span></tt> and <tt class="docutils literal"><span class="pre">cairooo</span></tt>
367 directories to a place on your D compiler's import path.</p>
368 <p>If you want to build import libraries, then you can use the
369 <tt class="docutils literal"><span class="pre">cairooo-build.d</span></tt> script, which will build them to the <tt class="docutils literal"><span class="pre">lib</span></tt> directory.
370 Usage is mostly the same as using <tt class="docutils literal"><span class="pre">cairo-build.d</span></tt> (see above).</p>
371 <p>Note that cairooo currently does not support cairo 1.2 or 1.4.</p>
372 </div>
373 <div class="section">
374 <h2><a class="toc-backref" href="#id7" id="cairo-snippets" name="cairo-snippets">cairo snippets</a></h2>
375 <p>The <tt class="docutils literal"><span class="pre">cairo_snippets</span></tt> and <tt class="docutils literal"><span class="pre">cairooo_snippets</span></tt> directories contain the
376 &quot;snippets&quot; example programs provided by the cairo developers ported to D.
377 They use the <tt class="docutils literal"><span class="pre">cairo</span></tt> and <tt class="docutils literal"><span class="pre">cairooo</span></tt> bindings respectively.</p>
378 <p>These do not have a &quot;proper&quot; build script like the binding itself: they are
379 generally built with either a Windows batch file or shell script.  However, if
380 you wish to build them manually, the command to do so usually looks like
381 this:</p>
382 <pre class="literal-block">
383 build -cleanup -release -inline -I.. NAME_OF_SNIPPET
384 </pre>
385 <p>Just be sure to create the <tt class="docutils literal"><span class="pre">output</span></tt> directory if it does not exist first.</p>
386 </div>
387 <div class="section">
388 <h2><a class="toc-backref" href="#id8" id="cairooo-tutorial" name="cairooo-tutorial">cairooo tutorial</a></h2>
389 <p>The <tt class="docutils literal"><span class="pre">cairooo_tutorial</span></tt> contains the beginnings of a very simple introductory
390 tutorial to programming image programs in D using the cairooo binding.  It is
391 pathetically incomplete; however, it may be a useful starting point.</p>
392 </div>
393 <div class="section">
394 <h2><a class="toc-backref" href="#id9" id="demos" name="demos">demos</a></h2>
395 <p>The <tt class="docutils literal"><span class="pre">demos</span></tt> directory will contain a few small demo programs to showcase the
396 binding.  Currently, it only has one demo, so the plural is prehaps
397 misleading.  Hopefully this will change :)</p>
398 </div>
399 <div class="section">
400 <h2><a class="toc-backref" href="#id10" id="documentation" name="documentation">documentation</a></h2>
401 <p>Whilst this project hopes to eventually have full DDoc documentation for the
402 cairooo binding, we will not be providing anything other than minimal
403 documentation for the raw cairo API binding.  The rationale is that since the
404 original C api and the raw D api are for the most part identical, there is no
405 need to duplicate the existing C documentation.</p>
406 <p>That said, the cairooo documentation itself is woefully lacking.  What does
407 exist can be built using the following command:</p>
408 <pre class="literal-block">
409 build &#64;build_docs_cairooo.brf
410 </pre>
411 <p>Please note that you will need to create the following directory structure
412 <em>first</em> if it does not yet exist:</p>
413 <pre class="literal-block">
414 docs\
415   cairooo\
416     extra\
417     glitz\
418     png\
419     win32\
420     xlib\
421 </pre>
422 </div>
423 <div class="section">
424 <h2><a class="toc-backref" href="#id11" id="cairo-for-windows" name="cairo-for-windows">cairo for Windows</a></h2>
425 <p>If you are using Windows, you will also probably want to grab the cairo
426 library itself.  The best version I have found is on <a class="reference" href="http://www.iki.fi/tml/index.html">Tor Lillqvist</a>'s
427 <a class="reference" href="http://www.gimp.org/%7Etml/gimp/win32/downloads.html">GTK+ for Windows</a> website.</p>
428 <p>If you go to that page, you will need to download the following packages:</p>
429 <ul class="simple">
430 <li>cairo-1.x.y.zip</li>
431 <li>libpng 1.x.y binaries zip</li>
432 <li>Zlib 1.x.y</li>
433 </ul>
434 <p>Specifically, you're after <tt class="docutils literal"><span class="pre">libcairo-2.dll</span></tt>, <tt class="docutils literal"><span class="pre">libpng13.dll</span></tt> and
435 <tt class="docutils literal"><span class="pre">zlib1.dll</span></tt>.  Just place these files into either your system path
436 somewhere, or (a better idea) place them in the working directory of any
437 programs you're developing.</p>
438 </div>
439 </div>
440 <div class="section">
441 <h1><a class="toc-backref" href="#id12" id="usage" name="usage">Usage</a></h1>
442 <div class="section">
443 <h2><a class="toc-backref" href="#id13" id="cairo" name="cairo">cairo</a></h2>
444 <p>To use the binding, simply import <tt class="docutils literal"><span class="pre">cairo.cairo</span></tt>, along with any other
445 parts of the library you need.  For example, if you wanted the base cairo
446 functionality, along with the PNG functions, you would add the following to
447 your code:</p>
448 <pre class="literal-block">
449 import cairo.cairo;
450 import cairo.png.cairo_png;
451 </pre>
452 <p>Also, before using the cairo library, you need to tell it to load the actual
453 library proper.  You can do this like so:</p>
454 <pre class="literal-block">
455 cairo_load();
456 cairo_png_load();
457 </pre>
458 <p>If some part of the library fails to load, these functions will thrown an
459 exception which can be caught and dealt with.</p>
460 <p>To select a particular version of the cairo library, make sure you compile
461 with an appropriate version flag:</p>
462 <ul class="simple">
463 <li>cairo 1.0: no version flag necessary.</li>
464 <li>cairo 1.2: --version=cairo_1_2.</li>
465 <li>cairo 1.4: --version=cairo_1_4.</li>
466 </ul>
467 <p>From there, just start using the cairo API as you would from C.  The cairo
468 website contains a collection of <a class="reference" href="http://cairographics.org/samples/">example snippets</a> in C, and this binding
469 comes complete with the majority of these examples converted to D.  Just
470 look in the <tt class="docutils literal"><span class="pre">cairo_snippets</span></tt> directory.</p>
471 </div>
472 <div class="section">
473 <h2><a class="toc-backref" href="#id14" id="cairooo" name="cairooo">cairooo</a></h2>
474 <p>To use the cairooo binding instead, import <tt class="docutils literal"><span class="pre">cairooo.all</span></tt>, along with any
475 other parts of the library that you need.  To copy the above example, to
476 import the base and PNG functions:</p>
477 <pre class="literal-block">
478 import cairooo.all;
479 import cairooo.png.all;
480 </pre>
481 <p>As with the raw binding, you need to tell the binding to load the cairo
482 library before you can use it.  You can do that like so:</p>
483 <pre class="literal-block">
484 Cairo.load();
485 CairoPNG.load();
486 </pre>
487 <p>Again, if anything fails to load, an exception will be thrown.</p>
488 <p>There are no huge, arbitrary differences between the flat C api and the
489 object-oriented one.  The largest change is that anywhere you would pass a
490 handle, you instead pass an object.  The naming translation is roughly:</p>
491 <pre class="literal-block">
492 cairo_foo_bar_xxx_t* --&gt; FooBarXXX
493 </pre>
494 <p>An exception to this is the cairo context, <tt class="docutils literal"><span class="pre">cairo_t*</span></tt>, which becomes
495 <tt class="docutils literal"><span class="pre">Context</span></tt>.</p>
496 <p>Also, the following differences should be kept in mind:</p>
497 <ul class="simple">
498 <li>&quot;lower_case_with_underscores&quot; functions become &quot;lowerCaseWithUnderscores&quot;.</li>
499 <li>&quot;CAIRO_ENUM_TYPE_ENUM_NAME&quot; becomes &quot;EnumType.enumName&quot;.</li>
500 </ul>
501 <p>Finally, where there have been multiple ways of creating a certain kind of
502 object (such as a Surface or Pattern), creating them is split between using
503 constructors and static members.  This will get resolved eventually, but for
504 the moment, which one to use is unclear.</p>
505 <p>The general rule is that if you want to convert:</p>
506 <pre class="literal-block">
507 xxx = cairo_some_object_create_foo(arg1, arg2, ...);
508 </pre>
509 <p>You should try the following:</p>
510 <pre class="literal-block">
511 xxx = new SomeObject(arg1, arg2, ...);
512 xxx = SomeObject.create(arg1, arg2, ...);
513 xxx = SomeObject.createFoo(arg1, arg2, ...);
514 </pre>
515 <p>For more concrete examples, see the <tt class="docutils literal"><span class="pre">cairooo_snippets</span></tt>, <tt class="docutils literal"><span class="pre">cairooo_tutorial</span></tt>
516 and <tt class="docutils literal"><span class="pre">demos</span></tt> directories.</p>
517 </div>
518 </div>
519 <div class="section">
520 <h1><a class="toc-backref" href="#id15" id="contributing" name="contributing">Contributing</a></h1>
521 <p>The cairo api has a functionality in it that this binding does not
522 yet cover: PDF abd PS for example.  However, the only binary version of cairo
523 I have access to is limited to what is currently covered, and I have thus
524 far had no success in compiling cairo myself.</p>
525 <p>So, currently the best way to contribute is to contribute and maintain a
526 binding for some currently unsupported part of cairo.  You can look at the
527 PNG binding for a simple example.</p>
528 <p>That, or you can write samples and demos to test the bindings that I can't.
529 In addition to being fun, you get to make pretty pictures in the process!</p>
530 </div>
531 <div class="section">
532 <h1><a class="toc-backref" href="#id16" id="thanks" name="thanks">Thanks</a></h1>
533 <ul class="simple">
534 <li>Many thanks for the hard work by the people behind the cairo library.</li>
535 <li>Also, thanks to Michael Parker for letting me steal <a class="reference" href="http://www.dsource.org/projects/derelict/">Derelict</a>'s dynamic
536 loader code.</li>
537 </ul>
538 </div>
539 <div class="section">
540 <h1><a class="toc-backref" href="#id17" id="credits" name="credits">Credits</a></h1>
541 <p>cairo bindings for D Copyright © 2006 Daniel Keep.  Portions Copyright ©
542 2006 Michael Parker.</p>
543 <p>Released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD license</a>.</p>
544 <!-- Links -->
545 <!-- Footnotes -->
546 <table class="docutils footnote" frame="void" id="debuglibs" rules="none">
547 <colgroup><col class="label" /><col /></colgroup>
548 <tbody valign="top">
549 <tr><td class="label"><a class="fn-backref" href="#id1" name="debuglibs">[1]</a></td><td>The debug libraries will have &quot;_debug&quot; appended to their
550 filename, so you do not need to worry about overwriting your
551 release libraries.</td></tr>
552 </tbody>
553 </table>
554 </div>
555 </div>
556 <div class="footer">
557 <hr class="footer" />
558 Generated on: 2007-11-04 02:51 UTC.
559
560 </div>
561 </body>
562 </html>
Note: See TracBrowser for help on using the browser.