Imported Upstream version 0.5.1

1 files changed, 83 insertions, 40 deletions

diff --git a/doc/public/xml/cairo-xlib.xml b/doc/public/xml/cairo-xlib.xml
index dbb59a6..5ab5b4a 100644
--- a/doc/public/xml/cairo-xlib.xml
+++ b/doc/public/xml/cairo-xlib.xml
@@ -18,14 +18,19 @@
 
 
 
-<link linkend="void">void</link>        <link linkend="cairo-set-target-drawable">cairo_set_target_drawable</link>       (<link linkend="cairo-t">cairo_t</link> *cr,
-                                             <link linkend="Display">Display</link> *dpy,
-                                             <link linkend="Drawable">Drawable</link> drawable);
 <link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-xlib-surface-create">cairo_xlib_surface_create</link>  (<link linkend="Display">Display</link> *dpy,
                                              <link linkend="Drawable">Drawable</link> drawable,
                                              <link linkend="Visual">Visual</link> *visual,
-                                             <link linkend="cairo-format-t">cairo_format_t</link> format,
-                                             <link linkend="Colormap">Colormap</link> colormap);
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);
+<link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-xlib-surface-create-for-bitmap">cairo_xlib_surface_create_for_bitmap</link>
+                                            (<link linkend="Display">Display</link> *dpy,
+                                             <link linkend="Pixmap">Pixmap</link> bitmap,
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);
+<link linkend="void">void</link>        <link linkend="cairo-xlib-surface-set-size">cairo_xlib_surface_set_size</link>     (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);
 </synopsis>
 </refsynopsisdiv>
 
@@ -47,61 +52,99 @@
 <refsect1>
 <title>Details</title>
 <refsect2>
-<title><anchor id="cairo-set-target-drawable"/>cairo_set_target_drawable ()</title>
-<indexterm><primary>cairo_set_target_drawable</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_set_target_drawable       (<link linkend="cairo-t">cairo_t</link> *cr,
-                                             <link linkend="Display">Display</link> *dpy,
-                                             <link linkend="Drawable">Drawable</link> drawable);</programlisting>
+<title><anchor id="cairo-xlib-surface-create"/>cairo_xlib_surface_create ()</title>
+<indexterm><primary>cairo_xlib_surface_create</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_xlib_surface_create  (<link linkend="Display">Display</link> *dpy,
+                                             <link linkend="Drawable">Drawable</link> drawable,
+                                             <link linkend="Visual">Visual</link> *visual,
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);</programlisting>
 <para>
-Directs output for a <link linkend="cairo-t"><type>cairo_t</type></link> to an Xlib drawable.  <parameter>drawable</parameter> must
-be a Window or Pixmap on the default screen of <parameter>dpy</parameter> using the
-default colormap and visual.  Using this function is slow because
-the function must retrieve information about <parameter>drawable</parameter> from the X
-server.
- 
-The combination of <link linkend="cairo-xlib-surface-create"><function>cairo_xlib_surface_create()</function></link> and
-<link linkend="cairo-set-target-surface"><function>cairo_set_target_surface()</function></link> is somewhat more flexible, although
-it still is slow.</para>
+Creates an Xlib surface that draws to the given drawable.
+The way that colors are represented in the drawable is specified
+by the provided visual.
+</para>
+<para>
+NOTE: If <parameter>drawable</parameter> is a Window, then the function
+cairo_xlib_surface_set_size must be called whenever the size of the
+window changes.</para>
 <para>
 
 </para><variablelist role="params">
-<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
-<listitem><simpara> a <link linkend="cairo-t"><type>cairo_t</type></link>
-</simpara></listitem></varlistentry>
 <varlistentry><term><parameter>dpy</parameter>&nbsp;:</term>
-<listitem><simpara> an X display
+<listitem><simpara> an X Display
 </simpara></listitem></varlistentry>
 <varlistentry><term><parameter>drawable</parameter>&nbsp;:</term>
-<listitem><simpara> a window or pixmap on the default screen of <parameter>dpy</parameter>
+<listitem><simpara> an X Drawable, (a Pixmap or a Window)
+</simpara></listitem></varlistentry>
+<varlistentry><term><parameter>visual</parameter>&nbsp;:</term>
+<listitem><simpara> the visual to use for drawing to <parameter>drawable</parameter>. The depth
+         of the visual must match the depth of the drawable.
+         Currently, only TrueColor visuals are fully supported.
+</simpara></listitem></varlistentry>
+<varlistentry><term><parameter>width</parameter>&nbsp;:</term>
+<listitem><simpara> the current width of <parameter>drawable</parameter>.
+</simpara></listitem></varlistentry>
+<varlistentry><term><parameter>height</parameter>&nbsp;:</term>
+<listitem><simpara> the current height of <parameter>drawable</parameter>.
+</simpara></listitem></varlistentry>
+<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the newly created surface
 </simpara></listitem></varlistentry>
 </variablelist></refsect2>
 <refsect2>
-<title><anchor id="cairo-xlib-surface-create"/>cairo_xlib_surface_create ()</title>
-<indexterm><primary>cairo_xlib_surface_create</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_xlib_surface_create  (<link linkend="Display">Display</link> *dpy,
-                                             <link linkend="Drawable">Drawable</link> drawable,
-                                             <link linkend="Visual">Visual</link> *visual,
-                                             <link linkend="cairo-format-t">cairo_format_t</link> format,
-                                             <link linkend="Colormap">Colormap</link> colormap);</programlisting>
+<title><anchor id="cairo-xlib-surface-create-for-bitmap"/>cairo_xlib_surface_create_for_bitmap ()</title>
+<indexterm><primary>cairo_xlib_surface_create_for_bitmap</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_xlib_surface_create_for_bitmap
+                                            (<link linkend="Display">Display</link> *dpy,
+                                             <link linkend="Pixmap">Pixmap</link> bitmap,
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);</programlisting>
+<para>
+Creates an Xlib surface that draws to the given bitmap.
+This will be drawn to as a CAIRO_FORMAT_A1 object.</para>
 <para>
 
 </para><variablelist role="params">
 <varlistentry><term><parameter>dpy</parameter>&nbsp;:</term>
-<listitem><simpara>
+<listitem><simpara> an X Display
 </simpara></listitem></varlistentry>
-<varlistentry><term><parameter>drawable</parameter>&nbsp;:</term>
-<listitem><simpara>
+<varlistentry><term><parameter>bitmap</parameter>&nbsp;:</term>
+<listitem><simpara> an X Drawable, (a depth-1 Pixmap)
 </simpara></listitem></varlistentry>
-<varlistentry><term><parameter>visual</parameter>&nbsp;:</term>
-<listitem><simpara>
+<varlistentry><term><parameter>width</parameter>&nbsp;:</term>
+<listitem><simpara> the current width of <parameter>bitmap</parameter>.
 </simpara></listitem></varlistentry>
-<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
-<listitem><simpara>
+<varlistentry><term><parameter>height</parameter>&nbsp;:</term>
+<listitem><simpara> the current height of <parameter>bitmap</parameter>.
 </simpara></listitem></varlistentry>
-<varlistentry><term><parameter>colormap</parameter>&nbsp;:</term>
-<listitem><simpara>
+<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the newly created surface
 </simpara></listitem></varlistentry>
-<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
-
+</variablelist></refsect2>
+<refsect2>
+<title><anchor id="cairo-xlib-surface-set-size"/>cairo_xlib_surface_set_size ()</title>
+<indexterm><primary>cairo_xlib_surface_set_size</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_xlib_surface_set_size     (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
+                                             <link linkend="int">int</link> width,
+                                             <link linkend="int">int</link> height);</programlisting>
+<para>
+Informs cairo of the new size of the X Drawable underlying the
+surface. For a surface created for a Window (rather than a Pixmap),
+this function must be called each time the size of the window
+changes. (For a subwindow, you are normally resizing the window
+yourself, but for a toplevel window, it is necessary to listen for
+ConfigureNotify events.)
+</para>
+<para>
+A Pixmap can never change size, so it is never necessary to call
+this function on a surface created for a Pixmap.</para>
+<para>
 
+</para><variablelist role="params">
+<varlistentry><term><parameter>surface</parameter>&nbsp;:</term>
+<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> for the XLib backend
+</simpara></listitem></varlistentry>
+<varlistentry><term><parameter>width</parameter>&nbsp;:</term>
+<listitem><simpara> the new width of the surface
+</simpara></listitem></varlistentry>
+<varlistentry><term><parameter>height</parameter>&nbsp;:</term>
+<listitem><simpara> the new height of the surface
 </simpara></listitem></varlistentry>
 </variablelist></refsect2>