Gtk2::Gdk::Pixbuf(3pm)

1Gtk2::Gdk::Pixbuf(3)  User Contributed Perl Documentation Gtk2::Gdk::Pixbuf(3)
2
3
4

NAME

6       Gtk2::Gdk::Pixbuf
7

HIERARCHY

9         Glib::Object
10         +----Gtk2::Gdk::Pixbuf
11

METHODS

13       pixbuf = Gtk2::Gdk::Pixbuf->new ($colorspace, $has_alpha,
14       $bits_per_sample, $width, $height)
15
16           * $colorspace (Gtk2::Gdk::Colorspace)
17           * $has_alpha (boolean)
18           * $bits_per_sample (integer)
19           * $width (integer)
20           * $height (integer)
21
22       pixbuf = Gtk2::Gdk::Pixbuf->new_from_data ($data, $colorspace,
23       $has_alpha, $bits_per_sample, $width, $height, $rowstride)
24
25           * $data (Gtk2::Gdk::Pixbuf) pixel data, usually made with pack()
26           * $colorspace (Gtk2::Gdk::Colorspace)
27           * $has_alpha (boolean) true if the image data includes an alpha
28           channel (opacity information).
29           * $bits_per_sample (integer)
30           * $width (integer) in pixels.
31           * $height (integer) in pixels.
32           * $rowstride (integer) distance in bytes between row starts; usu‐
33           ally 3*width for rgb data, 4*width if $has_alpha is true.
34
35           Creates a new Gtk2::Gdk::Pixbuf out of in-memory image data.  Cur‐
36           rently only RGB images with 8 bits per sample are supported.
37
38           In C this function allows you to wrap a GdkPixbuf structure around
39           existing pixel data.  In Perl, we have to use "pack" to generate a
40           scalar containing the pixel data, and pass that scalar to
41           "new_from_data", which copies the scalar to keep it around.  It
42           also manages the memory automagically, so there's no need for a
43           destruction notifier function.  This all means that if you change
44           your copy of the data scalar later, the pixbuf will not reflect
45           that, but because of the way perl manages string data and scalars,
46           it would be pretty fragile to do that in the first place.  If you
47           need to modify a pixbuf's data after it has been created, you can
48           create new pixbufs for the changed regions and use "$pixbuf->com‐
49           posite", or try a different approach (possibly use a server-side
50           pixmap and gdk drawing primitives, or something like libart).
51
52       pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename)
53
54           * $filename (localized file name)
55
56           May croak with a Glib::Error in $@ on failure.
57
58       pixbuf = Gtk2::Gdk::Pixbuf->new_from_file_at_scale ($filename, $width,
59       $height, $preserve_aspect_ratio)
60
61           * $filename (localized file name)
62           * $width (integer)
63           * $height (integer)
64           * $preserve_aspect_ratio (boolean)
65
66           May croak with a Glib::Error in $@ on failure.
67
68       pixbuf = Gtk2::Gdk::Pixbuf->new_from_file_at_size ($filename, $width,
69       $height)
70
71           * $filename (localized file name)
72           * $width (integer)
73           * $height (integer)
74
75           May croak with a Glib::Error in $@ on failure.
76
77       pixbuf = Gtk2::Gdk::Pixbuf->new_from_inline ($data, $copy_pixels=TRUE)
78
79           * $data (Gtk2::Gdk::Pixbuf) the format is special, see discussion
80           * $copy_pixels (boolean) whether $data should be copied, defaults
81           to true
82
83           Gtk+ ships with a tool called "gdk-pixbuf-csource", which turns any
84           image understood by gdk-pixbuf into the C syntax of the declaration
85           of a static data structure containing that image data, to be
86           #included directly into your source code.
87           "gdk_pixbuf_new_from_inline" creates a new GdkPixbuf from that data
88           structure.
89
90           Currently, this is not very easy to do from Perl.  The output of
91           "gdk-pixbuf-csource" must be mangled rather ruthlessly to create
92           valid Perl code using pack and translation from C string escapes to
93           valid Perl string escapes (for encoding and interpretation isses).
94           Because Perl scalars are garbage collected, it's rather rare to
95           have the ability to use static data, so $copy_pixels defaults to
96           true; if you can guarantee the image data will outlive the pixbuf
97           you can pass false here and save some memory.
98
99           For more information, see the description of
100           "gdk_pixbuf_new_from_inline" in the C API reference at
101           http://gtk.org/api/ .
102
103           May croak with a Glib::Error in $@ on failure.
104
105       pixbuf = Gtk2::Gdk::Pixbuf->new_from_xpm_data (...)
106
107           * ... (list) xpm data as a list of strings (see discussion)
108
109           X Pixel Map (XPM) files are designed to be easy to edit and easy to
110           include directly into C programs.  The file format is the C syntax
111           of the declaration and initialization of a variable containing an
112           array of strings.  "new_from_xpm_data" allows you to create an
113           image from such data included directly in your program source.
114
115           Since XPM files are C syntax, you must mangle that source a bit to
116           work in a Perl program.  For example, this is a valid xpm, but it
117           is not valid Perl code:
118
119            /* XPM */
120            static char * test_xpm[] = {
121            "4 4 3 1",
122            "      c None",
123            ".     c red",
124            "+     c blue",
125            ".. +",
126            ". ++",
127            " ++.",
128            "++.."};
129
130           You'll need to change the array declaration format, and change the
131           double-quoted strings to single-quoted to avoid Perl interpreting
132           any chars in the strings as special.
133
134            my @test_xpm = (
135            '4 4 3 1',
136            '      c None',
137            '.     c red',
138            '+     c blue',
139            '.. +',
140            '. ++',
141            ' ++.',
142            '++..');
143
144            $pixbuf = Gtk2::Gdk::Pixbuf->new_from_xpm_data (@test_xpm);
145
146           [It's only two or three regexes... Perhaps we should distribute a
147           script to convert XPM files to the proper format?]
148
149       pixbuf = $src_pixbuf->new_subpixbuf ($src_x, $src_y, $width, $height)
150
151           * $src_x (integer)
152           * $src_y (integer)
153           * $width (integer)
154           * $height (integer)
155
156       pixbuf = $pixbuf->add_alpha ($substitute_color, $r, $g, $b)
157
158           * $substitute_color (boolean)
159           * $r (Glib::UChar)
160           * $g (Glib::UChar)
161           * $b (Glib::UChar)
162
163       integer = $pixbuf->get_bits_per_sample
164
165       colorspace = $pixbuf->get_colorspace
166
167       $src->composite ($dest, $dest_x, $dest_y, $dest_width, $dest_height,
168       $offset_x, $offset_y, $scale_x, $scale_y, $interp_type, $overall_alpha)
169
170           * $dest (Gtk2::Gdk::Pixbuf)
171           * $dest_x (integer)
172           * $dest_y (integer)
173           * $dest_width (integer)
174           * $dest_height (integer)
175           * $offset_x (double)
176           * $offset_y (double)
177           * $scale_x (double)
178           * $scale_y (double)
179           * $interp_type (Gtk2::Gdk::InterpType)
180           * $overall_alpha (integer)
181
182       $src->composite_color ($dest, $dest_x, $dest_y, $dest_width,
183       $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type,
184       $overall_alpha, $check_x, $check_y, $check_size, $color1, $color2)
185
186           * $dest (Gtk2::Gdk::Pixbuf)
187           * $dest_x (integer)
188           * $dest_y (integer)
189           * $dest_width (integer)
190           * $dest_height (integer)
191           * $offset_x (double)
192           * $offset_y (double)
193           * $scale_x (double)
194           * $scale_y (double)
195           * $interp_type (Gtk2::Gdk::InterpType)
196           * $overall_alpha (integer)
197           * $check_x (integer)
198           * $check_y (integer)
199           * $check_size (integer)
200           * $color1 (unsigned)
201           * $color2 (unsigned)
202
203       pixbuf = $src->composite_color_simple ($dest_width, $dest_height,
204       $interp_type, $overall_alpha, $check_size, $color1, $color2)
205
206           * $dest_width (integer)
207           * $dest_height (integer)
208           * $interp_type (Gtk2::Gdk::InterpType)
209           * $overall_alpha (integer)
210           * $check_size (integer)
211           * $color1 (unsigned)
212           * $color2 (unsigned)
213
214       pixbuf = $pixbuf->copy
215
216       $src_pixbuf->copy_area ($src_x, $src_y, $width, $height, $dest_pixbuf,
217       $dest_x, $dest_y)
218
219           * $src_x (integer)
220           * $src_y (integer)
221           * $width (integer)
222           * $height (integer)
223           * $dest_pixbuf (Gtk2::Gdk::Pixbuf)
224           * $dest_x (integer)
225           * $dest_y (integer)
226
227       list = Gtk2::Gdk::Pixbuf->get_file_info ($filename)
228
229           * $filename (localized file name)
230
231       $pixbuf->fill ($pixel)
232
233           * $pixel (unsigned) a packed RGBA value.
234
235           Clear $pixbuf to contain only the value given in $pixel.
236
237       pixbuf = $src->flip ($horizontal)
238
239           * $horizontal (boolean)
240
241       list = Gtk2::Gdk::Pixbuf->get_formats
242
243           Returns a list of hashes with information about the formats sup‐
244           ported by Gtk2::Gdk::Pixbuf.
245
246       pixbuf = Gtk2::Gdk::Pixbuf->get_from_drawable ($src, $cmap, $src_x,
247       $src_y, $dest_x, $dest_y, $width, $height)
248
249       pixbuf = $pixbuf->get_from_drawable ($src, $cmap, $src_x, $src_y,
250       $dest_x, $dest_y, $width, $height)
251
252           * $src (Gtk2::Gdk::Drawable)
253           * $cmap (Gtk2::Gdk::Colormap or undef)
254           * $src_x (integer)
255           * $src_y (integer)
256           * $dest_x (integer)
257           * $dest_y (integer)
258           * $width (integer)
259           * $height (integer)
260
261           Fetch pixels from a Gtk2::Gdk::Drawable as a Gtk2::Gdk::Pixbuf.
262           Returns a new Gtk2::Gdk::Pixbuf if you use the class form, or
263           $pixbuf if you call it on an existing pixbuf.
264
265       pixbuf = Gtk2::Gdk::Pixbuf->get_from_image ($src, $cmap, $src_x,
266       $src_y, $dest_x, $dest_y, $width, $height)
267
268       pixbuf = $pixbuf->get_from_image ($src, $cmap, $src_x, $src_y, $dest_x,
269       $dest_y, $width, $height)
270
271           * $src (Gtk2::Gdk::Image)
272           * $cmap (Gtk2::Gdk::Colormap or undef)
273           * $src_x (integer)
274           * $src_y (integer)
275           * $dest_x (integer)
276           * $dest_y (integer)
277           * $width (integer)
278           * $height (integer)
279
280           Fetch pixels from a Gtk2::Gdk::Image as a Gtk2::Gdk::Pixbuf.
281           Returns a new Gtk2::Gdk::Pixbuf if you use the class form, or
282           $pixbuf if you call it on an existing pixbuf.
283
284       boolean = $pixbuf->get_has_alpha
285
286       integer = $pixbuf->get_height
287
288       integer = $pixbuf->get_n_channels
289
290       string or undef = $pixbuf->get_option ($key)
291
292           * $key (string)
293
294       scalar = $pixbuf->get_pixels
295
296       pixmap = $pixbuf->render_pixmap_and_mask ($alpha_threshold)
297
298       (pixmap, mask) = $pixbuf->render_pixmap_and_mask ($alpha_threshold)
299
300           * $alpha_threshold (integer)
301
302       pixmap = $pixbuf->render_pixmap_and_mask_for_colormap ($colormap,
303       $alpha_threshold)
304
305       (pixmap, mask) = $pixbuf->render_pixmap_and_mask_for_colormap ($col‐
306       ormap, $alpha_threshold)
307
308           * $colormap (Gtk2::Gdk::Colormap)
309           * $alpha_threshold (integer)
310
311       $pixbuf->render_threshold_alpha ($bitmap, $src_x, $src_y, $dest_x,
312       $dest_y, $width, $height, $alpha_threshold)
313
314           * $bitmap (Gtk2::Gdk::Bitmap)
315           * $src_x (integer)
316           * $src_y (integer)
317           * $dest_x (integer)
318           * $dest_y (integer)
319           * $width (integer)
320           * $height (integer)
321           * $alpha_threshold (integer)
322
323       $pixbuf->render_to_drawable ($drawable, $gc, $src_x, $src_y, $dest_x,
324       $dest_y, $width, $height, $dither, $x_dither, $y_dither)
325
326           * $drawable (Gtk2::Gdk::Drawable)
327           * $gc (Gtk2::Gdk::GC)
328           * $src_x (integer)
329           * $src_y (integer)
330           * $dest_x (integer)
331           * $dest_y (integer)
332           * $width (integer)
333           * $height (integer)
334           * $dither (Gtk2::Gdk::RgbDither)
335           * $x_dither (integer)
336           * $y_dither (integer)
337
338       $pixbuf->render_to_drawable_alpha ($drawable, $src_x, $src_y, $dest_x,
339       $dest_y, $width, $height, $alpha_mode, $alpha_threshold, $dither,
340       $x_dither, $y_dither)
341
342           * $drawable (Gtk2::Gdk::Drawable)
343           * $src_x (integer)
344           * $src_y (integer)
345           * $dest_x (integer)
346           * $dest_y (integer)
347           * $width (integer)
348           * $height (integer)
349           * $alpha_mode (Gtk2::Gdk::PixbufAlphaMode)
350           * $alpha_threshold (integer)
351           * $dither (Gtk2::Gdk::RgbDither)
352           * $x_dither (integer)
353           * $y_dither (integer)
354
355       pixbuf = $src->rotate_simple ($angle)
356
357           * $angle (Gtk2::Gdk::PixbufRotation)
358
359       integer = $pixbuf->get_rowstride
360
361       $src->saturate_and_pixelate ($dest, $saturation, $pixelate)
362
363           * $dest (Gtk2::Gdk::Pixbuf)
364           * $saturation (double)
365           * $pixelate (boolean)
366
367       $pixbuf->save ($filename, $type, ...)
368
369           * $filename (localized file name)
370           * $type (string) name of file format (e.g. "jpeg", "png")
371           * ... (list) list of key-value save options
372
373           Save $pixbuf to a file named $filename, in the format $type, which
374           is currently "jpeg" or "png".  The function will croak if there is
375           an error, which may arise from file- or image format-related
376           issues.
377
378           Any values in ... should be key/value string pairs that modify the
379           saving parameters.  For example:
380
381            $pixbuf->save ($filename, 'jpeg', quality => '100');
382
383           Currently only a few parameters exist.  JPEG images can be saved
384           with a "quality" parameter; its value should be in the range
385           [0,100].  Text chunks can be attached to PNG images by specifying
386           parameters of the form "tEXt::key", where key is an ASCII string of
387           length 1-79.  The values are UTF-8 encoded strings.  (This is a
388           quote from the C API reference; note that the C API reference is
389           the canonical source for this information.)
390
391           May croak with a Glib::Error in $@ on failure.
392
393       scalar = $pixbuf->save_to_buffer ($type, ...)
394
395           * $type (string) name of file format (e.g. "jpeg", "png")
396           * ... (list) list of key-value save options
397
398           Save $pixbuf to a scalar buffer, in the format $type, which is cur‐
399           rently "jpeg" or "png".  The function will croak if there is an
400           error, which may arise from image format-related issues.
401
402           The returned string contains binary data, which may have embedded
403           nuls.  Don't try to "print" it.
404
405           See "Gtk2::Gdk::Pixbuf::save" for more details.
406
407           May croak with a Glib::Error in $@ on failure.
408
409       $src->scale ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $off‐
410       set_x, $offset_y, $scale_x, $scale_y, $interp_type)
411
412           * $dest (Gtk2::Gdk::Pixbuf)
413           * $dest_x (integer)
414           * $dest_y (integer)
415           * $dest_width (integer)
416           * $dest_height (integer)
417           * $offset_x (double)
418           * $offset_y (double)
419           * $scale_x (double)
420           * $scale_y (double)
421           * $interp_type (Gtk2::Gdk::InterpType)
422
423       pixbuf = $src->scale_simple ($dest_width, $dest_height, $interp_type)
424
425           * $dest_width (integer)
426           * $dest_height (integer)
427           * $interp_type (Gtk2::Gdk::InterpType)
428
429       integer = $pixbuf->get_width
430

PROPERTIES

432       'bits-per-sample' (integer : readable / writable / construct-only /
433       private)
434           The number of bits per sample
435
436       'colorspace' (Gtk2::Gdk::Colorspace : readable / writable / construct-
437       only / private)
438           The colorspace in which the samples are interpreted
439
440       'has-alpha' (boolean : readable / writable / construct-only / private)
441           Whether the pixbuf has an alpha channel
442
443       'height' (integer : readable / writable / construct-only / private)
444           The number of rows of the pixbuf
445
446       'n-channels' (integer : readable / writable / construct-only / private)
447           The number of samples per pixel
448
449       'pixels' (gpointer : readable / writable / construct-only / private)
450           A pointer to the pixel data of the pixbuf
451
452       'rowstride' (integer : readable / writable / construct-only / private)
453           The number of bytes between the start of a row and the start of the
454           next row
455
456       'width' (integer : readable / writable / construct-only / private)
457           The number of columns of the pixbuf
458

ENUMS AND FLAGS

460       enum Gtk2::Gdk::Colorspace
461
462       * 'rgb' / 'GDK_COLORSPACE_RGB'
463
464       enum Gtk2::Gdk::InterpType
465
466       * 'nearest' / 'GDK_INTERP_NEAREST'
467       * 'tiles' / 'GDK_INTERP_TILES'
468       * 'bilinear' / 'GDK_INTERP_BILINEAR'
469       * 'hyper' / 'GDK_INTERP_HYPER'
470
471       enum Gtk2::Gdk::PixbufAlphaMode
472
473       * 'bilevel' / 'GDK_PIXBUF_ALPHA_BILEVEL'
474       * 'full' / 'GDK_PIXBUF_ALPHA_FULL'
475
476       enum Gtk2::Gdk::PixbufError
477
478       * 'corrupt-image' / 'GDK_PIXBUF_ERROR_CORRUPT_IMAGE'
479       * 'insufficient-memory' / 'GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY'
480       * 'bad-option' / 'GDK_PIXBUF_ERROR_BAD_OPTION'
481       * 'unknown-type' / 'GDK_PIXBUF_ERROR_UNKNOWN_TYPE'
482       * 'unsupported-operation' / 'GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION'
483       * 'failed' / 'GDK_PIXBUF_ERROR_FAILED'
484
485       enum Gtk2::Gdk::PixbufRotation
486
487       * 'none' / 'GDK_PIXBUF_ROTATE_NONE'
488       * 'counterclockwise' / 'GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE'
489       * 'upsidedown' / 'GDK_PIXBUF_ROTATE_UPSIDEDOWN'
490       * 'clockwise' / 'GDK_PIXBUF_ROTATE_CLOCKWISE'
491
492       enum Gtk2::Gdk::RgbDither
493
494       * 'none' / 'GDK_RGB_DITHER_NONE'
495       * 'normal' / 'GDK_RGB_DITHER_NORMAL'
496       * 'max' / 'GDK_RGB_DITHER_MAX'
497

COPYRIGHT

502       Copyright (C) 2003-2007 by the gtk2-perl team.
503
504       This software is licensed under the LGPL.  See Gtk2 for a full notice.
505
506
507
508perl v5.8.8                       2007-03-18              Gtk2::Gdk::Pixbuf(3)

NAME

HIERARCHY

METHODS

PROPERTIES

ENUMS AND FLAGS

SEE ALSO

COPYRIGHT