|
jpayne@68
|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
jpayne@68
|
2 <html>
|
|
jpayne@68
|
3 <head>
|
|
jpayne@68
|
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
jpayne@68
|
5 <title>Surfaces: Cairo: A Vector Graphics Library</title>
|
|
jpayne@68
|
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
|
jpayne@68
|
7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
|
|
jpayne@68
|
8 <link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
|
|
jpayne@68
|
9 <link rel="prev" href="bindings-patterns.html" title="Patterns">
|
|
jpayne@68
|
10 <link rel="next" href="bindings-fonts.html" title="Fonts">
|
|
jpayne@68
|
11 <meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
jpayne@68
|
12 <link rel="stylesheet" href="style.css" type="text/css">
|
|
jpayne@68
|
13 </head>
|
|
jpayne@68
|
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
jpayne@68
|
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
|
|
jpayne@68
|
16 <td width="100%" align="left" class="shortcuts"></td>
|
|
jpayne@68
|
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
|
|
jpayne@68
|
18 <td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
|
|
jpayne@68
|
19 <td><a accesskey="p" href="bindings-patterns.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
|
|
jpayne@68
|
20 <td><a accesskey="n" href="bindings-fonts.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
|
|
jpayne@68
|
21 </tr></table>
|
|
jpayne@68
|
22 <div class="sect1">
|
|
jpayne@68
|
23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
|
jpayne@68
|
24 <a name="bindings-surfaces"></a>Surfaces</h2></div></div></div>
|
|
jpayne@68
|
25 <p>
|
|
jpayne@68
|
26 Like patterns, surfaces, which use only the
|
|
jpayne@68
|
27 <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
|
|
jpayne@68
|
28 type in the C API should be broken up into a hierarchy of types
|
|
jpayne@68
|
29 in a language binding.
|
|
jpayne@68
|
30 </p>
|
|
jpayne@68
|
31 <pre class="programlisting">
|
|
jpayne@68
|
32 cairo_surface_t
|
|
jpayne@68
|
33 cairo_image_surface_t
|
|
jpayne@68
|
34 cairo_atsui_surface_t
|
|
jpayne@68
|
35 cairo_win32_surface_t
|
|
jpayne@68
|
36 cairo_xlib_surface_t
|
|
jpayne@68
|
37 cairo_beos_surface_t
|
|
jpayne@68
|
38 </pre>
|
|
jpayne@68
|
39 <p>
|
|
jpayne@68
|
40 Unlike patterns, the constructors and methods on these types are
|
|
jpayne@68
|
41 clearly named, and can be trivially associated with the
|
|
jpayne@68
|
42 appropriate subtype. Many language bindings will want to avoid
|
|
jpayne@68
|
43 binding the platform-specific subtypes at all, since the
|
|
jpayne@68
|
44 methods on these types are not useful without passing in native
|
|
jpayne@68
|
45 C types. Unless there is a language binding for Xlib available,
|
|
jpayne@68
|
46 there is no way to represent a XLib <span class="type">Display</span> * in
|
|
jpayne@68
|
47 that language.
|
|
jpayne@68
|
48 </p>
|
|
jpayne@68
|
49 <p>
|
|
jpayne@68
|
50 This doesn't mean that platform-specific surface types can't
|
|
jpayne@68
|
51 be used in a language binding that doesn't bind the constructor.
|
|
jpayne@68
|
52 A very common situation is to use a cairo language binding in
|
|
jpayne@68
|
53 combination with a binding for a higher level system like
|
|
jpayne@68
|
54 the <a class="ulink" href="http://www.gtk.org/" target="_top">GTK+</a> widget
|
|
jpayne@68
|
55 toolkit. In such a situation, the higher level toolkit provides
|
|
jpayne@68
|
56 ways to get references to platform specific surfaces.
|
|
jpayne@68
|
57 </p>
|
|
jpayne@68
|
58 <p>
|
|
jpayne@68
|
59 The <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-set-user-data" title="cairo_surface_set_user_data ()"><code class="function">cairo_surface_set_user_data()</code></a>,
|
|
jpayne@68
|
60 and <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-get-user-data" title="cairo_surface_get_user_data ()"><code class="function">cairo_surface_get_user_data()</code></a>
|
|
jpayne@68
|
61 methods are provided for use in language bindings, and should
|
|
jpayne@68
|
62 not be directly exposed to applications. One example of the use
|
|
jpayne@68
|
63 of these functions in a language binding is creating a binding for:
|
|
jpayne@68
|
64 </p>
|
|
jpayne@68
|
65 <pre class="programlisting">
|
|
jpayne@68
|
66 cairo_surface_t *
|
|
jpayne@68
|
67 <a class="link" href="cairo-Image-Surfaces.html#cairo-image-surface-create-for-data" title="cairo_image_surface_create_for_data ()"><code class="function">cairo_image_surface_create_for_data</code></a> (unsigned char *data,
|
|
jpayne@68
|
68 cairo_format_t format,
|
|
jpayne@68
|
69 int width,
|
|
jpayne@68
|
70 int height,
|
|
jpayne@68
|
71 int stride);
|
|
jpayne@68
|
72 </pre>
|
|
jpayne@68
|
73 <p>
|
|
jpayne@68
|
74 The memory block passed in for <em class="parameter"><code>data</code></em> must be
|
|
jpayne@68
|
75 kept around until the surface is destroyed, so the language
|
|
jpayne@68
|
76 binding must have some way of determining when that happens. The
|
|
jpayne@68
|
77 way to do this is to use the <em class="parameter"><code>destroy</code></em>
|
|
jpayne@68
|
78 argument to <code class="function">cairo_surface_set_user_data()</code>.
|
|
jpayne@68
|
79 </p>
|
|
jpayne@68
|
80 <p class="remark"><em><span class="remark">
|
|
jpayne@68
|
81 Some languages may not have a suitable “pointer to a block of
|
|
jpayne@68
|
82 data” type to pass in for <em class="parameter"><code>data</code></em>. And even
|
|
jpayne@68
|
83 where a language does have such a type, the user will be
|
|
jpayne@68
|
84 frequently able to cause the backing store to be reallocated
|
|
jpayne@68
|
85 to a different location or truncated. Should we recommend a
|
|
jpayne@68
|
86 standard type name and binding for a buffer object here?
|
|
jpayne@68
|
87 </span></em></p>
|
|
jpayne@68
|
88 </div>
|
|
jpayne@68
|
89 <div class="footer">
|
|
jpayne@68
|
90 <hr>Generated by GTK-Doc V1.27</div>
|
|
jpayne@68
|
91 </body>
|
|
jpayne@68
|
92 </html> |
