Allegro::Bitmap - Allegro Bitmap routines
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"); $al->sleep(10); }
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.
use Allegro::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:
$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.
$Allegro::GD
$bmp = $disp->Bitmap(width => 400, height => 100, depth => 32);
Width of bitmap in pixels.
Height of bitmap in pixels.
Depth of bitmap in pixels. Defaults to depth of display.
Type of bitmap to create.
memory
The bitmap will be held in main memory, and can be any depth. It will be converted to the display format when copied to the display. This is the default.
video
Video bitmaps are created in the graphic card's video memory, and must be the same depth as the display. Video bitmaps will be slower to read, but will be quicker to blit to the screen if your graphics device is accelerated. Video bitmaps must be in the same depth as the display.
system
System bitmaps may be stored in a platform independent method, but are stored in main memory. They must also be the same depth as the screen.
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);
The parent Bitmap object. May be a memory bitmap, video bitmap, system bitmap or a Display object.
X offset in parent bitmap.
Y offset in parent bitmap.
Width of sub-bitmap.
Height of sub-bitmap.
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.
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.
acquire
Clears a bitmap.
$bmp->clear(color => $color);
color is optional, and defaults to black.
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.
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);
Draws a line.
$bmp->line(x1 => $x1, y1 => $y1, x2 => $x2, y2 => $y2, color => 'white');
X coordinate of origin.
Y coordinate of origin.
X coordinate of second point. Defaults to x1.
Y coordinate of second point. defaults to y1.
Color of line to draw.
Draws a triangle.
$bmp->triangle(x1 => $x1, y1 => $y1, x2 => $x2, y2 => $y2, x3 => $x3, y3 => $y3, color => $color);
Draws a rectangle.
$bmp->rect(x => $x, y => $y, width => $width, height => $height, color => $fill, border => $border);
Width of rectangle.
Height of rectangle.
X coordinate of bottom right corner.
Y coordinate of bottom right corner.
Color with which to fill rectangle.
Color with which to draw border of rectangle.
Either the width and height or the x2 and y2 options must be specified.
Draws an ellipse.
$bmp->ellipse(x => $x, y => $y, width => $rx, height => $ry, color => $fill, border => $border);
X coordinate of center of ellipse.
Y coordinate of center of ellipse.
Radius along x axis.
Radius along y axis.
Radius of x and y axis.
Color with which to fill ellipse.
Color with which to draw ellipse border.
Either width and height or radius is required.
Alias for ellipse.
Floodfills an area starting at the specified point.
$bmp->floodfill(x => $x, y => $y, color => $c);
Draws text onto bitmap.
$bmp->text(x => $x, y => $y, font => $font, color => $color, bg => $bg, align => 'left', text => "Hello World");
X coordinate. Defaults to 0.
Y coordinate. Defaults to 0.
Width of text if align is set to justify.
justify
Font object to use as font.
Color in which to draw text.
Background color to use.
Aligns text to left, starting at (x, y).
Aligns text to right, ending at (x, y).
Centers text around (x, y).
Starts text at (x, y), ending at (x + width, y).
Draws a polygon.
$bmp->polygon($color, $x1, $y1, $x2, $y2, $x3, $y3, ...); $bmp->polygon($x1, $y1, $x2, $y2, $x3, $y3, ...);
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.
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, rotate => $angle, origin => [$x, $y]);
Blender support is not yet implemented (translucency, lighting, etc).
Source Allegro::Bitmap object.
X coordinate in source image. Defaults to 0.
Y coordinate in source image. Defaults to 0.
X coordinate in destination image. Defaults to 0.
Y coordinate in destination image. Defaults to 0.
Width of portion to blit. Defaults to width of source image.
Height of portion to blit. Defaults to height of source image.
Width of destination blit. Defaults to width of source image.
Height of destination blit. Defaults to height of source image.
Perform a masked blit (do not copy from source image where mask is set).
Rotates the source bitmap before drawing. The parameter should be between 0 and 1. By default the origin of the rotation will be (0, 0). Using a rotated blit currently implies a masked blit.
When used with rotated blits, the origin around which to rotate. Given as an anonymous reference of the x and y coordinates of the pivot point.
Examples:
$bmp->blit($source, x => 20, y => 20);
Blits $source to $bmp at (20, 20) in $bmp.
$bmp->blit($source, dw => 640, dh => 480);
Stretches $source to 640x480 and copies to $bmp.
$bmp->blit($source, masked => 1);
Copies $source to $bmp ignoring parts of $source that are masked out.
$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.
Currently rotated blits can not be combined with stretched blits or blits with an offset source (x, y).
Colin O'Leary <colino@cpan.org>
acquire and release descriptions are from the Allegro documentation.
Copyright 2003 by Colin O'Leary. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The Allegro library and documentation is copyright its authors, and is giftware. See http://alleg.sf.net for more information.
To install Allegro, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Allegro
CPAN shell
perl -MCPAN -e shell install Allegro
For more information on module installation, please visit the detailed CPAN module installation guide.