Euphoria Bitmap Tools v1.1		Colin Taylor       4/6/97
--------------------------		71630.1776@compuserve.com
					
The program "bitmap.e" contains various routines for the manipulation of 
Euphoria color bitmaps, i.e. graphic images of up to 256 colors in the 
same format used by the save_image() and display_image() routines found 
in "image.e".  Windows bitmap (.bmp) files can be converted to Euphoria 
bitmaps by the read_bmp() routine.

The bitmap.e routines enable bitmaps to be adjusted in size, inverted, 
rotated, shifted and skewed.  Sections can be cut out of bitmaps or pasted 
into bitmaps.  Small bitmaps can be tiled into large bitmaps.  Routines 
are included to save and load bitmaps in binary format.

A special subset of the Euphoria bitmap is the boolean bitmap, consisting 
entirely of TRUE and FALSE pixels.  Boolean bitmaps can be used to mask 
color bitmaps in various ways through the use of math or boolean operators, 
provided that the bitmaps are the same size. 

Routines are also provided to compress and expand boolean bitmaps.  Boolean 
bitmaps are compressed by converting the rows of bits into bytes (one byte 
for each 8 bits).  A compressed bitmap must be expanded to a boolean bitmap 
to be manipulated or displayed.

All routines are coded entirely in Euphoria - no machine language is used.  
Thanks to the speed of Euphoria, and its ability to do mathematical and 
boolean operation on sequences, the bitmap routines execute reasonably fast.

The following global routines are found in "bitmap.e":
	- type bitmap(sequence bm)
	- function bm_size(bm)
	- function bm_colors(bm)
	- function bm_roll(bm, s)
	- function bm_shift(bm, s, c)
	- function bm_warp(bm, s, c)
	- function bm_resize(bm, s1, s2, c)
	- function bm_trim(bm, s1, s2)
	- function bm_insert(bm1, bm2, s)
	- function bm_tile(bm, a)
	- function bm_invert(bm)
	- function bm_rotate(bm)
	- function bm_compress(bm)
	- function bm_expand(bc, w)
	- function bm_save(bm, name)
	- function bm_load(name)

bitmap(bm)
----------
Tests the sequence bm and returns TRUE if bm is a valid Euphoria bitmap, 
otherwise returns FALSE.
	example:    if bitmap(bm) then...

bm_size(bm)
-----------
Returns the matrix size of bitmap bm in the form {sx, sy}.
	example:    size = bm_size(bm)

bm_colors(bm)
-------------
Returns the apparent number of colors (2, 4, 16 or 256) used in bitmap bm, 
based on the highest color value found in the bitmap.
	example:    colors = bm_colors(bm)

bm_roll(bm, r)
--------------
Moves the image in bitmap bm r[1] pixels to the right and r[2] pixels down.  
The pixels which overflow are added to the opposite side of the matrix.  The 
modified bitmap is returned.  The vector r is a sequence in the form {x, y}, 
where r[1] and r[2] can be positive or negative.
	example:    bm2 = bm_roll(bm1, {1, -1})

bm_shift(bm, v, c)
------------------
Moves the image in bitmap bm v[1] pixels to the right and v[2] pixels down.  
Pixels which overflow are discarded and pixels of color c are added to the 
opposite side of the matrix to maintain matrix size.  The shifted bitmap is 
returned.  The vector v is a sequence in the form {x, y}, where v[1] and 
v[2] can be positive or negative.
	example:    bm2 = bm_shift(bm1, {-1, 1}, 15)

bm_warp(bm, s, c)
-----------------
Shifts each line of the bitmap bm to the right by the corresponding value 
in pixels found in s.  Adds pixels of color c to the ends of each line to 
maintain the rectangular shape of bm.  The warped bitmap is returned.  The 
width of bm will be increased by the largest value found in s.  The length 
of s must be greater or equal to the height of bm, or a subscript error 
will result.
	example:    bm2 = bm_warp(bm1, {0,0,0,1,2,3,2,1,0,0,0}, 5)

bm_resize(bm, r1, r2, c)
------------------------
Adjusts the size of bitmap bm by adding or subtracting rows or columns to 
(or from) any side of the bitmap.  Pixels removed are discarded.  Pixels 
added are color c.  The resized bitmap is returned.  The vector r1 is a 
sequence in the form {x, y} where r1[1] and r1[2] are the resize amount for 
top and left of bitmap.  Similarly, r2 is a sequence in the form {x, y} 
containing the resize amount for bottom and right of bitmap.  The resize 
values can be positive (to enlarge the bitmap) or negative (to shrink the 
bitmap).  If the resize values result in a null  or negative sized bitmap, 
Euphoria will return a subscript error.
	example:    bm2 = bm_resize(bm1, {1, 1}, {1, 1}, 0)

bm_trim(bm, s1, s2)
-------------------
Extracts a rectangular bitmap section {s1, s2} from a larger bitmap bm.  
The extracted bitmap is returned.  The sequences s1 and s2 are graphics 
points in the form {x, y}, where s1 is the position within bm of the upper 
left corner of the section and s2 is the position of the lower right 
corner of the section.  Both s1 and s2 must fall within the area of bm, or 
a subscript error will result.
	example:    bm2 = bm_trim(bm1, {5, 5}, {25, 30})

bm_insert(bm1, bm2, s)
----------------------
Inserts a rectangular bitmap section bm2 into a larger bitmap bm1.  The 
modified bitmap is returned.  The sequence s is a graphics point in the 
form {x, y}, which gives the  position of the upper left corner of bm2 
within bm1.  All of bm2 must fall within the area of bm1, or a subscript 
error will result.
	example:    bm3 = bm_insert(bm1, bm2, {5, 5})

bm_tile(bm, a)
--------------
Repeats bitmap bm over an area a, where a = {width, length} in pixels.  
The routine works for any combination of bitmap size and area a, even
if area a is smaller than the size of bm.  The tiled bitmap is returned.
	example:    bm2 = bm_tile(bm1, {640, 480})

bm_invert(bm)
-------------
Inverts bitmap bm top to bottom, producing a mirror image.  The inverted 
bitmap is returned.  To flip the image sideways, use a combination of 
bm_rotate() (below) and bm_invert().
	example:    bm2 = bm_invert(bm1)

bm_rotate(bm)
-------------
Rotates bitmap bm 90 degrees counterclockwise.  The rotated bitmap is 
returned.  To rotate 180, or 270 degrees, make multiple calls to bm_rotate().
	example 1:    bm2 = bm_rotate(bm1)
	example 2:    bm2 = bm_rotate(bm_rotate(bm1))  -- rotates 180 degrees

bm_compress(bm)
---------------
Converts boolean bitmap bm to a compressed bitmap.  The compressed bitmap 
is returned.  This is useful when saving a boolean bitmap to disk, as it 
takes up much less disk space.
	example:    bc = bm_compress(bm)

bm_expand(bc, w)
----------------
Converts compressed bitmap bc to a boolean bitmap.  The expanded bitmap is 
returned.  The integer w gives the  bitmap width in pixels, needed for the 
case when the bitmap width is not an even multiple of 8.  The value of w 
must not exceed 8 times the bitmap width in bytes, or a subscript error 
will result.
	example:    bm = bm_expand(bc)

bm_save(bm, name)
-----------------
Saves a bitmap to the current directory in binary format.  An error code
of 0 is returned if the file is saved successfully, otherwise a 1 is 
returned.  This function is useful for saving compressed boolean bitmaps.
	example:    ec = bm_save(bc, "bitmap.bc")

bm_load(name)
-------------
Loads and returns a bitmap which has been saved by bm_save() in the
current directory.  
	example:    bm = bm_load(bm)

--O--
