June 9, 1989



**********************************************
* *
* D R A W F I L L *
* *
* version 2.0 *
* *
* (c) 1989 Richard Biffl *
* *
**********************************************



DrawFill is a programming tool to help design graphic fill patterns for the
Borland Graphics Interface (BGI) used by Borland's Turbo languages.

The command-line syntax for running DrawFill is:

DRAWFILL [D=] [M=] [P=] [R] [/A] [/C] [/R]
[/L] [/"["]]

Items in square brackets (e.g., [R]) are optional. (All
parameters are optional.) Items in corner brackets (e.g.,
) should be replaced as indicated in the detailed
descriptions of the parameters. Case is ignored. So is the
order of the parameters; but if the same parameter occurs more
than once, the last instance takes effect. Parameters are
separated by a space or a tab.

Command-line parameters:

D= Driver specification

M= Mode-number specification

P= Path to screen driver file (.BGI) and
LITT.CHR

R RAM-resident mode

/A /C /R /L /"" Hot-key specifiers, for RAM-resident
mode

Usage of these parameters is described in detail in a later section of this
document.



FILL PATTERNS

An important element of the Borland Graphics Interface is the "fill pattern."

A fill pattern is a pattern eight pixels wide and eight pixels high, which is
repeated like a wallpaper pattern to fill part of the screen. Fill patterns
make any graphical output more lively, and they are especially useful in
monochrome graphics as substitutes for colors.

The BGI contains the following procedures that paint fill patterns on the
screen:

Bar Fills a rectangular area with the current fill
style and fill color.

Bar3D Draws a three-dimensional bar and fills its face
with the current fill style and fill color.

FillEllipse Draws an ellipse and fills it with the current
fill style and fill color.

FillPoly Draws a polygon and fills it with the current
fill style and fill color.

FloodFill Fills any bounded region with the current fill
style and fill color.

PieSlice Draws a pie slice and fills it with the current
fill style and fill color.

Sector Draws an elliptical sector and fills it with the
current fill style and fill color.

By default, the fill style is solid and the fill color is the maximum color in
the current palette. The fill pattern can be set by calling either of the
BGI's following two procedures:

SetFillStyle Sets a pre-defined fill pattern (see Borland
manual for descriptions).

SetFillPattern Sets a user-defined fill pattern.

SetFillPattern defines a new fill pattern from a pattern definition and a
color. The pattern is defined in an array of 8 bytes, one byte for each row
of pixels. Each byte's value is the sum of the values of the lit pixels in
the row. The values of the pixels, from left-most pixel to right-most, are

decimal notation: 128, 64, 32, 16, 8, 4, 2, 1
hexadecimal notation: $80, $40, $20, $10, $08, $04, $02, $01

For example, a fill pattern defined by (0,0,0,0,0,0,0,0) does not light any
pixels. A fill pattern of (255,255,255,255,255,255,255,255) lights all
pixels. (3,3,3,3,3,3,3,3) draws vertical lines two pixels thick; the pixel
with value 2 and the pixel with value 1 are both lit in each row.
(0,0,0,255,0,0,0,255) draws horizontal lines on every fourth row of pixels.

SetFillPattern allows the creation of fill patterns that are more interesting
than straight lines. Sketching such patterns on graph paper, though, and
manually calculating their pixel-row values, is a tedious and error-prone
task. DrawFill was made to simplify the process.



USING DRAWFILL

DrawFill lets you concentrate on creativity instead of bit values. You move a
circular cursor around an eight-by-eight grid, toggling pixels on or off as
you go. The pattern you are creating, and its changing values, are displayed
simultaneously next to the grid. You can scroll the whole pattern, invert it,
or change its colors until you see just what you want for your own program.
The values you need will all be on the screen, ready to copy into your
program. If you make DrawFill resident in memory, it will even do some of the
copying for you.

When DrawFill starts, a command menu appears at the bottom of the screen. The
command menu lists all of the available command keys, the current state of all
toggle switches, and the current graphics driver and graphics mode. The
command keys are simple:

Move the circular cursor from pixel to pixel on
the drawing grid, when Scroll Lock is OFF. When
Scroll Lock is ON, the arrow keys scroll the
whole pattern through the drawing grid.

Home, End Move the cursor to the left-most and right-most
columns, respectively.

PgUp, PgDn Move the cursor to the top-most and bottom-most
rows, respectively.

Toggles the current pixel on or off.

Ctrl-Home Erases the current fill pattern and returns the
cursor to the top-left pixel.

Esc Exits from DrawFill.

Scroll Lock When ON, allows the user to scroll the fill
pattern up, down, left, or right, using the
arrow keys.

NOTE: Take care when using Scroll Lock in
DrawFill's resident mode, if your keyboard has a
Scroll Lock indicator. When DrawFill pops up,
it saves the status of the toggle keys, which is
restored when DrawFill pops back down. However,
there is no way (known to me) to restore the
status of the Scroll Lock indicator light on
your keyboard. Your light may therefore
indicate the opposite of your computer's Scroll
Lock status. To prevent this annoyance, return
to DrawFill's original Scroll Lock status before
exiting from DrawFill when it is memory-
resident.

H Toggles hexadecimal mode or decimal mode for
representing the numerical values of the fill
pattern. Hexadecimal values are preceded by a
dollar sign ($), as in Turbo Pascal.

M Toggles the graphics mode for the current screen
driver. The mode number is defined by the BGI
driver; it is NOT the same as the ROM BIOS's
mode number.

F Toggles the color of the fill pattern.

S Toggles the foreground color of the screen
(other than the pixels which compose the fill
pattern).

B Toggles the background color of the screen.

I Inverts the fill pattern, so that pixels that
were lit are turned off and pixels that were off
are turned on.

W Writes the code for the fill pattern as it exits
DrawFill (available in resident mode only). The
pattern will be written from the point where the
cursor was when you popped DrawFill up.



COMMAND-LINE PARAMETERS

The command-line syntax for running DrawFill is:

DRAWFILL [D=] [M=] [P=] [R] [/A] [/C] [/R]
[/L] [/"["]]

Items in square brackets (e.g., [R]) are optional. (All
parameters are optional.) Items in corner brackets (e.g.,
) should be replaced as indicated in the detailed
descriptions of the parameters. Case is ignored. So is the
order of the parameters; but if the same parameter occurs more
than once, the last instance takes effect. Parameters are
separated by a space or a tab.



D= Driver specification

By default, DrawFill automatically uses the Borland BGI driver
that can provide the highest-quality graphics output on your
system. The D= parameter overrides the default driver.

The parameter specifies a Borland driver when is the
NUMBER (NOT the filename) of the appropriate Borland driver.
Borland drivers and their numbers are listed in your Borland
manual.

NOTE: The IBM 8514 graphics driver and the AT&T 400-line driver
CANNOT be installed automatically; if you are using one of them,
you MUST specify either D=6 or D=8, respectively.

Example:

DRAWFILL D=8
Initializes ATT400 driver (BGI driver
#8).

You can also use the D= parameter to use a non-Borland
screen driver. For example, if your system has the Spiffy
Graphics Array, and its manufacturer provided a driver for the
Borland Graphics Interface, you can use it by specifying the
FILENAME of the driver (NOT a number) in place of . The
DOS path to the driver should be included if the driver is not
in the current directory or in the directory specified by the
P= parameter.

Examples:

DRAWFILL D=SGA.BGI
DrawFill uses the custom screen driver
in the file SGA.BGI.

DRAWFILL D=\SPIFFY\SGA.BGI
DRAWFILL D=SGA.BGI P=\SPIFFY
DrawFill uses the driver SGA.BGI in the
SPIFFY directory of the current disk.

If the D= parameter specifies an invalid driver, the
error may not be detectable by DrawFill and the screen may go
blank. If so, try pressing Esc to escape back to the DOS
prompt. If your computer seems hopelessly locked up, reboot it
immediately to prevent the possibility of hardware damage.



M= Mode-number specification

By default, DrawFill tries to use the screen driver's mode with
the highest graphics quality. You can override the default mode
with the M= parameter, where is a NUMBER. The
valid modes for each Borland screen driver are listed in your
Borland manual. A specification of an invalid mode is ignored.

Example:

DRAWFILL M=0
Initializes the default driver in mode
0, which usually has the lowest resolution but
sometimes (e.g., on the CGA) has more colors
than the highest-resolution mode.

NOTE: Be sure to use Borland's mode number with the M=
parameter, NOT the ROM BIOS mode number.

NOTE: You can also change modes from within DrawFill, by
pressing .



P= Path to screen driver file (.BGI) and LITT.CHR

DrawFill requires the appropriate driver's .BGI file, and the
LITT.CHR font file. (These files are not included with
DrawFill; they are included with all Borland languages that use
the Borland Graphics Interface.)

By default, if the .BGI file is not found in the current
directory, the program will terminate with an error message. If
the LITT.CHR file is not found, the program will run using only
the default font, which will make only a cosmetic difference.

A path to the .BGI and LITT.CHR files may be specified on the
DrawFill command line with the P= parameter.

Example:

DRAWFILL P=C:\TP\TPGRAPH
Looks in the TPGRAPH subdirectory of the
TP directory on drive C.

DRAWFILL P=..
Looks in the parent directory above the
current subdirectory.



R RAM-resident mode

The R parameter loads DrawFill into random-access memory, where
it resides while you run other programs. You can pop DrawFill
up by pressing a hot-key combination.

By default, the hot-key combination is .
(You can remember this because "DRA" are the first three letters
of "DRAwFill.") DrawFill will pop up when you hold down the
and keys while you press . You can
change the hot-key combination with command-line parameters, as
described below.

DrawFill has a special capability in resident mode. It can
write the code for the pattern you create directly into whatever
program you were running when you popped DrawFill up. Press
in resident mode and DrawFill will pop down, writing the code
for your fill pattern to your screen. This is handy when you
pop DrawFill up from an editor while writing a program that will
use your fill pattern.

DrawFill uses almost 85,000 bytes of memory in resident mode.
It remains resident until you reboot your computer (unless you
have a memory manager that can release resident programs without
rebooting).

Example:

DRAWFILL R
Makes DrawFill resident in memory, and
reports how much memory it uses and what hot-key
combination is in effect.

NOTE: Because of limitations on the memory available to save
the screen, DrawFill can only be popped up from text and CGA-
graphics modes.



/A /C /R /L /"" Hot-key specifiers, for RAM-resident mode

The default hot-key combination to pop DrawFill up when it is
resident is . You can change either the
hot shift-key combination, or the hot character key, or both.

The shift keys are specified by /A for , /C for , /R
for , and/or /L for . Any combination
of these four shift keys is permitted.

The character key is specified by /"", where is any
character from to or numeral from <0> to <9>. The
second quotation mark is optional.

If you change only the shift-key combination, or only the
character key, the default will be used for the other part of
the hot-key combination.

Examples:

DRAWFILL R /C
Installs DrawFill in memory, with a hot-
key combination of .

DRAWFILL R /"F"
Installs DrawFill in memory, with a hot-
key combination of .

DRAWFILL R /C /"F"
Installs DrawFill in memory, with a hot-
key combination of .

The effective hot-key combination will be displayed when
DrawFill is installed in memory.



DISCLAIMER OF WARRANTY

DrawFill has been written with care, and I will make an honest effort to
exterminate any bugs reported by users. Beyond that, however, I specifically
disclaim all other warranties, expressed or implied, including but not limited
to implied warranties of merchantability or fitness for any particular
purpose, with respect to both the software and this documentation. In no
event shall I be liable for any loss of profit or any other commercial damage,
nor for any special, incidental, consequential or other damages. I do not
know of any risk in using DrawFill; but if there is a risk, the user bears it.



DISTRIBUTION POLICY

DrawFill is protected by United States copyright law and international treaty
provisions. It is not in the public domain.

You need not pay anything to use DrawFill to create fill patterns for graphics
programs, either commercial or non-commercial. (You may also use it to doodle
to your heart's content.) However, you may not incorporate DrawFill itself
into another program, product, or commercial package, without my prior written
consent.

You may distribute DrawFill and this documentation, provided that you
distribute both DRAWFILL.EXE and DRAWFILL.DOC, TOGETHER and UNALTERED. Please
let me know of any need for patches or revisions. If you must change one of
the files yourself, you may not distribute a copy of the altered version to
anyone else.

No distributor may charge for this program or documentation without my prior
written consent, except that distributors may charge a nominal fee (no more
than $10) to cover the costs of distribution.

The latest version of DrawFill is available from me for $10. If you tell me
which version you already have when you place your order, and it IS the latest
version, I will return your money, unless you tell me you would prefer to
receive an automatic upgrade when the next version is released.

Happy pixellating!



**********************************************
* *
* Richard Biffl *
* 2922 28th Street, N.W. *
* Washington, D.C. 20008 *
* CompuServe 73607,3043 *
* *
**********************************************



DrawFill was written in Turbo Pascal and Turbo Assembler.

RAM-resident routines are from TSRUnit by Ken L. Pottebaum,
which accompanied his article, "Creating TSR Programs with Turbo Pascal,"
Dr. Dobb's Journal vol. 14 no. 5, May 1989.

DrawFill is a trademark of Richard Biffl.
Turbo Pascal and Turbo Assembler are trademarks
of Borland International, Inc.