libgtk2-perl-doc 2:1.2498-1 / usr / share / perl5 / Gtk2 / Gdk / Pixbuf.pod

=head1 NAME

Gtk2::Gdk::Pixbuf - wrapper for GdkPixbuf

=cut

=head1 HIERARCHY

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



=cut

=head1 INTERFACES

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



=cut


=head1 METHODS

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new> ($colorspace, $has_alpha, $bits_per_sample, $width, $height)

=over

=item * $colorspace (Gtk2::Gdk::Colorspace) 

=item * $has_alpha (boolean) 

=item * $bits_per_sample (integer) 

=item * $width (integer) 

=item * $height (integer) 

=back

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_data> ($data, $colorspace, $has_alpha, $bits_per_sample, $width, $height, $rowstride)

=over

=item * $data (scalar) packed binary pixel data, usually made with pack()

=item * $colorspace (Gtk2::Gdk::Colorspace) 

=item * $has_alpha (boolean) true if the image data includes an alpha channel (opacity information).

=item * $bits_per_sample (integer) 

=item * $width (integer) in pixels.

=item * $height (integer) in pixels.

=item * $rowstride (integer) distance in bytes between row starts; usually 3*width for rgb data, 4*width if I<$has_alpha> is true.

=back


Creates a new Gtk2::Gdk::Pixbuf out of in-memory image data.  Currently only
RGB images with 8 bits per sample are supported.

In C this function allows you to wrap a GdkPixbuf structure around existing
pixel data.  In Perl, we have to use C<pack> to generate a scalar containing
the pixel data, and pass that scalar to C<new_from_data>, which copies the
scalar to keep it around.  It also manages the memory automagically, so there's
no need for a destruction notifier function.  This all means that if you change
your copy of the data scalar later, the pixbuf will I<not> reflect that, but
because of the way perl manages string data and scalars, it would be pretty
fragile to do that in the first place.  If you need to modify a pixbuf's data
after it has been created, you can create new pixbufs for the changed regions
and use C<< $pixbuf->composite >>, or try a different approach (possibly use a
server-side pixmap and gdk drawing primitives, or something like libart).


=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_file> ($filename)

=over

=item * $filename (localized file name) 

=back



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

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_file_at_scale> ($filename, $width, $height, $preserve_aspect_ratio)

=over

=item * $filename (localized file name) 

=item * $width (integer) 

=item * $height (integer) 

=item * $preserve_aspect_ratio (boolean) 

=back



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

Since: gtk+ 2.6

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_file_at_size> ($filename, $width, $height)

=over

=item * $filename (localized file name) 

=item * $width (integer) 

=item * $height (integer) 

=back



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

Since: gtk+ 2.4

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_inline> ($data, $copy_pixels=TRUE)

=over

=item * $data (scalar) packed binary data, the format is special, see discussion

=item * $copy_pixels (boolean) whether I<$data> should be copied, defaults to true

=back


Gtk+ ships with a tool called C<gdk-pixbuf-csource>, which turns any image
understood by gdk-pixbuf into the C syntax of the declaration of a static
data structure containing that image data, to be #included directly into
your source code.  C<gdk_pixbuf_new_from_inline> creates a new GdkPixbuf
from that data structure.

Currently, this is not very easy to do from Perl.  The output of
C<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 (for encoding and interpretation isses).  Because Perl
scalars are garbage collected, it's rather rare to have the ability to use
static data, so I<$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 C<gdk_pixbuf_new_from_inline>
in the C API reference at http://gtk.org/api/ .

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

=head2 pixbuf = Gtk2::Gdk::Pixbuf-E<gt>B<new_from_xpm_data> (...)

=over

=item * ... (list) xpm data as a list of strings (see discussion)

=back

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.
C<new_from_xpm_data> allows you to create an image from such data included
directly in your program source.

Since XPM files are C syntax, you must mangle that source a bit to 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 change the
double-quoted strings to single-quoted to avoid Perl interpreting
any chars in the strings as special.

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

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

[It's only two or three regexes... Perhaps we should distribute a script
to convert XPM files to the proper format?]

=head2 pixbuf = $src_pixbuf-E<gt>B<new_subpixbuf> ($src_x, $src_y, $width, $height)

=over

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=back

=head2 pixbuf = $pixbuf-E<gt>B<add_alpha> ($substitute_color, $r, $g, $b)

=over

=item * $substitute_color (boolean) 

=item * $r (Glib::UChar) 

=item * $g (Glib::UChar) 

=item * $b (Glib::UChar) 

=back

=head2 pixbuf = $src-E<gt>B<apply_embedded_orientation> 

Since: gtk+ 2.11

=head2 integer = $pixbuf-E<gt>B<get_bits_per_sample> 

=head2 colorspace = $pixbuf-E<gt>B<get_colorspace> 

=head2 $src-E<gt>B<composite> ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type, $overall_alpha)

=over

=item * $dest (Gtk2::Gdk::Pixbuf) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $dest_width (integer) 

=item * $dest_height (integer) 

=item * $offset_x (double) 

=item * $offset_y (double) 

=item * $scale_x (double) 

=item * $scale_y (double) 

=item * $interp_type (Gtk2::Gdk::InterpType) 

=item * $overall_alpha (integer) 

=back

=head2 $src-E<gt>B<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)

=over

=item * $dest (Gtk2::Gdk::Pixbuf) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $dest_width (integer) 

=item * $dest_height (integer) 

=item * $offset_x (double) 

=item * $offset_y (double) 

=item * $scale_x (double) 

=item * $scale_y (double) 

=item * $interp_type (Gtk2::Gdk::InterpType) 

=item * $overall_alpha (integer) 

=item * $check_x (integer) 

=item * $check_y (integer) 

=item * $check_size (integer) 

=item * $color1 (unsigned) 

=item * $color2 (unsigned) 

=back

=head2 pixbuf or undef = $src-E<gt>B<composite_color_simple> ($dest_width, $dest_height, $interp_type, $overall_alpha, $check_size, $color1, $color2)

=over

=item * $dest_width (integer) 

=item * $dest_height (integer) 

=item * $interp_type (Gtk2::Gdk::InterpType) 

=item * $overall_alpha (integer) 

=item * $check_size (integer) 

=item * $color1 (unsigned) 

=item * $color2 (unsigned) 

=back

=head2 pixbuf = $pixbuf-E<gt>B<copy> 

=head2 $src_pixbuf-E<gt>B<copy_area> ($src_x, $src_y, $width, $height, $dest_pixbuf, $dest_x, $dest_y)

=over

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=item * $dest_pixbuf (Gtk2::Gdk::Pixbuf) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=back

=head2 (format, width, height) = $pixbuf->B<get_file_info> ($filename)

=over

=item * $filename (localized file name) 

=back


Parses enough of I<$filename> to determine and return the format and size.
If the format is unknown or the file can't be opened, returns an empty list.


Since: gtk+ 2.4

=head2 $pixbuf-E<gt>B<fill> ($pixel)

=over

=item * $pixel (unsigned) a packed RGBA value.

=back

Clear I<$pixbuf> to contain only the value given in I<$pixel>.

=head2 pixbuf = $src-E<gt>B<flip> ($horizontal)

=over

=item * $horizontal (boolean) 

=back

Since: gtk+ 2.6

=head2 list = Gtk2::Gdk::Pixbuf-E<gt>B<get_formats> 

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

Since: gtk+ 2.2

=head2 pixbuf = Gtk2::Gdk::Pixbuf->B<get_from_drawable> ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

=head2 pixbuf = $pixbuf->B<get_from_drawable> ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

=over

=item * $src (Gtk2::Gdk::Drawable) 

=item * $cmap (Gtk2::Gdk::Colormap or undef) 

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=back

Fetch pixels from a Gtk2::Gdk::Drawable as a Gtk2::Gdk::Pixbuf.
Returns a new Gtk2::Gdk::Pixbuf if you use the class form, or I<$pixbuf> if
you call it on an existing pixbuf.

=head2 pixbuf = Gtk2::Gdk::Pixbuf->B<get_from_image> ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

=head2 pixbuf = $pixbuf->B<get_from_image> ($src, $cmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height)

=over

=item * $src (Gtk2::Gdk::Image) 

=item * $cmap (Gtk2::Gdk::Colormap or undef) 

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=back

Fetch pixels from a Gtk2::Gdk::Image as a Gtk2::Gdk::Pixbuf.
Returns a new Gtk2::Gdk::Pixbuf if you use the class form, or I<$pixbuf> if
you call it on an existing pixbuf.

=head2 boolean = $pixbuf-E<gt>B<get_has_alpha> 

=head2 integer = $pixbuf-E<gt>B<get_height> 

=head2 integer = $pixbuf-E<gt>B<get_n_channels> 

=head2 string or undef = $pixbuf-E<gt>B<get_option> ($key)

=over

=item * $key (string) 

=back

=head2 boolean = $pixbuf-E<gt>B<set_option> ($key, $value)

=over

=item * $key (string) 

=item * $value (string) 

=back

Since: gtk+ 2.2

=head2 scalar = $pixbuf-E<gt>B<get_pixels> 

Return a copy of the bytes comprising the pixel data of C<$pixbuf>.

As described in the Gdk Pixbuf reference manual (the "Note" section of
"The GdkPixbuf Structure"), the last row does not extend to the
rowstride, but ends with the last byte of the last pixel.  The length
of the C<get_pixels> return reflects this.

=head2 pixmap = $pixbuf->B<render_pixmap_and_mask> ($alpha_threshold)

=head2 (pixmap, mask) = $pixbuf->B<render_pixmap_and_mask> ($alpha_threshold)

=over

=item * $alpha_threshold (integer) 

=back



=head2 pixmap = $pixbuf->B<render_pixmap_and_mask_for_colormap> ($colormap, $alpha_threshold)

=head2 (pixmap, mask) = $pixbuf->B<render_pixmap_and_mask_for_colormap> ($colormap, $alpha_threshold)

=over

=item * $colormap (Gtk2::Gdk::Colormap) 

=item * $alpha_threshold (integer) 

=back



=head2 $pixbuf-E<gt>B<render_threshold_alpha> ($bitmap, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $alpha_threshold)

=over

=item * $bitmap (Gtk2::Gdk::Bitmap) 

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=item * $alpha_threshold (integer) 

=back

=head2 $pixbuf-E<gt>B<render_to_drawable> ($drawable, $gc, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $dither, $x_dither, $y_dither)

=over

=item * $drawable (Gtk2::Gdk::Drawable) 

=item * $gc (Gtk2::Gdk::GC) 

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=item * $dither (Gtk2::Gdk::RgbDither) 

=item * $x_dither (integer) 

=item * $y_dither (integer) 

=back

=head2 $pixbuf-E<gt>B<render_to_drawable_alpha> ($drawable, $src_x, $src_y, $dest_x, $dest_y, $width, $height, $alpha_mode, $alpha_threshold, $dither, $x_dither, $y_dither)

=over

=item * $drawable (Gtk2::Gdk::Drawable) 

=item * $src_x (integer) 

=item * $src_y (integer) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $width (integer) 

=item * $height (integer) 

=item * $alpha_mode (Gtk2::Gdk::PixbufAlphaMode) 

=item * $alpha_threshold (integer) 

=item * $dither (Gtk2::Gdk::RgbDither) 

=item * $x_dither (integer) 

=item * $y_dither (integer) 

=back

=head2 pixbuf = $src-E<gt>B<rotate_simple> ($angle)

=over

=item * $angle (Gtk2::Gdk::PixbufRotation) 

=back

Since: gtk+ 2.6

=head2 integer = $pixbuf-E<gt>B<get_rowstride> 

=head2 $src-E<gt>B<saturate_and_pixelate> ($dest, $saturation, $pixelate)

=over

=item * $dest (Gtk2::Gdk::Pixbuf) 

=item * $saturation (double) 

=item * $pixelate (boolean) 

=back

=head2 $pixbuf-E<gt>B<save> ($filename, $type, ...)

=over

=item * $filename (localized file name) 

=item * $type (string) name of file format (e.g. "jpeg", "png")

=item * ... (list) list of key-value save options

=back


Save I<$pixbuf> to a file named I<$filename>, in the format I<$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 I<...> 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 L<Glib::Error> in $@ on failure.

=head2 scalar = $pixbuf-E<gt>B<save_to_buffer> ($type, ...)

=over

=item * $type (string) name of file format (e.g. "jpeg", "png")

=item * ... (list) list of key-value save options

=back


Save I<$pixbuf> to a scalar buffer, in the format I<$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 C<print> it.

See C<Gtk2::Gdk::Pixbuf::save> for more details.


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

Since: gtk+ 2.4

=head2 $src-E<gt>B<scale> ($dest, $dest_x, $dest_y, $dest_width, $dest_height, $offset_x, $offset_y, $scale_x, $scale_y, $interp_type)

=over

=item * $dest (Gtk2::Gdk::Pixbuf) 

=item * $dest_x (integer) 

=item * $dest_y (integer) 

=item * $dest_width (integer) 

=item * $dest_height (integer) 

=item * $offset_x (double) 

=item * $offset_y (double) 

=item * $scale_x (double) 

=item * $scale_y (double) 

=item * $interp_type (Gtk2::Gdk::InterpType) 

=back

=head2 pixbuf or undef = $src-E<gt>B<scale_simple> ($dest_width, $dest_height, $interp_type)

=over

=item * $dest_width (integer) 

=item * $dest_height (integer) 

=item * $interp_type (Gtk2::Gdk::InterpType) 

=back

=head2 integer = $pixbuf-E<gt>B<get_width> 



=cut


=head1 PROPERTIES

=over

=item 'bits-per-sample' (integer : default 8 : readable / writable / construct-only / private)

The number of bits per sample

=item 'colorspace' (Gtk2::Gdk::Colorspace : default "rgb" : readable / writable / construct-only / private)

The colorspace in which the samples are interpreted

=item 'has-alpha' (boolean : default false : readable / writable / construct-only / private)

Whether the pixbuf has an alpha channel

=item 'height' (integer : default 1 : readable / writable / construct-only / private)

The number of rows of the pixbuf

=item 'n-channels' (integer : default 3 : readable / writable / construct-only / private)

The number of samples per pixel

=item 'pixel-bytes' (Glib::Bytes : default undef : readable / writable / construct-only / private)

Readonly pixel data

=item 'pixels' (gpointer : default 0 : readable / writable / construct-only / private)

A pointer to the pixel data of the pixbuf

=item 'rowstride' (integer : default 1 : readable / writable / construct-only / private)

The number of bytes between the start of a row and the start of the next row

=item 'width' (integer : default 1 : readable / writable / construct-only / private)

The number of columns of the pixbuf

=back



=cut


=head1 ENUMS AND FLAGS

=head2 enum Gtk2::Gdk::Colorspace



=over

=item * 'rgb' / 'GDK_COLORSPACE_RGB'

=back


=head2 enum Gtk2::Gdk::InterpType

=over

=item * 'nearest' / 'GDK_INTERP_NEAREST'

=item * 'tiles' / 'GDK_INTERP_TILES'

=item * 'bilinear' / 'GDK_INTERP_BILINEAR'

=item * 'hyper' / 'GDK_INTERP_HYPER'

=back


=head2 enum Gtk2::Gdk::PixbufAlphaMode



=over

=item * 'bilevel' / 'GDK_PIXBUF_ALPHA_BILEVEL'

=item * 'full' / 'GDK_PIXBUF_ALPHA_FULL'

=back


=head2 enum Gtk2::Gdk::PixbufError



=over

=item * 'corrupt-image' / 'GDK_PIXBUF_ERROR_CORRUPT_IMAGE'

=item * 'insufficient-memory' / 'GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY'

=item * 'bad-option' / 'GDK_PIXBUF_ERROR_BAD_OPTION'

=item * 'unknown-type' / 'GDK_PIXBUF_ERROR_UNKNOWN_TYPE'

=item * 'unsupported-operation' / 'GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION'

=item * 'failed' / 'GDK_PIXBUF_ERROR_FAILED'

=back


=head2 enum Gtk2::Gdk::PixbufRotation

=over

=item * 'none' / 'GDK_PIXBUF_ROTATE_NONE'

=item * 'counterclockwise' / 'GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE'

=item * 'upsidedown' / 'GDK_PIXBUF_ROTATE_UPSIDEDOWN'

=item * 'clockwise' / 'GDK_PIXBUF_ROTATE_CLOCKWISE'

=back


=head2 enum Gtk2::Gdk::RgbDither

=over

=item * 'none' / 'GDK_RGB_DITHER_NONE'

=item * 'normal' / 'GDK_RGB_DITHER_NORMAL'

=item * 'max' / 'GDK_RGB_DITHER_MAX'

=back




=cut


=head1 SEE ALSO

L<Gtk2>, L<Glib::Object>


=cut


=head1 COPYRIGHT

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

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



=cut