1
<refentry id="gdk-pixbuf-rendering">
3
<refentrytitle>Rendering</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
9
<refname>Rendering</refname><refpurpose>Rendering a pixbuf to a GDK drawable.</refpurpose>
12
<refsynopsisdiv><title>Synopsis</title>
15
#include <gdk-pixbuf/gdk-pixbuf.h>
18
enum <link linkend="GdkPixbufAlphaMode">GdkPixbufAlphaMode</link>;
19
void <link linkend="gdk-pixbuf-render-to-drawable-alpha">gdk_pixbuf_render_to_drawable_alpha</link>
20
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
21
<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
28
<link linkend="GdkPixbufAlphaMode">GdkPixbufAlphaMode</link> alpha_mode,
30
<link linkend="GdkRgbDither">GdkRgbDither</link> dither,
33
void <link linkend="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable</link> (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
34
<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
35
<link linkend="GdkGC">GdkGC</link> *gc,
42
<link linkend="GdkRgbDither">GdkRgbDither</link> dither,
45
void <link linkend="gdk-pixbuf-render-threshold-alpha">gdk_pixbuf_render_threshold_alpha</link>
46
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
47
<link linkend="GdkBitmap">GdkBitmap</link> *bitmap,
55
void <link linkend="gdk-pixbuf-render-pixmap-and-mask">gdk_pixbuf_render_pixmap_and_mask</link>
56
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
57
<link linkend="GdkPixmap">GdkPixmap</link> **pixmap_return,
58
<link linkend="GdkBitmap">GdkBitmap</link> **mask_return,
68
<title>Description</title>
70
The &gdk-pixbuf; library provides several convenience functions to
71
render pixbufs to GDK drawables. It uses the GdkRGB to render the
76
At this point there is not a standard alpha channel extension for
77
the X Window System, so it is not possible to use full opacity
78
information when painting images to arbitrary drawables. The
79
&gdk-pixbuf; convenience functions will threshold the opacity
80
information to create a bi-level clipping mask (black and white),
81
and use that to draw the image onto a drawable.
86
Since these functions use GdkRGB for rendering, you must
87
initialize GdkRGB before using any of them. You can do this by
88
calling <link linkend="gdk-rgb-init">gdk_rgb_init</link>() near the beginning of your program.
94
<title>Details</title>
96
<title><anchor id="GdkPixbufAlphaMode">enum GdkPixbufAlphaMode</title>
97
<programlisting>typedef enum {
98
GDK_PIXBUF_ALPHA_BILEVEL,
100
} GdkPixbufAlphaMode;
103
These values can be passed to
104
<link linkend="gdk-pixbuf-render-to-drawable-alpha">gdk_pixbuf_render_to_drawable_alpha</link>() to control how the alpha
105
chanel of an image should be handled. This function can create a
106
bilevel clipping mask (black and white) and use it while painting
107
the image. In the future, when the X Window System gets an alpha
108
channel extension, it will be possible to do full alpha
109
compositing onto arbitrary drawables. For now both cases fall
110
back to a bilevel clipping mask.
111
</para><informaltable pgwide=1 frame="none" role="enum">
113
<colspec colwidth="2*">
114
<colspec colwidth="8*">
117
<entry><literal>GDK_PIXBUF_ALPHA_BILEVEL</literal></entry>
118
<entry>A bilevel clipping mask (black and white)
119
will be created and used to draw the image. Pixels below 0.5 opacity
120
will be considered fully transparent, and all others will be
121
considered fully opaque.
125
<entry><literal>GDK_PIXBUF_ALPHA_FULL</literal></entry>
126
<entry>For now falls back to <link linkend="GDK-PIXBUF-ALPHA-BILEVEL-CAPS">GDK_PIXBUF_ALPHA_BILEVEL</link>.
127
In the future it will do full alpha compositing.
131
</tbody></tgroup></informaltable></refsect2>
133
<title><anchor id="gdk-pixbuf-render-to-drawable-alpha">gdk_pixbuf_render_to_drawable_alpha ()</title>
134
<programlisting>void gdk_pixbuf_render_to_drawable_alpha
135
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
136
<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
143
<link linkend="GdkPixbufAlphaMode">GdkPixbufAlphaMode</link> alpha_mode,
145
<link linkend="GdkRgbDither">GdkRgbDither</link> dither,
147
int y_dither);</programlisting>
149
Renders a rectangular portion of a pixbuf to a drawable. This is done using
150
GdkRGB, so the specified drawable must have the GdkRGB visual and colormap.
153
When used with <link linkend="GDK-PIXBUF-ALPHA-BILEVEL-CAPS">GDK_PIXBUF_ALPHA_BILEVEL</link>, this function has to create a bitmap
154
out of the thresholded alpha channel of the image and, it has to set this
155
bitmap as the clipping mask for the GC used for drawing. This can be a
156
significant performance penalty depending on the size and the complexity of
157
the alpha channel of the image. If performance is crucial, consider handling
158
the alpha channel yourself (possibly by caching it in your application) and
159
using <link linkend="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable</link>() or GdkRGB directly instead.</para>
162
</para><informaltable pgwide=1 frame="none" role="params">
164
<colspec colwidth="2*">
165
<colspec colwidth="8*">
167
<row><entry align="right"><parameter>pixbuf</parameter> :</entry>
170
<row><entry align="right"><parameter>drawable</parameter> :</entry>
171
<entry> Destination drawable.
173
<row><entry align="right"><parameter>src_x</parameter> :</entry>
174
<entry> Source X coordinate within pixbuf.
176
<row><entry align="right"><parameter>src_y</parameter> :</entry>
177
<entry> Source Y coordinates within pixbuf.
179
<row><entry align="right"><parameter>dest_x</parameter> :</entry>
180
<entry> Destination X coordinate within drawable.
182
<row><entry align="right"><parameter>dest_y</parameter> :</entry>
183
<entry> Destination Y coordinate within drawable.
185
<row><entry align="right"><parameter>width</parameter> :</entry>
186
<entry> Width of region to render, in pixels.
188
<row><entry align="right"><parameter>height</parameter> :</entry>
189
<entry> Height of region to render, in pixels.
191
<row><entry align="right"><parameter>alpha_mode</parameter> :</entry>
192
<entry> If the image does not have opacity information, this is ignored.
193
Otherwise, specifies how to handle transparency when rendering.
195
<row><entry align="right"><parameter>alpha_threshold</parameter> :</entry>
196
<entry> If the image does have opacity information and <parameter>alpha_mode</parameter>
197
is GDK_PIXBUF_ALPHA_BILEVEL, specifies the threshold value for opacity
200
<row><entry align="right"><parameter>dither</parameter> :</entry>
201
<entry> Dithering mode for GdkRGB.
203
<row><entry align="right"><parameter>x_dither</parameter> :</entry>
204
<entry> X offset for dither.
206
<row><entry align="right"><parameter>y_dither</parameter> :</entry>
207
<entry> Y offset for dither.
209
</tbody></tgroup></informaltable></refsect2>
211
<title><anchor id="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable ()</title>
212
<programlisting>void gdk_pixbuf_render_to_drawable (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
213
<link linkend="GdkDrawable">GdkDrawable</link> *drawable,
214
<link linkend="GdkGC">GdkGC</link> *gc,
221
<link linkend="GdkRgbDither">GdkRgbDither</link> dither,
223
int y_dither);</programlisting>
225
Renders a rectangular portion of a pixbuf to a drawable while using the
226
specified GC. This is done using GdkRGB, so the specified drawable must have
227
the GdkRGB visual and colormap. Note that this function will ignore the
228
opacity information for images with an alpha channel; the GC must already
229
have the clipping mask set if you want transparent regions to show through.
232
For an explanation of dither offsets, see the GdkRGB documentation. In
233
brief, the dither offset is important when re-rendering partial regions of an
234
image to a rendered version of the full image, or for when the offsets to a
235
base position change, as in scrolling. The dither matrix has to be shifted
236
for consistent visual results. If you do not have any of these cases, the
237
dither offsets can be both zero.</para>
240
</para><informaltable pgwide=1 frame="none" role="params">
242
<colspec colwidth="2*">
243
<colspec colwidth="8*">
245
<row><entry align="right"><parameter>pixbuf</parameter> :</entry>
248
<row><entry align="right"><parameter>drawable</parameter> :</entry>
249
<entry> Destination drawable.
251
<row><entry align="right"><parameter>gc</parameter> :</entry>
252
<entry> GC used for rendering.
254
<row><entry align="right"><parameter>src_x</parameter> :</entry>
255
<entry> Source X coordinate within pixbuf.
257
<row><entry align="right"><parameter>src_y</parameter> :</entry>
258
<entry> Source Y coordinate within pixbuf.
260
<row><entry align="right"><parameter>dest_x</parameter> :</entry>
261
<entry> Destination X coordinate within drawable.
263
<row><entry align="right"><parameter>dest_y</parameter> :</entry>
264
<entry> Destination Y coordinate within drawable.
266
<row><entry align="right"><parameter>width</parameter> :</entry>
267
<entry> Width of region to render, in pixels.
269
<row><entry align="right"><parameter>height</parameter> :</entry>
270
<entry> Height of region to render, in pixels.
272
<row><entry align="right"><parameter>dither</parameter> :</entry>
273
<entry> Dithering mode for GdkRGB.
275
<row><entry align="right"><parameter>x_dither</parameter> :</entry>
276
<entry> X offset for dither.
278
<row><entry align="right"><parameter>y_dither</parameter> :</entry>
279
<entry> Y offset for dither.
281
</tbody></tgroup></informaltable></refsect2>
283
<title><anchor id="gdk-pixbuf-render-threshold-alpha">gdk_pixbuf_render_threshold_alpha ()</title>
284
<programlisting>void gdk_pixbuf_render_threshold_alpha
285
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
286
<link linkend="GdkBitmap">GdkBitmap</link> *bitmap,
293
int alpha_threshold);</programlisting>
295
Takes the opacity values in a rectangular portion of a pixbuf and thresholds
296
them to produce a bi-level alpha mask that can be used as a clipping mask for
300
</para><informaltable pgwide=1 frame="none" role="params">
302
<colspec colwidth="2*">
303
<colspec colwidth="8*">
305
<row><entry align="right"><parameter>pixbuf</parameter> :</entry>
308
<row><entry align="right"><parameter>bitmap</parameter> :</entry>
309
<entry> Bitmap where the bilevel mask will be painted to.
311
<row><entry align="right"><parameter>src_x</parameter> :</entry>
312
<entry> Source X coordinate.
314
<row><entry align="right"><parameter>src_y</parameter> :</entry>
315
<entry> source Y coordinate.
317
<row><entry align="right"><parameter>dest_x</parameter> :</entry>
318
<entry> Destination X coordinate.
320
<row><entry align="right"><parameter>dest_y</parameter> :</entry>
321
<entry> Destination Y coordinate.
323
<row><entry align="right"><parameter>width</parameter> :</entry>
324
<entry> Width of region to threshold.
326
<row><entry align="right"><parameter>height</parameter> :</entry>
327
<entry> Height of region to threshold.
329
<row><entry align="right"><parameter>alpha_threshold</parameter> :</entry>
330
<entry> Opacity values below this will be painted as zero; all
331
other values will be painted as one.
333
</tbody></tgroup></informaltable></refsect2>
335
<title><anchor id="gdk-pixbuf-render-pixmap-and-mask">gdk_pixbuf_render_pixmap_and_mask ()</title>
336
<programlisting>void gdk_pixbuf_render_pixmap_and_mask
337
(<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
338
<link linkend="GdkPixmap">GdkPixmap</link> **pixmap_return,
339
<link linkend="GdkBitmap">GdkBitmap</link> **mask_return,
340
int alpha_threshold);</programlisting>
342
Creates a pixmap and a mask bitmap which are returned in the <parameter>pixmap_return</parameter>
343
and <parameter>mask_return</parameter> arguments, respectively, and renders a pixbuf and its
344
corresponding tresholded alpha mask to them. This is merely a convenience
345
function; applications that need to render pixbufs with dither offsets or to
346
given drawables should use <link linkend="gdk-pixbuf-render-to-drawable-alpha">gdk_pixbuf_render_to_drawable_alpha</link>() or
347
<link linkend="gdk-pixbuf-render-to-drawable">gdk_pixbuf_render_to_drawable</link>(), and <link linkend="gdk-pixbuf-render-threshold-alpha">gdk_pixbuf_render_threshold_alpha</link>().
350
If the pixbuf does not have an alpha channel, then *<parameter>mask_return</parameter> will be set
351
to <literal>NULL</literal>.</para>
354
</para><informaltable pgwide=1 frame="none" role="params">
356
<colspec colwidth="2*">
357
<colspec colwidth="8*">
359
<row><entry align="right"><parameter>pixbuf</parameter> :</entry>
362
<row><entry align="right"><parameter>pixmap_return</parameter> :</entry>
363
<entry> Return value for the created pixmap.
365
<row><entry align="right"><parameter>mask_return</parameter> :</entry>
366
<entry> Return value for the created mask.
368
<row><entry align="right"><parameter>alpha_threshold</parameter> :</entry>
369
<entry> Threshold value for opacity values.
371
</tbody></tgroup></informaltable></refsect2>
378
<title>See Also</title>
added
removed
doc/sgml/rendering.sgml
