Gtk2::Gdk::Pixbuf(3)

πŸ“¦
version 1.24993 Β· 2 versions
, in fedora 43

🌈 Gtk2::Gdk::Pixbuf 🌈

hiii bestie πŸ’– welcome to the manual page for Gtk2::Gdk::Pixbuf, coming at you straight from the User Contributed Perl Documentation (that's the manual name, we're being ✨fancy✨ about it). this whole thing is a wrapper for GdkPixbuf. the (3) at the end just means it's a library page, don't even worry about it πŸŽ€


🌸 NAME 🌸

Gtk2::Gdk::Pixbuf β€” it's a wrapper for GdkPixbuf, periodt. that's the whole name. short, iconic, does exactly what it says on the tin πŸ‘‘


πŸ¦‹ HIERARCHY πŸ¦‹

okay so the family tree is giving nepo baby, here's the lineage:

Glib::Object
+----Gtk2::Gdk::Pixbuf

your pixbuf is a Glib::Object at heart β€” it inherits all that object-y goodness. slay ✨


🧚 INTERFACES 🧚

it also implements these interfaces, which are basically extra vibes it signed up for:

Glib::Object::_Unregistered::GIcon
Glib::Object::_Unregistered::GLoadableIcon

πŸ’… METHODS πŸ’…

okay this is the main event, every single method. buckle up bestie, there's a LOT and they all matter. we do not skip here πŸ”₯


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new ($colorspace, $has_alpha, $bits_per_sample, $width, $height)

the constructor, the moment, the birth of a pixbuf. it takes:

  • $colorspace β€” a Gtk2::Gdk::Colorspace, i.e. which color space you're living in
  • $has_alpha β€” boolean, are we doing transparency or not
  • $bits_per_sample β€” integer
  • $width β€” integer
  • $height β€” integer

πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_data ($data, $colorspace, $has_alpha, $bits_per_sample, $width, $height, $rowstride)

  • $data (scalar) β€” packed binary pixel data, usually made with pack()
  • $colorspace (Gtk2::Gdk::Colorspace)
  • $has_alpha (boolean) β€” true if the image data includes an alpha channel (that's your opacity info bestie)
  • $bits_per_sample (integer)
  • $width (integer) β€” in pixels
  • $height (integer) β€” in pixels
  • $rowstride (integer) β€” the distance in bytes between row starts; usually 3*width for rgb data, or 4*width if $has_alpha is true

this one creates a new Gtk2::Gdk::Pixbuf out of in-memory image data. currently only RGB images with 8 bits per sample are supported β€” so don't come at it with anything else, it will not play.

in C, this function lets you wrap a GdkPixbuf structure around existing pixel data. in Perl though? you have to use pack to generate a scalar with the pixel data, then pass that scalar to new_from_data, which copies the scalar to keep it around. it also handles the memory automagically, so you don't need a destruction notifier function β€” no cap. this all means that if you change your copy of the data scalar later, the pixbuf will not reflect that. but honestly, given the way perl manages string data and scalars, doing that in the first place would be pretty fragile anyway. if you need to modify a pixbuf's data after it's created, you can make new pixbufs for the changed regions and use $pixbuf->composite, or try a totally different approach (maybe a server-side pixmap and gdk drawing primitives, or something like libart) πŸ’«


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename)

  • $filename (localized file name)
⚠️ may croak with a Glib::Error in $@ on failure. so wrap it in an eval, bestie πŸ™ˆ

πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_file_at_scale ($filename, $width, $height, $preserve_aspect_ratio)

  • $filename (localized file name)
  • $width (integer)
  • $height (integer)
  • $preserve_aspect_ratio (boolean)
⚠️ may croak with a Glib::Error in $@ on failure.

since: gtk+ 2.6 ✨


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_file_at_size ($filename, $width, $height)

  • $filename (localized file name)
  • $width (integer)
  • $height (integer)
⚠️ may croak with a Glib::Error in $@ on failure.

since: gtk+ 2.4 ✨


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_inline ($data, $copy_pixels=TRUE)

  • $data (scalar) β€” packed binary data, the format is special, see the discussion
  • $copy_pixels (boolean) β€” whether $data should be copied, defaults to true

okay so gtk+ ships with a tool called gdk-pixbuf-csource, which turns any image gdk-pixbuf understands into the C syntax of the declaration of a static data structure containing that image data, so you can #include it directly into your source code. gdk_pixbuf_new_from_inline creates a new GdkPixbuf from that data structure.

now here's the tea β˜•: currently, this is not very easy to do from Perl. the output of gdk-pixbuf-csource must be mangled rather ruthlessly to create valid Perl code using pack and translation from C string escapes to valid Perl string escapes (encoding and interpretation issues, ugh). and because Perl scalars are garbage collected, it's rather rare to have the ability to use static data β€” which is exactly why $copy_pixels defaults to true. if you can guarantee the image data will outlive the pixbuf, you can pass false here and save some memory πŸ‘€

for more information, see the description of gdk_pixbuf_new_from_inline in the C API reference at http://gtk.org/api/ .

⚠️ may croak with a Glib::Error in $@ on failure.

πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->new_from_xpm_data (...)

  • ... (list) β€” xpm data as a list of strings (see the discussion)

X Pixel Map (XPM) files are designed to be easy to edit and easy to include directly into C programs. the file format is the C syntax of the declaration and initialization of a variable containing an array of strings. new_from_xpm_data lets you create an image from such data included right there in your program source. cute, right? πŸŽ€

but since XPM files are C syntax, you have to mangle that source a bit to make it work in a Perl program. for example, this is a valid xpm, but it is not valid Perl code:

/* XPM */
static char * test_xpm[] = {
"4 4 3 1",
"      c None",
".     c red",
"+     c blue",
".. +",
". ++",
" ++.",
"++.."};

you'll need to change the array declaration format, and switch the double-quoted strings to single-quoted ones so Perl doesn't interpret any chars in the strings as special. like this:

my @test_xpm = (
'4 4 3 1',
'      c None',
'.     c red',
'+     c blue',
'.. +',
'. ++',
' ++.',
'++..');

$pixbuf = Gtk2::Gdk::Pixbuf->new_from_xpm_data (@test_xpm);

[side note, straight from the original and not from me: it's only two or three regexes... Perhaps we should distribute a script to convert XPM files to the proper format?] πŸ€”


πŸ“ pixbuf = $src_pixbuf->new_subpixbuf ($src_x, $src_y, $width, $height)

  • $src_x (integer)
  • $src_y (integer)
  • $width (integer)
  • $height (integer)

πŸ“ pixbuf = $pixbuf->add_alpha ($substitute_color, $r, $g, $b)

  • $substitute_color (boolean)
  • $r (Glib::UChar)
  • $g (Glib::UChar)
  • $b (Glib::UChar)

πŸ“ pixbuf = $src->apply_embedded_orientation

since: gtk+ 2.11 ✨


πŸ“ integer = $pixbuf->get_bits_per_sample


πŸ“ colorspace = $pixbuf->get_colorspace


πŸ“ $src->composite ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type, $overall_alpha)

  • $dest (Gtk2::Gdk::Pixbuf)
  • $dest_x (integer)
  • $dest_y (integer)
  • $dest_width (integer)
  • $dest_height (integer)
  • $offset_x (double)
  • $offset_y (double)
  • $scale_x (double)
  • $scale_y (double)
  • $interp_type (Gtk2::Gdk::InterpType)
  • $overall_alpha (integer)

πŸ“ $src->composite_color ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type, $overall_alpha, $check_x, $check_y, $check_size, $color1, $color2)

  • $dest (Gtk2::Gdk::Pixbuf)
  • $dest_x (integer)
  • $dest_y (integer)
  • $dest_width (integer)
  • $dest_height (integer)
  • $offset_x (double)
  • $offset_y (double)
  • $scale_x (double)
  • $scale_y (double)
  • $interp_type (Gtk2::Gdk::InterpType)
  • $overall_alpha (integer)
  • $check_x (integer)
  • $check_y (integer)
  • $check_size (integer)
  • $color1 (unsigned)
  • $color2 (unsigned)

πŸ“ pixbuf or undef = $src->composite_color_simple ($dest_width, $dest_height, $interp_type, $overall_alpha, $check_size, $color1, $color2)

  • $dest_width (integer)
  • $dest_height (integer)
  • $interp_type (Gtk2::Gdk::InterpType)
  • $overall_alpha (integer)
  • $check_size (integer)
  • $color1 (unsigned)
  • $color2 (unsigned)

πŸ“ pixbuf = $pixbuf->copy


πŸ“ $src_pixbuf->copy_area ($src_x, $src_y, $width, $height, $dest_pixbuf, $dest_x, $dest_y)

  • $src_x (integer)
  • $src_y (integer)
  • $width (integer)
  • $height (integer)
  • $dest_pixbuf (Gtk2::Gdk::Pixbuf)
  • $dest_x (integer)
  • $dest_y (integer)

πŸ“ (format, width, height) = $pixbuf->get_file_info ($filename)

  • $filename (localized file name)

this one parses enough of $filename to figure out and return the format and size. if the format is unknown or the file can't be opened, it returns an empty list. so like, check your return value bestie πŸ™ˆ

since: gtk+ 2.4 ✨


πŸ“ $pixbuf->fill ($pixel)

  • $pixel (unsigned) β€” a packed RGBA value

this clears $pixbuf so it contains only the value given in $pixel. clean slate energy, we love to see it ✨


πŸ“ pixbuf = $src->flip ($horizontal)

  • $horizontal (boolean)

since: gtk+ 2.6 ✨


πŸ“ list = Gtk2::Gdk::Pixbuf->get_formats

returns a list of hashes with information about the formats supported by Gtk2::Gdk::Pixbuf.

since: gtk+ 2.2 ✨


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->get_from_drawable ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

πŸ“ pixbuf = $pixbuf->get_from_drawable ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

  • $src (Gtk2::Gdk::Drawable)
  • $cmap (Gtk2::Gdk::Colormap or undef)
  • $src_x (integer)
  • $src_y (integer)
  • $dest_x (integer)
  • $dest_y (integer)
  • $width (integer)
  • $height (integer)

this fetches pixels from a Gtk2::Gdk::Drawable as a Gtk2::Gdk::Pixbuf. it returns a new Gtk2::Gdk::Pixbuf if you use the class form, or $pixbuf if you call it on an existing pixbuf. pick your fighter πŸ’…


πŸ“ pixbuf = Gtk2::Gdk::Pixbuf->get_from_image ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

πŸ“ pixbuf = $pixbuf->get_from_image ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

  • $src (Gtk2::Gdk::Image)
  • $cmap (Gtk2::Gdk::Colormap or undef)
  • $src_x (integer)
  • $src_y (integer)
  • $dest_x (integer)
  • $dest_y (integer)
  • $width (integer)
  • $height (integer)

fetches pixels from a Gtk2::Gdk::Image as a Gtk2::Gdk::Pixbuf. returns a new Gtk2::Gdk::Pixbuf if you use the class form, or $pixbuf if you call it on an existing pixbuf. same deal as the drawable one, just with an Image instead πŸ–ΌοΈ


πŸ“ boolean = $pixbuf->get_has_alpha


πŸ“ integer = $pixbuf->get_height


πŸ“ integer = $pixbuf->get_n_channels


πŸ“ string or undef = $pixbuf->get_option ($key)

  • $key (string)

πŸ“ boolean = $pixbuf->set_option ($key, $value)

  • $key (string)
  • $value (string)

since: gtk+ 2.2 ✨


πŸ“ scalar = $pixbuf->get_pixels

returns a copy of the bytes that make up the pixel data of $pixbuf.

as described in the Gdk Pixbuf reference manual (specifically the "Note" section of "The GdkPixbuf Structure"), the last row does not extend all the way to the rowstride β€” it ends with the last byte of the last pixel. the length of the get_pixels return reflects that πŸ“


πŸ“ pixmap = $pixbuf->render_pixmap_and_mask ($alpha_threshold)

πŸ“ (pixmap, mask) = $pixbuf->render_pixmap_and_mask ($alpha_threshold)

  • $alpha_threshold (integer)

πŸ“ pixmap = $pixbuf->render_pixmap_and_mask_for_colormap ($colormap, $alpha_threshold)

πŸ“ (pixmap, mask) = $pixbuf->render_pixmap_and_mask_for_colormap ($colormap, $alpha_threshold)

  • $colormap (Gtk2::Gdk::Colormap)
  • $alpha_threshold (integer)
  • $pixbuf->render_threshold_alpha ($bitmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $alpha_threshold) β€” okay so here's the signature, and the args are giving:
    • $bitmap (Gtk2::Gdk::Bitmap)
    • $src_x (integer)
    • $src_y (integer)
    • $dest_x (integer)
    • $dest_y (integer)
    • $width (integer)
    • $height (integer)
    • $alpha_threshold (integer)
  • $pixbuf->render_to_drawable ($drawable, $gc, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $dither, $x_dither, $y_dither) β€” render_to_drawable has entered the chat, and it wants:
    • $drawable (Gtk2::Gdk::Drawable)
    • $gc (Gtk2::Gdk::GC)
    • $src_x (integer)
    • $src_y (integer)
    • $dest_x (integer)
    • $dest_y (integer)
    • $width (integer)
    • $height (integer)
    • $dither (Gtk2::Gdk::RgbDither)
    • $x_dither (integer)
    • $y_dither (integer)
  • $pixbuf->render_to_drawable_alpha ($drawable, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $alpha_mode, $alpha_threshold, $dither, $x_dither, $y_dither) β€” the alpha version of that whole situation, with:
    • $drawable (Gtk2::Gdk::Drawable)
    • $src_x (integer)
    • $src_y (integer)
    • $dest_x (integer)
    • $dest_y (integer)
    • $width (integer)
    • $height (integer)
    • $alpha_mode (Gtk2::Gdk::PixbufAlphaMode)
    • $alpha_threshold (integer)
    • $dither (Gtk2::Gdk::RgbDither)
    • $x_dither (integer)
    • $y_dither (integer)
  • pixbuf = $src->rotate_simple ($angle) β€” rotate it, bestie. Takes:
    • $angle (Gtk2::Gdk::PixbufRotation)

Since: gtk+ 2.6

  • integer = $pixbuf->get_rowstride β€” just hands you the rowstride integer, no args, no drama.
  • $src->saturate_and_pixelate ($dest, $saturation, $pixelate) β€” saturate and pixelate time. The args:
    • $dest (Gtk2::Gdk::Pixbuf)
    • $saturation (double)
    • $pixelate (boolean)
  • $pixbuf->save ($filename, $type, ...) β€” save it to a file, iconic. The args:
    • $filename (localized file name)
    • $type (string) name of file format (e.g. "jpeg", "png")
    • ... (list) list of key-value save options

Save $pixbuf to a file named $filename, in the format $type, which is currently "jpeg" or "png". The function will croak if there is an error, which may arise from file- or image format-related issues.

Any values in ... should be key/value string pairs that modify the saving parameters. For example:

$pixbuf->save ($filename, 'jpeg', quality => '100');

Currently only a few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. (This is a quote from the C API reference; note that the C API reference is the canonical source for this information.)

May croak with a Glib::Error in $@ on failure.

  • scalar = $pixbuf->save_to_buffer ($type, ...) β€” save to a buffer instead. Args:
    • $type (string) name of file format (e.g. "jpeg", "png")
    • ... (list) list of key-value save options

Save $pixbuf to a scalar buffer, in the format $type, which is currently "jpeg" or "png". The function will croak if there is an error, which may arise from image format-related issues.

The returned string contains binary data, which may have embedded nuls. Don't try to "print" it.

See "Gtk2::Gdk::Pixbuf::save" for more details.

May croak with a Glib::Error in $@ on failure.

Since: gtk+ 2.4

  • $src->scale ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type) β€” scale it, periodt. Args:
    • $dest (Gtk2::Gdk::Pixbuf)
    • $dest_x (integer)
    • $dest_y (integer)
    • $dest_width (integer)
    • $dest_height (integer)
    • $offset_x (double)
    • $offset_y (double)
    • $scale_x (double)
    • $scale_y (double)
    • $interp_type (Gtk2::Gdk::InterpType)
  • pixbuf or undef = $src->scale_simple ($dest_width, $dest_height, $interp_type) β€” the simple scale, giving pixbuf or undef. Args:
    • $dest_width (integer)
    • $dest_height (integer)
    • $interp_type (Gtk2::Gdk::InterpType)
  • integer = $pixbuf->get_width β€” returns the width integer, that's it.

✨ PROPERTIES ✨

  • 'bits-per-sample' (integer : default 8 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The number of bits per sample
  • 'colorspace' (Gtk2::Gdk::Colorspace : default "rgb" : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The colorspace in which the samples are interpreted
  • 'has-alpha' (boolean : default false : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” Whether the pixbuf has an alpha channel
  • 'height' (integer : default 1 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The number of rows of the pixbuf
  • 'n-channels' (integer : default 3 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The number of samples per pixel
  • 'pixel-bytes' (Glib::Bytes : default undef : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” Readonly pixel data
  • 'pixels' (gpointer : default 0 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” A pointer to the pixel data of the pixbuf
  • 'rowstride' (integer : default 1 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The number of bytes between the start of a row and the start of the next row
  • 'width' (integer : default 1 : readable / writable / construct-only / private / static-nick / static-blurb / explicit-notify) β€” The number of columns of the pixbuf

🌈 ENUMS AND FLAGS 🌈

enum Gtk2::Gdk::Colorspace

  • 'rgb' / 'GDK_COLORSPACE_RGB'

enum Gtk2::Gdk::InterpType

  • 'nearest' / 'GDK_INTERP_NEAREST'
  • 'tiles' / 'GDK_INTERP_TILES'
  • 'bilinear' / 'GDK_INTERP_BILINEAR'
  • 'hyper' / 'GDK_INTERP_HYPER'

enum Gtk2::Gdk::PixbufAlphaMode

  • 'bilevel' / 'GDK_PIXBUF_ALPHA_BILEVEL'
  • 'full' / 'GDK_PIXBUF_ALPHA_FULL'

enum Gtk2::Gdk::PixbufError

  • 'corrupt-image' / 'GDK_PIXBUF_ERROR_CORRUPT_IMAGE'
  • 'insufficient-memory' / 'GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY'
  • 'bad-option' / 'GDK_PIXBUF_ERROR_BAD_OPTION'
  • 'unknown-type' / 'GDK_PIXBUF_ERROR_UNKNOWN_TYPE'
  • 'unsupported-operation' / 'GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION'
  • 'failed' / 'GDK_PIXBUF_ERROR_FAILED'
  • 'incomplete-animation' / 'GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION'

enum Gtk2::Gdk::PixbufRotation

  • 'none' / 'GDK_PIXBUF_ROTATE_NONE'
  • 'counterclockwise' / 'GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE'
  • 'upsidedown' / 'GDK_PIXBUF_ROTATE_UPSIDEDOWN'
  • 'clockwise' / 'GDK_PIXBUF_ROTATE_CLOCKWISE'

enum Gtk2::Gdk::RgbDither

  • 'none' / 'GDK_RGB_DITHER_NONE'
  • 'normal' / 'GDK_RGB_DITHER_NORMAL'
  • 'max' / 'GDK_RGB_DITHER_MAX'

πŸ‘€ SEE ALSO πŸ‘€

  • Gtk2, Glib::Object

Copyright (C) 2003-2011 by the gtk2-perl team.

This software is licensed under the LGPL. See Gtk2 for a full notice.

And that's a wrap, bestie. This page is from perl v5.42.0, dated 2025-07-25, and it's Gtk2::Gdk::Pixbuf(3). πŸ’…βœ¨πŸ«Ά
πŸ“¦ where this page comes from