RubyGems - cairo - Versions diffs - 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32 - Mend

cairo 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32

Potentially problematic release.

This version of cairo might be problematic. Click here for more details.

Files changed (126) hide show

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-path.html ADDED Viewed

@@ -0,0 +1,127 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>cairo_path_t</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="prev" href="bindings-fonts.html" title="Fonts">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-fonts.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td> </td>
+</tr></table>
+<div class="sect1" title="cairo_path_t">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-path"></a>cairo_path_t</h2></div></div></div>
+<p>
+      The <a class="link" href="cairo-paths.html#cairo-path-t" title="cairo_path_t"><span class="type">cairo_path_t</span></a> type is one
+      area in which most language bindings will differ significantly
+      from the C API. The C API for <span class="type">cairo_path_t</span> is
+      designed for efficiency and to avoid auxiliary objects that
+      would be have to be manually memory managed by the
+      application. However,
+      a language binding should not present <span class="type">cairo_path_t</span> as an
+      array, but rather as an opaque that can be iterated
+      over. Different languages have quite different conventions for
+      how iterators work, so it is impossible to give an exact
+      specification for how this API should work, but the type names
+      and methods should be similar to the language's mapping of the following:
+    </p>
+<pre class="programlisting">
+typedef struct cairo_path_iterator cairo_path_iterator_t;
+typedef struct cairo_path_element cairo_path_element_t;
+cairo_path_iterator_t *
+cairo_path_get_iterator (cairo_path_t *path);
+cairo_bool_t
+cairo_path_iterator_has_next (cairo_path_iterator_t *iterator);
+cairo_path_element_t *
+cairo_path_iterator_next (cairo_path_iterator_t *iterator);
+cairo_path_element_type_t
+cairo_path_element_get_type (cairo_path_element_t *element);
+void
+cairo_path_element_get_point (cairo_path_element_t *element,
+                              int                   index,
+                              double                *x,
+                              double                *y);
+    </pre>
+<p>
+      The above is written using the Java conventions for
+      iterators. To illustrate how the API for PathIterator might
+      depend on the native iteration conventions of the API, examine
+      three versions of the loop, first written in a hypothetical Java
+      binding:
+    </p>
+<pre class="programlisting">
+PathIterator iter = cr.copyPath().iterator();
+while (cr.hasNext()) {
+    PathElement element = iter.next();
+    if (element.getType() == PathElementType.MOVE_TO) {
+        Point p = element.getPoint(0);
+        doMoveTo (p.x, p.y);
+    }
+}</pre>
+<p>
+      And then in a hypothetical C++ binding:
+    </p>
+<pre class="programlisting">
+Path path = cr.copyPath();
+for (PathIterator iter = path.begin(); iter != path.end(); iter++) {
+    PathElement element = *iter;
+    if (element.getType() == PathElementType.MOVE_TO) {
+        Point p = element.getPoint(0);
+        doMoveTo (p.x, p.y);
+    }
+}</pre>
+<p>
+      And then finally in a Python binding:
+    </p>
+<pre class="programlisting">
+for element in cr.copy_path():
+    if element.getType == cairo.PATH_ELEMENT_MOVE_TO:
+        (x, y) = element.getPoint(0)
+        doMoveTo (x, y);</pre>
+<p>
+      While many of the API elements stay the same in the three
+      examples, the exact iteration mechanism is quite different, to
+      match how users of the language would expect to iterate over
+      a container.
+    </p>
+<p>
+      You should not present an API for mutating or for creating new
+      <span class="type">cairo_path_t</span> objects. In the future, these
+      guidelines may be extended to present an API for creating a
+      <span class="type">cairo_path_t</span> from scratch for use with
+      <a class="link" href="cairo-paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_append_path()</code></a>
+      but the current expectation is that <code class="function">cairo_append_path()</code> will
+      mostly be used with paths from
+      <a class="link" href="cairo-paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_copy_path()</code></a>.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-patterns.html ADDED Viewed

@@ -0,0 +1,67 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Patterns</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="prev" href="bindings-errors.html" title="Error handling">
+<link rel="next" href="bindings-surfaces.html" title="Surfaces">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-errors.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-surfaces.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Patterns">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-patterns"></a>Patterns</h2></div></div></div>
+<p>
+      The cairo C API allows for creating a number of different types
+      of patterns. All of these different types of patterns map to
+      <a class="link" href="cairo-pattern.html#cairo-pattern-t" title="cairo_pattern_t"><span class="type">cairo_pattern_t</span></a>
+      in C, but in an object oriented language, there should instead
+      be a hierarchy of types. (The functions that should map to
+      constructors for the various types are listed after the type,
+      methods on that type are listed below)
+    </p>
+<pre class="programlisting">
+cairo_pattern_t
+      <a class="link" href="cairo-pattern.html#cairo-pattern-set-matrix" title="cairo_pattern_set_matrix ()"><code class="function">cairo_pattern_set_matrix()</code></a>
+      <a class="link" href="cairo-pattern.html#cairo-pattern-get-matrix" title="cairo_pattern_get_matrix ()"><code class="function">cairo_pattern_get_matrix()</code></a>
+   cairo_solid_pattern_t (<a class="link" href="cairo-pattern.html#cairo-pattern-create-rgb" title="cairo_pattern_create_rgb ()"><code class="function">cairo_pattern_create_rgb()</code></a> and <a class="link" href="cairo-pattern.html#cairo-pattern-create-rgba" title="cairo_pattern_create_rgba ()"><code class="function">cairo_pattern_create_rgba()</code></a>)
+   cairo_surface_pattern_t (<a class="link" href="cairo-pattern.html#cairo-pattern-create-for-surface" title="cairo_pattern_create_for_surface ()"><code class="function">cairo_pattern_create_for_surface()</code></a>)
+         <a class="link" href="cairo-pattern.html#cairo-pattern-set-extend" title="cairo_pattern_set_extend ()"><code class="function">cairo_pattern_set_extend()</code></a>
+         <a class="link" href="cairo-pattern.html#cairo-pattern-get-extend" title="cairo_pattern_get_extend ()"><code class="function">cairo_pattern_get_extend()</code></a>
+         <a class="link" href="cairo-pattern.html#cairo-pattern-set-filter" title="cairo_pattern_set_filter ()"><code class="function">cairo_pattern_set_filter()</code></a>
+         <a class="link" href="cairo-pattern.html#cairo-pattern-get-filter" title="cairo_pattern_get_filter ()"><code class="function">cairo_pattern_get_filter()</code></a>
+   cairo_gradient_t
+         <a class="link" href="cairo-pattern.html#cairo-pattern-add-color-stop-rgb" title="cairo_pattern_add_color_stop_rgb ()"><code class="function">cairo_pattern_add_color_stop_rgb()</code></a>
+         <a class="link" href="cairo-pattern.html#cairo-pattern-add-color-stop-rgba" title="cairo_pattern_add_color_stop_rgba ()"><code class="function">cairo_pattern_add_color_stop_rgba()</code></a>
+      cairo_linear_gradient_t (<a class="link" href="cairo-pattern.html#cairo-pattern-create-linear" title="cairo_pattern_create_linear ()"><code class="function">cairo_pattern_create_linear()</code></a>)
+      cairo_radial_gradient_t (<a class="link" href="cairo-pattern.html#cairo-pattern-create-radial" title="cairo_pattern_create_radial ()"><code class="function">cairo_pattern_create_radial()</code></a>)
+    </pre>
+<p>
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-return-values.html ADDED Viewed

@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Multiple return values</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="prev" href="bindings-memory.html" title="Memory management">
+<link rel="next" href="bindings-overloading.html" title="Overloading and optional arguments">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-memory.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-overloading.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Multiple return values">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-return-values"></a>Multiple return values</h2></div></div></div>
+<p>
+      There are a number of functions in the cairo API that have
+      multiple <em class="firstterm">out parameters</em> or
+      <em class="firstterm">in-out parameters</em>. In some languages
+      these can be translated into multiple return values. In Python,
+      what is:
+    </p>
+<pre class="programlisting">
+cairo_user_to_device (cr, &amp;x, &amp;y);</pre>
+<p>
+      can by mapped to:
+    </p>
+<pre class="programlisting">
+(x, y) = cr.user_to_device (cr, x, y);</pre>
+<p>
+      but many languages don't have provisions for multiple return
+      values, so it is necessary to introduce auxiliary types.
+      Most of the functions that require the auxiliary types
+      require a type that would, in C, look like
+    </p>
+<pre class="programlisting">
+typedef struct _cairo_point cairo_point_t;
+struct _cairo_point {
+    double x;
+    double y;
+}</pre>
+<p>
+      The same type should be used both for functions that use a pair
+      of coordinates as an absolute position, and functions that use
+      a pair of coordinates as a displacement. While an argument could
+      be made that having a separate “distance” type is more correct,
+      it is more likely just to confuse users.
+    </p>
+<pre class="programlisting">
+void
+cairo_user_to_device (cairo_t *cr, double *x, double *y);
+void
+cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
+void
+cairo_device_to_user (cairo_t *cr, double *x, double *y);
+void
+cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
+void
+cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy);
+void
+cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y);
+void
+cairo_get_current_point (cairo_t *cr, double *x, double *y);
+    </pre>
+<p>
+      There are also a couple of functions that return four values
+      representing a rectangle. These should be mapped to a
+      “rectangle” type that looks like:
+    </p>
+<pre class="programlisting">
+typedef struct _cairo_rectangle cairo_rectangle_t;
+struct _cairo_rectangle {
+    double x;
+    double y;
+    double width;
+    double height;
+}</pre>
+<p>
+      The C function returns the rectangle as a set of two points to
+      facilitate rounding to integral extents, but this isn't worth
+      adding a “box” type to go along with the more obvious
+      “rectangle” representation.
+    </p>
+<p class="remark"><i><span class="remark">
+      Q: Would it make sense here to define a standard
+      <code class="function">cairo_rectangle_round()</code> method
+      that language bindings should map?
+    </span></i></p>
+<pre class="programlisting">
+void
+cairo_stroke_extents (cairo_t *cr,
+		      double *x1, double *y1,
+		      double *x2, double *y2);
+void
+cairo_fill_extents (cairo_t *cr,
+		    double *x1, double *y1,
+		    double *x2, double *y2);
+    </pre>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-streams.html ADDED Viewed

@@ -0,0 +1,102 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Streams and File I/O</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="prev" href="bindings-overloading.html" title="Overloading and optional arguments">
+<link rel="next" href="bindings-errors.html" title="Error handling">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-overloading.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-errors.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Streams and File I/O">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-streams"></a>Streams and File I/O</h2></div></div></div>
+<p>
+      Various places in the cairo API deal with reading and writing
+      data, whether from and to files, or to other sources and
+      destinations. In these cases, what is typically provided in the
+      C API is a simple version that just takes a filename, and a
+      complex version that takes a callback function.
+      An example is the PNG handling functions:
+    </p>
+<pre class="programlisting">
+cairo_surface_t *
+cairo_image_surface_create_from_png (const char	*filename);
+cairo_surface_t *
+cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
+					    void             *closure);
+cairo_status_t
+cairo_surface_write_to_png (cairo_surface_t	*surface,
+			    const char		*filename);
+cairo_status_t
+cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
+				   cairo_write_func_t	write_func,
+				   void			*closure);</pre>
+<p>
+      The expectation is that the filename version will be mapped
+      literally in the language binding, but the callback version
+      will be mapped to a version that takes a language stream
+      object. For example, in Java, the four functions above
+      might be mapped to:
+    </p>
+<pre class="programlisting">
+static public ImageSurface createFromPNG (String filename) throws IOException;
+static public ImageSurface createFromPNG (InputStream stream) throws IOException;
+public void writeToPNG (String filename) throws IOException;
+public void writeToPNG (OutputStream stream) throws IOException;
+</pre>
+<p>
+      In many cases, it will be better to
+      implement the filename version internally
+      using the stream version, rather than building it on top of the
+      filename version in C. The reason for this is that will
+      naturally give a more standard handling of file errors for
+      the language, as seen in the above Java example, where
+      <code class="methodname">createFromPNG()</code> is marked as raising
+      an exception. Propagating exceptions from inside the callback
+      function to the caller will pose a challenge to the language
+      binding implementor, since an exception must not propagate
+      through the Cairo code. A technique that will be useful in
+      some cases is to catch the exception in the callback,
+      store the exception object inside a structure pointed to by
+      <em class="parameter"><code>closure</code></em>, and then rethrow it once
+      the function returns.
+    </p>
+<p class="remark"><i><span class="remark">
+      I'm not sure how to handle this for
+      <code class="function">cairo_pdf_surface_create_for_callback()</code>.
+      Other than keep a “exception to rethrow” thread-specific
+      variable
+      that is checked after <span class="emphasis"><em>every</em></span> call to a Cairo
+      function.
+    </span></i></p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-surfaces.html ADDED Viewed

@@ -0,0 +1,103 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Surfaces</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
+<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="prev" href="bindings-patterns.html" title="Patterns">
+<link rel="next" href="bindings-fonts.html" title="Fonts">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-patterns.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-fonts.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Surfaces">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-surfaces"></a>Surfaces</h2></div></div></div>
+<p>
+      Like patterns, surfaces, which use only the
+      <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+      type in the C API should be broken up into a hierarchy of types
+      in a language binding.
+    </p>
+<pre class="programlisting">
+cairo_surface_t
+    cairo_image_surface_t
+    cairo_atsui_surface_t
+    cairo_win32_surface_t
+    cairo_xlib_surface_t
+    cairo_beos_surface_t
+    </pre>
+<p>
+      Unlike patterns, the constructors and methods on these types are
+      clearly named, and can be trivially associated with the
+      appropriate subtype. Many language bindings will want to avoid
+      binding the platform-specific subtypes at all, since the
+      methods on these types are not useful without passing in native
+      C types. Unless there is a language binding for Xlib available,
+      there is no way to represent a XLib <span class="type">Display</span> * in
+      that language.
+    </p>
+<p>
+      This doesn't mean that platform-specific surface types can't
+      be used in a language binding that doesn't bind the constructor.
+      A very common situation is to use a cairo language binding in
+      combination with a binding for a higher level system like
+      the <a class="ulink" href="http://www.gtk.org/" target="_top">GTK+</a> widget
+      toolkit. In such a situation, the higher level toolkit provides
+      ways to get references to platform specific surfaces.
+    </p>
+<p>
+      The <a class="link" href="cairo-surface.html#cairo-surface-set-user-data" title="cairo_surface_set_user_data ()"><code class="function">cairo_surface_set_user_data()</code></a>,
+      and <a class="link" href="cairo-surface.html#cairo-surface-get-user-data" title="cairo_surface_get_user_data ()"><code class="function">cairo_surface_get_user_data()</code></a>
+      methods are provided for use in language bindings, and should
+      not be directly exposed to applications. One example of the use
+      of these functions in a language binding is creating a binding for:
+    </p>
+<pre class="programlisting">
+cairo_surface_t *
+<a class="link" href="cairo-image-surface.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,
+				     cairo_format_t		format,
+				     int			width,
+				     int			height,
+				     int			stride);
+</pre>
+<p>
+      The memory block passed in for <em class="parameter"><code>data</code></em> must be
+      kept around until the surface is destroyed, so the language
+      binding must have some way of determining when that happens. The
+      way to do this is to use the <em class="parameter"><code>destroy</code></em>
+      argument to <code class="function">cairo_surface_set_user_data()</code>.
+    </p>
+<p class="remark"><i><span class="remark">
+      Some languages may not have a suitable “pointer to a block of
+      data” type to pass in for <em class="parameter"><code>data</code></em>. And even
+      where a language does have such a type, the user will be
+      frequently able to cause the backing store to be reallocated
+      to a different location or truncated. Should we recommend a
+      standard type name and binding for a buffer object here?
+    </span></i></p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>