/ 
Gtk2-1.2496
River stage three • 102 direct dependents • 128 total dependents
/ xs/GdkPixbuf.xs

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 get_pixels return reflects this.

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 pack to generate a scalar containing the pixel data, and pass that scalar to 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 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 $pixbuf->composite, or try a different approach (possibly use a server-side pixmap and gdk drawing primitives, or something like libart).

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?]

Gtk+ ships with a tool called 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. 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 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 $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/ .

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.)

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.

The seconds and microseconds values are available from Time::HiRes, which is standard since perl 5.8.0. If both are undef or omitted, the function uses the current time.

Parses enough of $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.

DESCRIPTION

A Gtk2::Gdk::PixbufFormat has the following format information fields, eg. $format->{'name'},

name            string
description     string
mime_types      arrayref of strings
extensions      arrayref of strings, eg. ['jpg','jpeg']
is_writable     0 or 1
is_scalable     0 or 1    # in Gtk 2.6 up
is_disabled     0 or 1    # in Gtk 2.6 up
license         string    # in Gtk 2.6 up

Note that any change caused by this method will not immediately affect $format->{is_disabled}. You need to refetch the format in order to see the new value.