NAME

Gtk2::Ex::PixbufBits -- misc Gtk2::Gdk::Pixbuf helpers

SYNOPSIS

 use Gtk2::Ex::PixbufBits;

FUNCTIONS

Saving

Gtk2::Ex::PixbufBits::save_adapt ($pixbuf, $filename, $type, key => value, ...)

($filename, $type, ...) = Gtk2::Ex::PixbufBits::save_adapt_options ($pixbuf, $filename, $type, key => value, ...)

save_adapt() saves a Gtk2::Gdk::Pixbuf with various options adapted for the target $type and the options supported by the Gtk in use. $type is a string per $pixbuf->save, such as "png" or "jpeg".

save_adapt_options() adapts options and returns them without saving. The return can be passed to a $pixbuf->save,

    $pixbuf->save (save_adapt_options($pixbuf, $filename, $type,
                                      zlib_compression => 4));

The idea is to give a full set of options and have them automatically reduced if not applicable to the $type or not available in the Gtk version. For example the compression option must be set differently for PNG or for TIFF. The two separate compression options here are used according to the $type.

zlib_compression (integer 0 to 9 or -1)

A Zlib style compression level. For $type "png" and Gtk 2.8 up this becomes the compression option.

tiff_compression_type (integer, or names "none", "huffman", "lzw", "jpeg" or "deflate")

A TIFF compression method. For $type "tiff" and Gtk 2.20 up this becomes the compression option. String names "deflate" etc are converted to the corresponding integer value.

quality_percent (0 to 100)

An image quality percentage for lossy formats such as JPEG. For $type "jpeg" this becomes the quality option.

tEXt:foo (string)

A PNG style keyword string. For $type "png" and Gtk 2.8 up this is passed through as tEXt, with a utf8::upgrade if necessary for Gtk2-Perl 1.221.

These tEXt options are moved to before any compression option as a workaround for a Gtk bug where if tEXt is after compression then wrong text strings are written.

x_hot, y_hot (integer or undef)

The cursor hotspot position for $type "ico". undef means no hotspot. The default is the pixbuf get_option x_hot,y_hot which is set when reading an ICO or XPM file.

XPM is not writable as of Gtk 2.22 but if it becomes writable then perhaps its hotspot could be set from these options too.

For example

    Gtk2::Ex::PixbufBits::save_adapt
      ($pixbuf,             # Gtk2::Gdk::Pixbuf object
       $users_filename,     # eg. string "/tmp/foo"
       $users_type,         # eg. string "png"
       zlib_compression      => 9,
       quality_percent       => 100,
       tiff_compression_type => "deflate",
       tEXt:Author           => "Yorick");

Colours

$str = Gtk2::Ex::PixbufBits::sampled_majority_color($pixbuf)

Return a string which is the apparent majority colour in $pixbuf, established by sampling some pixels at random. For an 8-bit RGB pixbuf the return is a string like "#FF00FF".

This function only makes sense for images which have a particular dominant background (or foreground) colour, it's no good if there's lots of shades of grey etc.

The current code only supports 8-bit RGB or RGBA data formats, which is all GdkPixbuf itself supports as of Gtk 2.22. Transparent pixels (alpha channel zero) are ignored.

The idea of sampling pixels at random is to avoid a fixed sampling algorithm hitting a grid or pattern in the image which is not the majority colour. For small images all pixels are checked (currently anything up to 1800 pixels).

Type Info

($width, $height) = Gtk2::Ex::PixbufBits::type_max_size ($type)

$bool = Gtk2::Ex::PixbufBits::type_supports_size ($type, $width, $height)

type_max_size() returns the maximum which file format $type supports, or no values if there's no maximum known. type_supports_size() returns true if the given size is supported by $type (and true if unknown too).

The maximum sizes are

    png       2**31-1 x 2**31-1
    jpeg      65500x65500
    tiff      2**32-1 x 2**32-1
    bmp       2**31-1 x 2**31-1
    ico       255x255

The PNG spec allows 2^31-1 and that's given here, but libpng (in png_check_IHDR()) restricts the width to 2^29-130 (RGBA row in 32-bit malloced block), and also has compiled-in PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX defaulting to 1,000,000. Might try to include those limits here, if they can be identified reliably.

$format = Gtk2::Ex::PixbufBits::type_to_format ($type)

Return a Gtk2::Gdk::PixbufFormat object for the given $type string. $type is the format name, such as "png", "jpeg", etc (lower case). If $type is unknown then return undef.

Gtk2::Gdk::PixbufFormat is new in Gtk 2.2. It's unspecified yet what this function does in Gtk 2.0.x.

EXPORTS

Nothing is exported by default, but all functions can be requested in usual Exporter style,

    use Gtk2::Ex::PixbufBits 'save_adapt';
    save_adapt ($pixbuf, $filename, $type,
                'tEXt::Title' => 'Picture of Matchstick Men');

There's no :all tag since this module is meant as a grab-bag of functions and to import as-yet unknown things would be asking for name clashes.

SEE ALSO

Gtk2::Gdk::Pixbuf, Gtk2::Ex::WidgetBits, Gtk2::Ex::ComboBox::PixbufType

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-widgetbits/index.html

LICENSE

Copyright 2007, 2008, 2009, 2010, 2011, 2012 Kevin Ryde

Gtk2-Ex-WidgetBits is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-WidgetBits is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-WidgetBits. If not, see http://www.gnu.org/licenses/.