PIXEL(1)						User Contributed Perl Documentation						  PIXEL(1)

NAME

       Gimp::Pixel - how to operate on raw pixels.

       ***WARNING*** this manpage is no longer up-to-date. See "examples/map_to_gradient" for a simple raw-pixel-manipulating plug-in. If you bug
       me enough I'll rewrite this document.

SYNOPSIS

	 use Gimp;
	 use PDL;	       # to make sensible things with the pixels

	 # Gimp::GimpDrawable  - The GimpDrawable structure
	 # Gimp::Tile	       - The Tile family of functions.
	 # Gimp::PixelRgn      - The PixelRgn family of functions.

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::GimpDrawable, "Gimp::Tile", "Gimp::PixelRgn") are available with and without the "Gimp::" prefix.

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 "gimp_drawable_something" operate on "drawable_ID"s, some functions (notably the ones
       operating on raw pixel data!) need a "GimpDrawable" instead. Every drawable has a corresponding "GimpDrawable", you can get it with the
       "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.

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 "gimp_tile_width" and "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 GimpDrawable structure. You can get one from any drawable, by calling the "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 "get_tile" or "get_tile2".  "get_tile" expects row/column numbers of the tile, while "get_tile2"
       expects pixel coordinates and will return the tile that pixel is in:

	my $tile = $gdrawable->get_tile2(1,75,60);

       The "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

PIXELREGIONS

       "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 GimpDrawable structure. You can get one from any drawable, by calling the "get"
       function:

	my $gdrawable = $drawable->get;

       Now you can create as many PixelRgn structures as you want from the "GimpDrawable":

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

AUTHOR

       Marc Lehmann <pcg@goof.com>

SEE ALSO

       perl(1), Gimp(1).

perl v5.8.0							    2000-08-24								  PIXEL(1)