1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="cairo-cairo-surface-t">
<refmeta>
<refentrytitle>cairo_surface_t</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAIRO Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>cairo_surface_t</refname><refpurpose></refpurpose>
</refnamediv>
<refsynopsisdiv><title>Synopsis</title>
<synopsis>
typedef <link linkend="cairo-surface-t">cairo_surface_t</link>;
<link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-surface-create-similar">cairo_surface_create_similar</link>
(<link linkend="cairo-surface-t">cairo_surface_t</link> *other,
<link linkend="cairo-content-t">cairo_content_t</link> content,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);
<link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-surface-reference">cairo_surface_reference</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="void">void</link> <link linkend="cairo-surface-destroy">cairo_surface_destroy</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="cairo-status-t">cairo_status_t</link> <link linkend="cairo-surface-status">cairo_surface_status</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="void">void</link> <link linkend="cairo-surface-finish">cairo_surface_finish</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="void">void</link> <link linkend="cairo-surface-get-font-options">cairo_surface_get_font_options</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="cairo-font-options-t">cairo_font_options_t</link> *options);
<link linkend="cairo-status-t">cairo_status_t</link> <link linkend="cairo-surface-set-user-data">cairo_surface_set_user_data</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
const <link linkend="cairo-user-data-key-t">cairo_user_data_key_t</link> *key,
<link linkend="void">void</link> *user_data,
<link linkend="cairo-destroy-func-t">cairo_destroy_func_t</link> destroy);
<link linkend="void">void</link>* <link linkend="cairo-surface-get-user-data">cairo_surface_get_user_data</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
const <link linkend="cairo-user-data-key-t">cairo_user_data_key_t</link> *key);
<link linkend="void">void</link> <link linkend="cairo-surface-flush">cairo_surface_flush</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="void">void</link> <link linkend="cairo-surface-mark-dirty">cairo_surface_mark_dirty</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="void">void</link> <link linkend="cairo-surface-mark-dirty-rectangle">cairo_surface_mark_dirty_rectangle</link>
(<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="int">int</link> x,
<link linkend="int">int</link> y,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);
<link linkend="void">void</link> <link linkend="cairo-surface-set-device-offset">cairo_surface_set_device_offset</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="double">double</link> x_offset,
<link linkend="double">double</link> y_offset);
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
</para>
</refsect1>
<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="cairo-surface-t"/>cairo_surface_t</title>
<indexterm><primary>cairo_surface_t</primary></indexterm><programlisting>typedef struct _cairo_surface cairo_surface_t;
</programlisting>
<para>
A <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> represents an image, either as the destination
of a drawing operation or as source when drawing onto another
surface. There are different subtypes of cairo_surface_t for
different drawing backends; for example, <link linkend="cairo-image-surface-create"><function>cairo_image_surface_create()</function></link>
creates a bitmap image in memory.
</para>
<para>
Memory management of <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> is done with
<link linkend="cairo-surface-reference"><function>cairo_surface_reference()</function></link> and <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link>.</para>
<para>
</para></refsect2>
<refsect2>
<title><anchor id="cairo-surface-create-similar"/>cairo_surface_create_similar ()</title>
<indexterm><primary>cairo_surface_create_similar</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_surface_create_similar
(<link linkend="cairo-surface-t">cairo_surface_t</link> *other,
<link linkend="cairo-content-t">cairo_content_t</link> content,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);</programlisting>
<para>
Create a new surface that is as compatible as possible with an
existing surface. The new surface will use the same backend as
<parameter>other</parameter> unless that is not possible for some reason.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>other</parameter> :</term>
<listitem><simpara> an existing surface used to select the backend of the new surface
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>content</parameter> :</term>
<listitem><simpara> the content for the new surface
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter> :</term>
<listitem><simpara> width of the new surface, (in device-space units)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter> :</term>
<listitem><simpara> height of the new surface (in device-space units)
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the newly allocated surface. The caller
owns the surface and should call cairo_surface_destroy when done
with it.
This function always returns a valid pointer, but it will return a
pointer to a "nil" surface if <parameter>other</parameter> is already in an error state
or any other error occurs.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-reference"/>cairo_surface_reference ()</title>
<indexterm><primary>cairo_surface_reference</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_surface_reference (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Increases the reference count on <parameter>surface</parameter> by one. This prevents
<parameter>surface</parameter> from being destroyed until a matching call to
<link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> is made.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the referenced <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-destroy"/>cairo_surface_destroy ()</title>
<indexterm><primary>cairo_surface_destroy</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_destroy (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Decreases the reference count on <parameter>surface</parameter> by one. If the result is
zero, then <parameter>surface</parameter> and all associated resources are freed. See
<link linkend="cairo-surface-reference"><function>cairo_surface_reference()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-t"><type>cairo_t</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-status"/>cairo_surface_status ()</title>
<indexterm><primary>cairo_surface_status</primary></indexterm><programlisting><link linkend="cairo-status-t">cairo_status_t</link> cairo_surface_status (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Checks whether an error has previously occurred for this
surface.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>CAIRO_STATUS_SUCCESS</literal>, <literal>CAIRO_STATUS_NULL_POINTER</literal>,
<literal>CAIRO_STATUS_NO_MEMORY</literal>, <literal>CAIRO_STATUS_READ_ERROR</literal>,
<literal>CAIRO_STATUS_INVALID_CONTENT</literal>, <literal>CAIRO_STATUS_INVALUE_FORMAT</literal>, or
<literal>CAIRO_STATUS_INVALID_VISUAL</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-finish"/>cairo_surface_finish ()</title>
<indexterm><primary>cairo_surface_finish</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_finish (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
This function finishes the surface and drops all references to
external resources. For example, for the Xlib backend it means
that cairo will no longer access the drawable, which can be freed.
After calling <link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> the only valid operations on a
surface are getting and setting user data and referencing and
destroying it. Further drawing to the surface will not affect the
surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED
error.
</para>
<para>
When the last call to <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> decreases the
reference count to zero, cairo will call <link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> if
it hasn't been called already, before freeing the resources
associated with the surface.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> the <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> to finish
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-get-font-options"/>cairo_surface_get_font_options ()</title>
<indexterm><primary>cairo_surface_get_font_options</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_get_font_options (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="cairo-font-options-t">cairo_font_options_t</link> *options);</programlisting>
<para>
Retrieves the default font rendering options for the surface.
This allows display surfaces to report the correct subpixel order
for rendering on them, print surfaces to disable hinting of
metrics and so forth. The result can then be used with
<link linkend="cairo-scaled-font-create"><function>cairo_scaled_font_create()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>options</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-font-options-t"><type>cairo_font_options_t</type></link> object into which to store
the retrieved options. All existing values are overwritten
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-set-user-data"/>cairo_surface_set_user_data ()</title>
<indexterm><primary>cairo_surface_set_user_data</primary></indexterm><programlisting><link linkend="cairo-status-t">cairo_status_t</link> cairo_surface_set_user_data (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
const <link linkend="cairo-user-data-key-t">cairo_user_data_key_t</link> *key,
<link linkend="void">void</link> *user_data,
<link linkend="cairo-destroy-func-t">cairo_destroy_func_t</link> destroy);</programlisting>
<para>
Attach user data to <parameter>surface</parameter>. To remove user data from a surface,
call this function with the key that was used to set it and <literal>NULL</literal>
for <parameter>data</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara> the address of a <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> to attach the user data to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> the user data to attach to the surface
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>destroy</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-destroy-func-t"><type>cairo_destroy_func_t</type></link> which will be called when the
surface is destroyed or when new user data is attached using the
same key.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>CAIRO_STATUS_SUCCESS</literal> or <literal>CAIRO_STATUS_NO_MEMORY</literal> if a
slot could not be allocated for the user data.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-get-user-data"/>cairo_surface_get_user_data ()</title>
<indexterm><primary>cairo_surface_get_user_data</primary></indexterm><programlisting><link linkend="void">void</link>* cairo_surface_get_user_data (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
const <link linkend="cairo-user-data-key-t">cairo_user_data_key_t</link> *key);</programlisting>
<para>
Return user data previously attached to <parameter>surface</parameter> using the specified
key. If no user data has been attached with the given key this
function returns <literal>NULL</literal>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter> :</term>
<listitem><simpara> the address of the <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> the user data was
attached to
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the user data previously attached or <literal>NULL</literal>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-flush"/>cairo_surface_flush ()</title>
<indexterm><primary>cairo_surface_flush</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_flush (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Do any pending drawing for the surface and also restore any
temporary modification's cairo has made to the surface's
state. This function must be called before switching from
drawing on the surface with cairo to drawing on it directly
with native APIs. If the surface doesn't support direct access,
then this function does nothing.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-mark-dirty"/>cairo_surface_mark_dirty ()</title>
<indexterm><primary>cairo_surface_mark_dirty</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_mark_dirty (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Tells cairo that drawing has been done to surface using means other
than cairo, and that cairo should reread any cached areas. Note
that you must call <link linkend="cairo-surface-flush"><function>cairo_surface_flush()</function></link> before doing such drawing.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-mark-dirty-rectangle"/>cairo_surface_mark_dirty_rectangle ()</title>
<indexterm><primary>cairo_surface_mark_dirty_rectangle</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_mark_dirty_rectangle
(<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="int">int</link> x,
<link linkend="int">int</link> y,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);</programlisting>
<para>
Like <link linkend="cairo-surface-mark-dirty"><function>cairo_surface_mark_dirty()</function></link>, but drawing has been done only to
the specified rectangle, so that cairo can retain cached contents
for other parts of the surface.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x</parameter> :</term>
<listitem><simpara> X coordinate of dirty rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y</parameter> :</term>
<listitem><simpara> Y coordinate of dirty rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter> :</term>
<listitem><simpara> width of dirty rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter> :</term>
<listitem><simpara> height of dirty rectangle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-surface-set-device-offset"/>cairo_surface_set_device_offset ()</title>
<indexterm><primary>cairo_surface_set_device_offset</primary></indexterm><programlisting><link linkend="void">void</link> cairo_surface_set_device_offset (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface,
<link linkend="double">double</link> x_offset,
<link linkend="double">double</link> y_offset);</programlisting>
<para>
Sets an offset that is added to the device coordinates determined
by the CTM when drawing to <parameter>surface</parameter>. One use case for this function
is when we want to create a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> that redirects drawing
for a portion of an onscreen surface to an offscreen surface in a
way that is completely invisible to the user of the cairo
API. Setting a transformation via <link linkend="cairo-translate"><function>cairo_translate()</function></link> isn't
sufficient to do this, since functions like
<link linkend="cairo-device-to-user"><function>cairo_device_to_user()</function></link> will expose the hidden offset.
</para>
<para>
Note that the offset only affects drawing to the surface, not using
the surface in a surface pattern.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x_offset</parameter> :</term>
<listitem><simpara> the offset in the X direction, in device units
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y_offset</parameter> :</term>
<listitem><simpara> the offset in the Y direction, in device units
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>
|
