mirror of https://github.com/GNOME/gimp.git
117 lines
4.2 KiB
Plaintext
117 lines
4.2 KiB
Plaintext
=head1 NAME
|
|
|
|
Gimp::Pixel - how to operate on raw pixels
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Gimp;
|
|
use Gimp::PDL; # you need Gimp::PDL for pixel access
|
|
use PDL; # to make sensible things with the pixels
|
|
|
|
# Gimp::GDrawable - The GDrawable structure
|
|
# Gimp::Tile - The Tile family of functions.
|
|
# Gimp::PixelRgn - The PixelRgn family of functions.
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
You can access the pixels in a drawable through tiles or pixel regions. This
|
|
manpage explains how this is done in perl. All classes (Gimp::GDrawable,
|
|
Gimp::Tile, Gimp::PixelRgn) are available with and without the C<Gimp::> prefix.
|
|
|
|
=head1 GDRAWABLES
|
|
|
|
Well, you know drawables? (also known as PARAM_DRAWABLE or Gimp::Drawable)?
|
|
In the Gimp, drawables are things you can draw on: layers, channels or whole
|
|
images. While most functions named C<gimp_drawable_something> operate on
|
|
C<drawable_ID>s, some functions (notably the ones operating on raw pixel
|
|
data!) need a C<GDrawable> instead. Every drawable has a corresponding
|
|
C<GDrawable>, you can get it with the C<gimp_drawable_get> function:
|
|
|
|
my $gdrawable = $drawable->get;
|
|
|
|
When the $gdrawable is destroyed, it is automatically flushed & detached, so
|
|
you don't need to do this yourself.
|
|
|
|
=head1 TILES
|
|
|
|
Tiles are the basic building blocks of all drawables. Each drawable consists
|
|
of a "grid" of tiles, each tile having the same size. The size of a tile is
|
|
always the same (it's hardcoded in your Gimp program).
|
|
|
|
The C<gimp_tile_width> and C<gimp_tile_height> functions return the current
|
|
width/height of a tile (at the moment, this is 64x64).
|
|
|
|
How do I get a tile? First, you have to grab a GDrawable structure. You can
|
|
get one from any drawable, by calling the C<get> function:
|
|
|
|
my $gdrawable = $drawable->get;
|
|
|
|
in a sense, <$gdrawable> contains all tiles. Changes you make to them might
|
|
not be reflected in the image until you destroy this variable. (Thats the
|
|
reason I used "my" int he above example. Once $gdrawable gets out of scope,
|
|
the drawable in the gimp automatically gets updated).
|
|
|
|
To get access to a tile, you have to call C<get_tile> or C<get_tile2>.
|
|
C<get_tile> expects row/column numbers of the tile, while C<get_tile2>
|
|
expects pixel coordinates and will return the tile that pixel is in:
|
|
|
|
my $tile = $gdrawable->get_tile2(1,75,60);
|
|
|
|
The C<data> method returns and sets the raw pixel data.
|
|
|
|
$piddle = $tile->data; # get the tile data as a piddle
|
|
$piddle *= 0.5; # do sth. with the pixels
|
|
$tile->data($piddle); # and modify the tile
|
|
|
|
=head1 PIXELREGIONS
|
|
|
|
C<PixelRgn>s are rectangular parts of a drawable. You can access single
|
|
pixels, rows, columns and rectangles within these regions. Don't expect me
|
|
to explain everything now, I don't understand the mechanism too well
|
|
myself..
|
|
|
|
How do I create a pixel region? First, you have to grab a GDrawable structure. You can
|
|
get one from any drawable, by calling the C<get> function:
|
|
|
|
my $gdrawable = $drawable->get;
|
|
|
|
Now you can create as many PixelRgn structures as you want from
|
|
the C<GDrawable>:
|
|
|
|
my $region = new PixelRgn($gdrawable,0,0,50,30,1,0); # with "new"
|
|
my $region = $gdrawable->pixel_rgn(0,0,50,30,1,0); # or from a drawable
|
|
|
|
which method you choose is purely a question of style...
|
|
|
|
The following functions return packed pixel data (see L<Gimp::PDL> for an
|
|
easier way to manipulate on image data):
|
|
|
|
$piddle = $region->get_pixel(45,60); # return the pixel at (45|60)
|
|
$piddle = $region->get_row(45,60,10); # return ten horizontal pixels
|
|
$piddle = $region->get_col(45,60,10); # same but vertically
|
|
$piddle = $region->get_rect(45,60,10,12); # a 10x12 rectangle
|
|
|
|
To modify pixels, the dirty bit of the region must be set (I believe, but I
|
|
don't see the reason what the dirty bit in a region is for so I might be
|
|
wrong), and you can write pixel data to the region with the following
|
|
functions, each one corresponding to a get-function:
|
|
|
|
$region->set_pixel($piddle,45,60); # set pixel at (45|60)
|
|
$region->set_row($piddle,45,60); # set a row
|
|
$region->set_col($piddle,45,60); # set a column
|
|
$region->set_rect($piddle,45,60); # set a whole rectangle
|
|
|
|
Please note that (unlike the C functions they call), the size arguments
|
|
(width and/or height) are missing, they can be calculated from the piddle.
|
|
|
|
=head1 AUTHOR
|
|
|
|
Marc Lehmann <pcg@goof.com>
|
|
|
|
=head1 SEE ALSO
|
|
|
|
perl(1), Gimp(1).
|
|
|
|
=cut
|
|
|