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
|
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cairo-Image-Surfaces">
<refmeta>
<refentrytitle id="top_of_page">Image Surfaces</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAIRO Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Image Surfaces</refname>
<refpurpose>Rendering to memory buffers</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>
<synopsis>
enum <link linkend="cairo-format-t">cairo_format_t</link>;
<link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-image-surface-create">cairo_image_surface_create</link> (<link linkend="cairo-format-t">cairo_format_t</link> format,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);
<link linkend="cairo-surface-t">cairo_surface_t</link>* <link linkend="cairo-image-surface-create-for-data">cairo_image_surface_create_for_data</link>
(unsigned <link linkend="char">char</link> *data,
<link linkend="cairo-format-t">cairo_format_t</link> format,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height,
<link linkend="int">int</link> stride);
unsigned <link linkend="char">char</link>* <link linkend="cairo-image-surface-get-data">cairo_image_surface_get_data</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="cairo-format-t">cairo_format_t</link> <link linkend="cairo-image-surface-get-format">cairo_image_surface_get_format</link>
(<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="int">int</link> <link linkend="cairo-image-surface-get-width">cairo_image_surface_get_width</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="int">int</link> <link linkend="cairo-image-surface-get-height">cairo_image_surface_get_height</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
<link linkend="int">int</link> <link linkend="cairo-image-surface-get-stride">cairo_image_surface_get_stride</link> (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);
</synopsis>
</refsynopsisdiv>
<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>
Image surfaces provide the ability to render to memory buffers
either allocated by cairo or by the calling code. The supported
image formats are those defined in <link linkend="cairo-format-t"><type>cairo_format_t</type></link>.
</para>
</refsect1>
<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="cairo-format-t" role="enum"/>enum cairo_format_t</title>
<indexterm><primary>cairo_format_t</primary></indexterm><programlisting>typedef enum _cairo_format {
CAIRO_FORMAT_ARGB32,
CAIRO_FORMAT_RGB24,
CAIRO_FORMAT_A8,
CAIRO_FORMAT_A1,
CAIRO_FORMAT_RGB16_565
} cairo_format_t;
</programlisting>
<para>
<link linkend="cairo-format-t"><type>cairo_format_t</type></link> is used to identify the memory format of
image data.
</para>
<para>
New entries may be added in future versions.</para>
<para>
</para><variablelist role="enum">
<varlistentry>
<term><anchor id="CAIRO-FORMAT-ARGB32:CAPS" role="constant"/><literal>CAIRO_FORMAT_ARGB32</literal></term>
<listitem><simpara> each pixel is a 32-bit quantity, with
alpha in the upper 8 bits, then red, then green, then blue.
The 32-bit quantities are stored native-endian. Pre-multiplied
alpha is used. (That is, 50% transparent red is 0x80800000,
not 0x80ff0000.)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-FORMAT-RGB24:CAPS" role="constant"/><literal>CAIRO_FORMAT_RGB24</literal></term>
<listitem><simpara> each pixel is a 32-bit quantity, with
the upper 8 bits unused. Red, Green, and Blue are stored
in the remaining 24 bits in that order.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-FORMAT-A8:CAPS" role="constant"/><literal>CAIRO_FORMAT_A8</literal></term>
<listitem><simpara> each pixel is a 8-bit quantity holding
an alpha value.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-FORMAT-A1:CAPS" role="constant"/><literal>CAIRO_FORMAT_A1</literal></term>
<listitem><simpara> each pixel is a 1-bit quantity holding
an alpha value. Pixels are packed together into 32-bit
quantities. The ordering of the bits matches the
endianess of the platform. On a big-endian machine, the
first pixel is in the uppermost bit, on a little-endian
machine the first pixel is in the least-significant bit.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-FORMAT-RGB16-565:CAPS" role="constant"/><literal>CAIRO_FORMAT_RGB16_565</literal></term>
<listitem><simpara> This format value is deprecated. It has
never been properly implemented in cairo and should not be used
by applications. For example, any attempt to create an image
surface with a format of CAIRO_FORMAT_RGB16_565 will fail. This
format value was added as part of fixing cairo's xlib backend to
work with X servers advertising a 16-bit, 565 visual. But as it
turned out, adding this format to <link linkend="cairo-format-t"><type>cairo_format_t</type></link> was not
necessary, and was a mistake, (cairo's xlib backend can work fine
with 16-bit visuals in the same way it works with BGR visuals
without any BGR formats in <link linkend="cairo-format-t"><type>cairo_format_t</type></link>). (Since 1.2)
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-create" role="function"/>cairo_image_surface_create ()</title>
<indexterm><primary>cairo_image_surface_create</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_image_surface_create (<link linkend="cairo-format-t">cairo_format_t</link> format,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height);</programlisting>
<para>
Creates an image surface of the specified format and
dimensions. Initially the surface contents are all
0. (Specifically, within each pixel, each color or alpha channel
belonging to format will be 0. The contents of bits within a pixel,
but not belonging to the given format are undefined).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> format of pixels in the surface to create
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter> :</term>
<listitem><simpara> width of the surface, in pixels
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter> :</term>
<listitem><simpara> height of the surface, in pixels
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the newly created 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 an error such as out of memory
occurs. You can use <link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link> to check for this.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-create-for-data" role="function"/>cairo_image_surface_create_for_data ()</title>
<indexterm><primary>cairo_image_surface_create_for_data</primary></indexterm><programlisting><link linkend="cairo-surface-t">cairo_surface_t</link>* cairo_image_surface_create_for_data
(unsigned <link linkend="char">char</link> *data,
<link linkend="cairo-format-t">cairo_format_t</link> format,
<link linkend="int">int</link> width,
<link linkend="int">int</link> height,
<link linkend="int">int</link> stride);</programlisting>
<para>
Creates an image surface for the provided pixel data. The output
buffer must be kept around until the <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> is destroyed
or <link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> is called on the surface. The initial
contents of <parameter>buffer</parameter> will be used as the inital image contents; you
must explicitely clear the buffer, using, for example,
<link linkend="cairo-rectangle"><function>cairo_rectangle()</function></link> and <link linkend="cairo-fill"><function>cairo_fill()</function></link> if you want it cleared.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter> :</term>
<listitem><simpara> a pointer to a buffer supplied by the application
in which to write contents.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter> :</term>
<listitem><simpara> the format of pixels in the buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter> :</term>
<listitem><simpara> the width of the image to be stored in the buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter> :</term>
<listitem><simpara> the height of the image to be stored in the buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>stride</parameter> :</term>
<listitem><simpara> the number of bytes between the start of rows
in the buffer. Having this be specified separate from <parameter>width</parameter>
allows for padding at the end of rows, or for writing
to a subportion of a larger image.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the newly created 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 an error such as out of memory
occurs. You can use <link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link> to check for this.
See <link linkend="cairo-surface-set-user-data"><function>cairo_surface_set_user_data()</function></link> for a means of attaching a
destroy-notification fallback to the surface if necessary.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-get-data" role="function" condition="since:1.2"/>cairo_image_surface_get_data ()</title>
<indexterm role="1.2"><primary>cairo_image_surface_get_data</primary></indexterm><programlisting>unsigned <link linkend="char">char</link>* cairo_image_surface_get_data (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Get a pointer to the data of the image surface, for direct
inspection or modification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-image-surface-t"><type>cairo_image_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the image data of this surface or NULL
if <parameter>surface</parameter> is not an image surface.
</simpara></listitem></varlistentry>
</variablelist><para>Since 1.2
</para></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-get-format" role="function" condition="since:1.2"/>cairo_image_surface_get_format ()</title>
<indexterm role="1.2"><primary>cairo_image_surface_get_format</primary></indexterm><programlisting><link linkend="cairo-format-t">cairo_format_t</link> cairo_image_surface_get_format
(<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Get the format of the surface.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-image-surface-t"><type>cairo_image_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the format of the surface
</simpara></listitem></varlistentry>
</variablelist><para>Since 1.2
</para></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-get-width" role="function"/>cairo_image_surface_get_width ()</title>
<indexterm><primary>cairo_image_surface_get_width</primary></indexterm><programlisting><link linkend="int">int</link> cairo_image_surface_get_width (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Get the width of the image surface in pixels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-image-surface-t"><type>cairo_image_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the width of the surface in pixels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-get-height" role="function"/>cairo_image_surface_get_height ()</title>
<indexterm><primary>cairo_image_surface_get_height</primary></indexterm><programlisting><link linkend="int">int</link> cairo_image_surface_get_height (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Get the height of the image surface in pixels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-image-surface-t"><type>cairo_image_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the height of the surface in pixels.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-image-surface-get-stride" role="function" condition="since:1.2"/>cairo_image_surface_get_stride ()</title>
<indexterm role="1.2"><primary>cairo_image_surface_get_stride</primary></indexterm><programlisting><link linkend="int">int</link> cairo_image_surface_get_stride (<link linkend="cairo-surface-t">cairo_surface_t</link> *surface);</programlisting>
<para>
Get the stride of the image surface in bytes</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter> :</term>
<listitem><simpara> a <link linkend="cairo-image-surface-t"><type>cairo_image_surface_t</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the stride of the image surface in bytes (or 0 if
<parameter>surface</parameter> is not an image surface). The stride is the distance in
bytes from the beginning of one row of the image data to the
beginning of the next row.
</simpara></listitem></varlistentry>
</variablelist><para>Since 1.2
</para></refsect2>
</refsect1>
</refentry>
|
