Gtk2::Gdk::Pixbuf(3pm)

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

NAME

6       Gtk2::Gdk::Pixbuf - wrapper for GdkPixbuf
7

HIERARCHY

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

INTERFACES

13         Glib::Object::_Unregistered::GIcon
14         Glib::Object::_Unregistered::GLoadableIcon
15

METHODS

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

PROPERTIES

545       'bits-per-sample' (integer : default 8 : readable / writable /
546       construct-only / private / static-nick / static-blurb / explicit-
547       notify)
548           The number of bits per sample
549
550       'colorspace' (Gtk2::Gdk::Colorspace : default "rgb" : readable /
551       writable / construct-only / private / static-nick / static-blurb /
552       explicit-notify)
553           The colorspace in which the samples are interpreted
554
555       'has-alpha' (boolean : default false : readable / writable / construct-
556       only / private / static-nick / static-blurb / explicit-notify)
557           Whether the pixbuf has an alpha channel
558
559       'height' (integer : default 1 : readable / writable / construct-only /
560       private / static-nick / static-blurb / explicit-notify)
561           The number of rows of the pixbuf
562
563       'n-channels' (integer : default 3 : readable / writable / construct-
564       only / private / static-nick / static-blurb / explicit-notify)
565           The number of samples per pixel
566
567       'pixel-bytes' (Glib::Bytes : default undef : readable / writable /
568       construct-only / private / static-nick / static-blurb / explicit-
569       notify)
570           Readonly pixel data
571
572       'pixels' (gpointer : default 0 : readable / writable / construct-only /
573       private / static-nick / static-blurb / explicit-notify)
574           A pointer to the pixel data of the pixbuf
575
576       'rowstride' (integer : default 1 : readable / writable / construct-only
577       / private / static-nick / static-blurb / explicit-notify)
578           The number of bytes between the start of a row and the start of the
579           next row
580
581       'width' (integer : default 1 : readable / writable / construct-only /
582       private / static-nick / static-blurb / explicit-notify)
583           The number of columns of the pixbuf
584

ENUMS AND FLAGS

586   enum Gtk2::Gdk::Colorspace
587       •   'rgb' / 'GDK_COLORSPACE_RGB'
588
589   enum Gtk2::Gdk::InterpType
590       •   'nearest' / 'GDK_INTERP_NEAREST'
591
592       •   'tiles' / 'GDK_INTERP_TILES'
593
594       •   'bilinear' / 'GDK_INTERP_BILINEAR'
595
596       •   'hyper' / 'GDK_INTERP_HYPER'
597
598   enum Gtk2::Gdk::PixbufAlphaMode
599       •   'bilevel' / 'GDK_PIXBUF_ALPHA_BILEVEL'
600
601       •   'full' / 'GDK_PIXBUF_ALPHA_FULL'
602
603   enum Gtk2::Gdk::PixbufError
604       •   'corrupt-image' / 'GDK_PIXBUF_ERROR_CORRUPT_IMAGE'
605
606       •   'insufficient-memory' / 'GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY'
607
608       •   'bad-option' / 'GDK_PIXBUF_ERROR_BAD_OPTION'
609
610       •   'unknown-type' / 'GDK_PIXBUF_ERROR_UNKNOWN_TYPE'
611
612       •   'unsupported-operation' / 'GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION'
613
614       •   'failed' / 'GDK_PIXBUF_ERROR_FAILED'
615
616       •   'incomplete-animation' / 'GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION'
617
618   enum Gtk2::Gdk::PixbufRotation
619       •   'none' / 'GDK_PIXBUF_ROTATE_NONE'
620
621       •   'counterclockwise' / 'GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE'
622
623       •   'upsidedown' / 'GDK_PIXBUF_ROTATE_UPSIDEDOWN'
624
625       •   'clockwise' / 'GDK_PIXBUF_ROTATE_CLOCKWISE'
626
627   enum Gtk2::Gdk::RgbDither
628       •   'none' / 'GDK_RGB_DITHER_NONE'
629
630       •   'normal' / 'GDK_RGB_DITHER_NORMAL'
631
632       •   'max' / 'GDK_RGB_DITHER_MAX'
633

COPYRIGHT

638       Copyright (C) 2003-2011 by the gtk2-perl team.
639
640       This software is licensed under the LGPL.  See Gtk2 for a full notice.
641
642
643
644perl v5.34.0                      2021-07-22              Gtk2::Gdk::Pixbuf(3)