NAME

Allegro::Bitmap - Allegro Bitmap routines

SYNOPSIS

   use Allegro;

   $al = Allegro->new() or die;
   $screen = $al->Display(width => 640, height => 480);

   # Display images given on command line
   for $file (@ARGV) {
      $bmp = $screen->Bitmap(file => $file) or die;
      $w = $bmp->width;
      $h = $bmp->height;

      $screen->clear();
      $screen->blit($bmp);
      $screen->text(x => 10, y => 10, text => "$file: $w x $h");
      sleep 10;
   }

DESCRIPTION

The Allegro::Bitmap module provides an object-oriented interface to the Allegro bitmap related routines.

Allegro::Bitmap is included automatically by the Allegro module, so an explicit use Allegro::Bitmap is not needed.

METHODS

new - create a new bitmap

This method creates a new bitmap object, either by creating a new bitmap in memory, or by loading a bitmap from disk.

This method can be used in three ways:

Loading an image from disk

   $bmp = $disp->Bitmap(file => "test.bmp");

This routine will load any file format supported by Allegro (BMP, PCX, LBM, TGA). PNG and JPEG support is also available if the GD module can be found. $Allegro::GD will be set if GD is available.

Creating a new bitmap

   $bmp = $disp->Bitmap(width  => 400,
                        height => 100,
                        depth  => 32);

width (required): Width of bitmap in pixels.
height (required): Height of bitmap in pixels.
depth (optional): Depth of bitmap in pixels. Defaults to depth of display.
mode (optional): Type of bitmap to create.

Creating a Sub-bitmap

Sub-bitmaps share their image with the parent bitmap. Therefore modifying the sub-bitmap will also modify the parent bitmap. Sub-bitmaps can be located at an arbitrary offset in the parent bitmap, and vary in size from the parent.

   $bmp = $disp->Bitmap(parent => $disp,
                        x      => 10,
                        y      => 10,
                        width  => $disp->width - 20,
                        height => $disp->height - 20);

parent (required): The parent Bitmap object. May be a memory bitmap, video bitmap, system bitmap or a Display object.
x (required): X offset in parent bitmap.
y (required): Y offset in parent bitmap.
width, w (required): Width of sub-bitmap.
height, h (required): Height of sub-bitmap.

acquire

Acquires a video memory bitmap prior to drawing onto it. These calls are not strictly required, because the drawing routines will automatically acquire the bitmap before accessing it, but on some platforms you may get much better performance if you acquire the screen just once at the start of your main redraw function, and only release it when the drawing is completely finished.

release

Releases a bitmap that was previously locked by calling acquire. If the bitmap was acquired multiple times, you must release it the same number of times before it will truly be unlocked.

clear

Clears a bitmap.

   $bmp->clear(color => $color);

color is optional, and defaults to black.

putpixel

Sets a pixel to a certain color.

   $bmp->putpixel(x     => $x,
                  y     => $y,
                  color => 'blue');

Note that if you don't specify a color the default is to pick one at random.

getpixel

Returns the color of a certain pixel in a format suitable to passing as color to any drawing primitives.

   $color = $bmp->getpixel(x => $x,
                           y => $y);

line

Draws a line.

   $bmp->line(x1    => $x1,
              y1    => $y1,
              x2    => $x2,
              y2    => $y2,
              color => 'white');

x1, x (required): X coordinate of origin.
y1, y (required): Y coordinate of origin.
x2 (optional): X coordinate of second point. Defaults to x1.
y2 (optional): Y coordinate of second point. defaults to y1.
color (optional): Color of line to draw.

triangle

Draws a triangle.

   $bmp->triangle(x1 => $x1, y1 => $y1,
                  x2 => $x2, y2 => $y2,
                  x3 => $x3, y3 => $y3,
                  color => $color);

rect

Draws a rectangle.

   $bmp->rect(x      => $x,
              y      => $y,
              width  => $width,
              height => $height,
              color  => $fill,
              border => $border);

x (required): X coordinate of origin.
y (required): Y coordinate of origin.
width (optional): Width of rectangle.
height (optional): Height of rectangle.
x2 (optional): X coordinate of bottom right corner.
y2 (optional): Y coordinate of bottom right corner.
color (optional): Color with which to fill rectangle.
border (optional): Color with which to draw border of rectangle.

Either the width and height or the x2 and y2 options must be specified.

ellipse

Draws an ellipse.

   $bmp->ellipse(x      => $x,
                 y      => $y,
                 width  => $rx,
                 height => $ry,
                 color  => $fill,
                 border => $border);

x (required): X coordinate of center of ellipse.
y (required): Y coordinate of center of ellipse.
width, w (optional): Radius along x axis.
height, h (optional): Radius along y axis.
radius (optional): Radius of x and y axis.
color (optional): Color with which to fill ellipse.
border (optional): Color with which to draw ellipse border.

Either width and height or radius is required.

circle

Alias for ellipse.

floodfill

Floodfills an area starting at the specified point.

   $bmp->floodfill(x     => $x,
                   y     => $y,
                   color => $c);

text

Draws text onto bitmap.

   $bmp->text(x     => $x,
              y     => $y,
              font  => $font,
              color => $color,
              bg    => $bg,
              align => 'left',
              text  => "Hello World");

x (optional): X coordinate. Defaults to 0.
y (optional): Y coordinate. Defaults to 0.
width, w (optional): Width of text if align is set to justify.
font (optional): Font object to use as font.
color, foreground, fg (optional): Color in which to draw text.
background, bg (optional): Background color to use.
align (optional)

polygon

Draws a polygon.

   $bmp->polygon($color,
                 $x1, $y1,
                 $x2, $y2,
                 $x3, $y3,
                 ...);

   $bmp->polygon($x1, $y1,
                 $x2, $y2,
                 $x3, $y3,
                 ...);

blit_to

Copies part of or all of the bitmap onto another bitmap or display.

   # These calls are equivalent.
   $bmp->blit_to($screen, ...);
   $screen->blit($bmp, ...);

See blit below for a full description.

blit

Copies part or all of a bitmap onto this one

   $bmp->blit($source,
              sx     => $sx,
              sy     => $sy,
              dx     => $dx,
              dy     => $dy,
              sw     => $sw,
              sh     => $sh,
              dw     => $dw,
              dh     => $dh,
              masked => $masked);

Blender support is not yet implemented (translucency, lighting, etc).

$source (required): Source Allegro::Bitmap object.
sx (optional): X coordinate in source image. Defaults to 0.
sy (optional): Y coordinate in source image. Defaults to 0.
dx, x (optional): X coordinate in destination image. Defaults to 0.
dy, y (optional): Y coordinate in destination image. Defaults to 0.
sw, w, width (optional): Width of portion to blit. Defaults to width of source image.
sh, h, height (optional): Height of portion to blit. Defaults to height of source image.
dw (optional): Width of destination blit. Defaults to width of source image.
dh (optional): Height of destination blit. Defaults to height of source image.
masked (optional): Perform a masked blit (do not copy from source image where mask is set).

Examples:

Standard blit

   $bmp->blit($source, x => 20, y => 20);

Blits $source to $bmp at (20, 20) in $bmp.

Stretched blit

   $bmp->blit($source, dw => 640, dh => 480);

Stretches $source to 640x480 and copies to $bmp.

Masked blit (Transparent blit)

   $bmp->blit($source, masked => 1);

Copies $source to $bmp ignoring parts of $source that are masked out.

Combined

   $bmp->blit($source, dw     => $dest->{width},
                       dh     => $dest->{height},
                       masked => 1);

The above operations can be combined in a single call.

Be warned that temporary bitmaps may be created behind your back to perform certain combinations. Using different source and destination widths/heights with a non-memory bitmap as a source, or masked blits with a non-memory bitmap as a source (on certain hardware) will create a temporary memory bitmap. The same is true when converting between color depths when using masked or stretched blits.

AUTHOR

Colin O'Leary <colin@mx3.org>

COPYRIGHT