cairo-cairo-device-t.html [plain text]
<!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_device_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="cairo-surfaces.html" title="Surfaces">
<link rel="prev" href="cairo-surfaces.html" title="Surfaces">
<link rel="next" href="cairo-cairo-surface-t.html" title="cairo_surface_t">
<meta name="generator" content="GTK-Doc V1.15 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</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="cairo-surfaces.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="cairo-surfaces.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="cairo-cairo-surface-t.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#cairo-cairo-device-t.synopsis" class="shortcut">Top</a>
|
<a href="#cairo-cairo-device-t.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry" title="cairo_device_t">
<a name="cairo-cairo-device-t"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="cairo-cairo-device-t.top_of_page"></a>cairo_device_t</span></h2>
<p>cairo_device_t — interface to underlying rendering system</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv" title="Synopsis">
<a name="cairo-cairo-device-t.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">typedef <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t">cairo_device_t</a>;
<a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="returnvalue">cairo_device_t</span></a> * <a class="link" href="cairo-cairo-device-t.html#cairo-device-reference" title="cairo_device_reference ()">cairo_device_reference</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-cairo-device-t.html#cairo-device-destroy" title="cairo_device_destroy ()">cairo_device_destroy</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> <a class="link" href="cairo-cairo-device-t.html#cairo-device-status" title="cairo_device_status ()">cairo_device_status</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-cairo-device-t.html#cairo-device-finish" title="cairo_device_finish ()">cairo_device_finish</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-cairo-device-t.html#cairo-device-flush" title="cairo_device_flush ()">cairo_device_flush</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
enum <a class="link" href="cairo-cairo-device-t.html#cairo-device-type-t" title="enum cairo_device_type_t">cairo_device_type_t</a>;
<a class="link" href="cairo-cairo-device-t.html#cairo-device-type-t" title="enum cairo_device_type_t"><span class="returnvalue">cairo_device_type_t</span></a> <a class="link" href="cairo-cairo-device-t.html#cairo-device-get-type" title="cairo_device_get_type ()">cairo_device_get_type</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
unsigned <span class="returnvalue">int</span> <a class="link" href="cairo-cairo-device-t.html#cairo-device-get-reference-count" title="cairo_device_get_reference_count ()">cairo_device_get_reference_count</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> <a class="link" href="cairo-cairo-device-t.html#cairo-device-set-user-data" title="cairo_device_set_user_data ()">cairo_device_set_user_data</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> *key</code></em>,
<em class="parameter"><code><span class="type">void</span> *user_data</code></em>,
<em class="parameter"><code><a class="link" href="cairo-Types.html#cairo-destroy-func-t" title="cairo_destroy_func_t ()"><span class="type">cairo_destroy_func_t</span></a> destroy</code></em>);
<span class="returnvalue">void</span> * <a class="link" href="cairo-cairo-device-t.html#cairo-device-get-user-data" title="cairo_device_get_user_data ()">cairo_device_get_user_data</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> *key</code></em>);
<a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> <a class="link" href="cairo-cairo-device-t.html#cairo-device-acquire" title="cairo_device_acquire ()">cairo_device_acquire</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-cairo-device-t.html#cairo-device-release" title="cairo_device_release ()">cairo_device_release</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);
</pre>
</div>
<div class="refsect1" title="Description">
<a name="cairo-cairo-device-t.description"></a><h2>Description</h2>
<p>
Devices are the abstraction Cairo employs for the rendering system
used by a <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>. You can get the device of a surface using
<a class="link" href="cairo-cairo-surface-t.html#cairo-surface-get-device" title="cairo_surface_get_device ()"><code class="function">cairo_surface_get_device()</code></a>.
</p>
<p>
Devices are created using custom functions specific to the rendering
system you want to use. See the documentation for the surface types
for those functions.
</p>
<p>
An important function that devices fulfill is sharing access to the
rendering system between Cairo and your application. If you want to
access a device directly that you used to draw to with Cairo, you must
first call <a class="link" href="cairo-cairo-device-t.html#cairo-device-flush" title="cairo_device_flush ()"><code class="function">cairo_device_flush()</code></a> to ensure that Cairo finishes all
operations on the device and resets it to a clean state.
</p>
<p>
Cairo also provides the functions <a class="link" href="cairo-cairo-device-t.html#cairo-device-acquire" title="cairo_device_acquire ()"><code class="function">cairo_device_acquire()</code></a> and
<a class="link" href="cairo-cairo-device-t.html#cairo-device-release" title="cairo_device_release ()"><code class="function">cairo_device_release()</code></a> to synchronize access to the rendering system
in a multithreaded environment. This is done internally, but can also
be used by applications.
</p>
<p>
Putting this all together, a function that works with devices should
look something like this:
</p>
<div class="informalexample"><pre class="programlisting">
void
my_device_modifying_function (cairo_device_t *device)
{
cairo_status_t status;
// Ensure the device is properly reset
cairo_device_flush (device);
// Try to acquire the device
status = cairo_device_acquire (device);
if (status != CAIRO_STATUS_SUCCESS) {
printf ("Failed to acquire the device: %s\n", cairo_status_to_string (status));
return;
}
// Do the custom operations on the device here.
// But do not call any Cairo functions that might acquire devices.
// Release the device when done.
cairo_device_release (device);
}
</pre></div>
<p>
</p>
<p>
</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Please refer to the documentation of each backend for
additional usage requirements, guarantees provided, and
interactions with existing surface API of the device functions for
surfaces of that type.
</p>
</div>
<p>
</p>
</div>
<div class="refsect1" title="Details">
<a name="cairo-cairo-device-t.details"></a><h2>Details</h2>
<div class="refsect2" title="cairo_device_t">
<a name="cairo-device-t"></a><h3>cairo_device_t</h3>
<pre class="programlisting">typedef struct _cairo_device cairo_device_t;
</pre>
<p>
A <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> represents the driver interface for drawing
operations to a <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>. There are different subtypes of
<a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> for different drawing backends; for example,
<code class="function">cairo_xcb_device_create()</code> creates a device that wraps the connection
to an X Windows System using the XCB library.
</p>
<p>
The type of a device can be queried with <a class="link" href="cairo-cairo-device-t.html#cairo-device-get-type" title="cairo_device_get_type ()"><code class="function">cairo_device_get_type()</code></a>.
</p>
<p>
Memory management of <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> is done with
<a class="link" href="cairo-cairo-device-t.html#cairo-device-reference" title="cairo_device_reference ()"><code class="function">cairo_device_reference()</code></a> and <a class="link" href="cairo-cairo-device-t.html#cairo-device-destroy" title="cairo_device_destroy ()"><code class="function">cairo_device_destroy()</code></a>.
</p>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_reference ()">
<a name="cairo-device-reference"></a><h3>cairo_device_reference ()</h3>
<pre class="programlisting"><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="returnvalue">cairo_device_t</span></a> * cairo_device_reference (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Increases the reference count on <em class="parameter"><code>device</code></em> by one. This prevents
<em class="parameter"><code>device</code></em> from being destroyed until a matching call to
<a class="link" href="cairo-cairo-device-t.html#cairo-device-destroy" title="cairo_device_destroy ()"><code class="function">cairo_device_destroy()</code></a> is made.
</p>
<p>
The number of references to a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> can be get using
<a class="link" href="cairo-cairo-device-t.html#cairo-device-get-reference-count" title="cairo_device_get_reference_count ()"><code class="function">cairo_device_get_reference_count()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the referenced <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_destroy ()">
<a name="cairo-device-destroy"></a><h3>cairo_device_destroy ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_destroy (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Decreases the reference count on <em class="parameter"><code>device</code></em> by one. If the result is
zero, then <em class="parameter"><code>device</code></em> and all associated resources are freed. See
<a class="link" href="cairo-cairo-device-t.html#cairo-device-reference" title="cairo_device_reference ()"><code class="function">cairo_device_reference()</code></a>.
</p>
<p>
This function may acquire devices if the last reference was dropped.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_status ()">
<a name="cairo-device-status"></a><h3>cairo_device_status ()</h3>
<pre class="programlisting"><a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> cairo_device_status (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Checks whether an error has previously occurred for this
device.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-SUCCESS:CAPS"><code class="literal">CAIRO_STATUS_SUCCESS</code></a> on success or an error code if
the device is in an error state.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_finish ()">
<a name="cairo-device-finish"></a><h3>cairo_device_finish ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_finish (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
This function finishes the device and drops all references to
external resources. All surfaces, fonts and other objects created
for this <em class="parameter"><code>device</code></em> will be finished, too.
Further operations on the <em class="parameter"><code>device</code></em> will not affect the <em class="parameter"><code>device</code></em> but
will instead trigger a <code class="literal">CAIRO_STATUS_DEVICE_FINISHED</code> error.
</p>
<p>
When the last call to <a class="link" href="cairo-cairo-device-t.html#cairo-device-destroy" title="cairo_device_destroy ()"><code class="function">cairo_device_destroy()</code></a> decreases the
reference count to zero, cairo will call <a class="link" href="cairo-cairo-device-t.html#cairo-device-finish" title="cairo_device_finish ()"><code class="function">cairo_device_finish()</code></a> if
it hasn't been called already, before freeing the resources
associated with the device.
</p>
<p>
This function may acquire devices.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>the <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> to finish
</td>
</tr></tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_flush ()">
<a name="cairo-device-flush"></a><h3>cairo_device_flush ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_flush (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Finish any pending operations for the device and also restore any
temporary modifications cairo has made to the device's state.
This function must be called before switching from using the
device with Cairo to operating on it directly with native APIs.
If the device doesn't support direct access, then this function
does nothing.
</p>
<p>
This function may acquire devices.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="enum cairo_device_type_t">
<a name="cairo-device-type-t"></a><h3>enum cairo_device_type_t</h3>
<pre class="programlisting">typedef enum _cairo_device_type {
CAIRO_DEVICE_TYPE_DRM,
CAIRO_DEVICE_TYPE_GL,
CAIRO_DEVICE_TYPE_SCRIPT,
CAIRO_DEVICE_TYPE_XCB,
CAIRO_DEVICE_TYPE_XLIB,
CAIRO_DEVICE_TYPE_XML
} cairo_device_type_t;
</pre>
<p>
<a class="link" href="cairo-cairo-device-t.html#cairo-device-type-t" title="enum cairo_device_type_t"><span class="type">cairo_device_type_t</span></a> is used to describe the type of a given
device. The devices types are also known as "backends" within cairo.
</p>
<p>
The device type can be queried with <a class="link" href="cairo-cairo-device-t.html#cairo-device-get-type" title="cairo_device_get_type ()"><code class="function">cairo_device_get_type()</code></a>
</p>
<p>
The various <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> functions can be used with surfaces of
any type, but some backends also provide type-specific functions
that must only be called with a device of the appropriate
type. These functions have names that begin with
cairo_<span class="emphasis"><em>type</em></span>_device such as <code class="function">cairo_xcb_device_debug_set_render_version()</code>.
</p>
<p>
The behavior of calling a type-specific function with a surface of
the wrong type is undefined.
</p>
<p>
New entries may be added in future versions.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-DRM:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_DRM</code></span></p></td>
<td>The surface is of type Direct Render Manager
</td>
</tr>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-GL:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_GL</code></span></p></td>
<td>The surface is of type OpenGL
</td>
</tr>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-SCRIPT:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_SCRIPT</code></span></p></td>
<td>The surface is of type script
</td>
</tr>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-XCB:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_XCB</code></span></p></td>
<td>The surface is of type xcb
</td>
</tr>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-XLIB:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_XLIB</code></span></p></td>
<td>The surface is of type xlib
</td>
</tr>
<tr>
<td><p><a name="CAIRO-DEVICE-TYPE-XML:CAPS"></a><span class="term"><code class="literal">CAIRO_DEVICE_TYPE_XML</code></span></p></td>
<td>The surface is of type XML
<a class="link" href="cairo-cairo-surface-t.html#cairo-surface-create-for-rectangle" title="cairo_surface_create_for_rectangle ()"><code class="function">cairo_surface_create_for_rectangle()</code></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_get_type ()">
<a name="cairo-device-get-type"></a><h3>cairo_device_get_type ()</h3>
<pre class="programlisting"><a class="link" href="cairo-cairo-device-t.html#cairo-device-type-t" title="enum cairo_device_type_t"><span class="returnvalue">cairo_device_type_t</span></a> cairo_device_get_type (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
This function returns the type of the device. See <a class="link" href="cairo-cairo-device-t.html#cairo-device-type-t" title="enum cairo_device_type_t"><span class="type">cairo_device_type_t</span></a>
for available types.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> The type of <em class="parameter"><code>device</code></em>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_get_reference_count ()">
<a name="cairo-device-get-reference-count"></a><h3>cairo_device_get_reference_count ()</h3>
<pre class="programlisting">unsigned <span class="returnvalue">int</span> cairo_device_get_reference_count (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Returns the current reference count of <em class="parameter"><code>device</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the current reference count of <em class="parameter"><code>device</code></em>. If the
object is a nil object, 0 will be returned.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_set_user_data ()">
<a name="cairo-device-set-user-data"></a><h3>cairo_device_set_user_data ()</h3>
<pre class="programlisting"><a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> cairo_device_set_user_data (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> *key</code></em>,
<em class="parameter"><code><span class="type">void</span> *user_data</code></em>,
<em class="parameter"><code><a class="link" href="cairo-Types.html#cairo-destroy-func-t" title="cairo_destroy_func_t ()"><span class="type">cairo_destroy_func_t</span></a> destroy</code></em>);</pre>
<p>
Attach user data to <em class="parameter"><code>device</code></em>. To remove user data from a surface,
call this function with the key that was used to set it and <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
for <em class="parameter"><code>data</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
<td>the address of a <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> to attach the user data to
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>the user data to attach to the <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>destroy</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-Types.html#cairo-destroy-func-t" title="cairo_destroy_func_t ()"><span class="type">cairo_destroy_func_t</span></a> which will be called when the
<a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> is destroyed or when new user data is attached using the
same key.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-SUCCESS:CAPS"><code class="literal">CAIRO_STATUS_SUCCESS</code></a> or <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-NO-MEMORY:CAPS"><code class="literal">CAIRO_STATUS_NO_MEMORY</code></a> if a
slot could not be allocated for the user data.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_get_user_data ()">
<a name="cairo-device-get-user-data"></a><h3>cairo_device_get_user_data ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> * cairo_device_get_user_data (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> *key</code></em>);</pre>
<p>
Return user data previously attached to <em class="parameter"><code>device</code></em> using the
specified key. If no user data has been attached with the given
key this function returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
<td>the address of the <a class="link" href="cairo-Types.html#cairo-user-data-key-t" title="cairo_user_data_key_t"><span class="type">cairo_user_data_key_t</span></a> the user data was
attached to
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the user data previously attached or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_acquire ()">
<a name="cairo-device-acquire"></a><h3>cairo_device_acquire ()</h3>
<pre class="programlisting"><a class="link" href="cairo-Error-handling.html#cairo-status-t" title="enum cairo_status_t"><span class="returnvalue">cairo_status_t</span></a> cairo_device_acquire (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Acquires the <em class="parameter"><code>device</code></em> for the current thread. This function will block
until no other thread has acquired the device.
</p>
<p>
If the return value is <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-SUCCESS:CAPS"><code class="literal">CAIRO_STATUS_SUCCESS</code></a>, you successfully acquired the
device. From now on your thread owns the device and no other thread will be
able to acquire it until a matching call to <a class="link" href="cairo-cairo-device-t.html#cairo-device-release" title="cairo_device_release ()"><code class="function">cairo_device_release()</code></a>. It is
allowed to recursively acquire the device multiple times from the same
thread.
</p>
<p>
</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>You must never acquire two different devices at the same time
unless this is explicitly allowed. Otherwise the possibility of deadlocks
exist.
</p>
<p>
As various Cairo functions can acquire devices when called, these functions
may also cause deadlocks when you call them with an acquired device. So you
must not have a device acquired when calling them. These functions are
marked in the documentation.
</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a class="link" href="cairo-Error-handling.html#CAIRO-STATUS-SUCCESS:CAPS"><code class="literal">CAIRO_STATUS_SUCCESS</code></a> on success or an error code if
the device is in an error state and could not be
acquired. After a successful call to <a class="link" href="cairo-cairo-device-t.html#cairo-device-acquire" title="cairo_device_acquire ()"><code class="function">cairo_device_acquire()</code></a>,
a matching call to <a class="link" href="cairo-cairo-device-t.html#cairo-device-release" title="cairo_device_release ()"><code class="function">cairo_device_release()</code></a> is required.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
<hr>
<div class="refsect2" title="cairo_device_release ()">
<a name="cairo-device-release"></a><h3>cairo_device_release ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_release (<em class="parameter"><code><a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a> *device</code></em>);</pre>
<p>
Releases a <em class="parameter"><code>device</code></em> previously acquired using <a class="link" href="cairo-cairo-device-t.html#cairo-device-acquire" title="cairo_device_acquire ()"><code class="function">cairo_device_acquire()</code></a>. See
that function for details.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>device</code></em> :</span></p></td>
<td>a <a class="link" href="cairo-cairo-device-t.html#cairo-device-t" title="cairo_device_t"><span class="type">cairo_device_t</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 1.10</p>
</div>
</div>
<div class="refsect1" title="See Also">
<a name="cairo-cairo-device-t.see-also"></a><h2>See Also</h2>
<a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.15</div>
</body>
</html>