Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d1xx/d191/blitlab.lha/BlitLab/README

Text File | 1989-03-14 | 9KB | 164 lines

BlitLab 1.3                        17 April 88

    This is release 1.3, which adds custom screen operation and
a blitter simulator, as well as an undo gadget and a log file.

    BlitLab is a program which lets you experiment with the blitter
to your hearts content, in relative safety.  It opens up a workbench
window with gadgets for all of the registers of the blitter, and allows
you to manipulate individual registers and perform blits on a magnified
bitmap.  This documentation is sketchy, but it probably won't get much
better.

    This program was written for a blitter presentation at the
BADGE meeting of 16 April 1987, and it met with such approval that I
decided to make it available over the net.  I wrote it for Manx C using
16 bit ints.  It should port to Lattice with a minimum of effort, but
it doesn't.

    The code itself may turn out to be interesting.  I wrote the
entire program in two days, but I tried to keep things clean and
modular.  Any comments on the code, either positive or constructive
criticism, is welcome.

    On to the program.  I'm going to describe operation of the
program starting in the upper left hand corner and proceeding across
and down.  I will not describe the operation of the blitter; that's
all in the file blit.tex.

    By default, the program opens up in a workbench window.  To
open a custom screen, invoke it with a `-c' argument.

    The large dark area in the upper left is the bit map we are
going to play with.  It has a width of 96 bits, or 12 bytes, or 6
words.  It has a height of 32 rows.  Remember these numbers well.
You can draw in this area with the mouse and the two gadgets in the
upper right.  The topmost gadget is the Point/Box gadget.  When set
to point, you can draw individual pixels on the screen by clicking on
the pixels with the select button.  When set to box, you can draw a
filled rectangle by clicking on the upper left hand pixel of the box you
wish to draw with the select button, dragging the mouse and releasing
the select button over the lower left hand pixel.  By using the right
mouse button with either Point or Click, you can clear instead of set
points.  Note that
this is not a paint program, and the interaction speed may not be as
fast as you are used to; no apologies.  It was only intended to draw
bits for the blitter.

    Below these two gadgets are two numbers.  The adrs number
holds the address of the word the cursor is currently pointing at,
relative to the beginning of the bit array.  (It is written as, for
instance, M+382, which means the address of the array plus 382 bytes.)
The shift value is the pixel, numbered from 0 at the left to 15 at the
right.  With these values, you can point at a pixel to get its address
to enter into a string gadget below.

    The Calc gadget looks at the values you have entered for the
blitter, and determines if any memory other than the bit array will be
modified.  If it will, it prints `Blit unsafe' on the title bar.  This
is a sanity check to keep you from crashing the system.  Carefully check
your values if this flag is on.  The fact that this gadget writes `Blit
unsafe' does not necessarily mean that the blit will destroy memory
outside of the array; careful use of a source operand and mask bits
might not pass this test but would be perfectly okay.  I have
allocated several extra rows above and below the bit array so minor
errors shouldn't crash the system.  Currently line mode is not checked,
so use it with care.

    The GO gadget performs the blit you have indicated.  After the
blit, the results are updated in the magnified bit array rather slowly.
It performs the same check performed by Calc before executing, and
complains similarly.  You can override the complaint by clicking on the
GO gadget again.

    The UNDO gadget restores the bitmap window to its state before
a blit.  Useful to do a blit, undo it, and redo it after changing
something.  Also helps recover from your errors.

    The Real/Simul gadget determines if the real blitter is used,
or if instead the blitter simulator is used.  The simulator is slightly
slower, and does not work in line mode, but it allows you to trace
operation of the blitter to a log file.

    Underneath the magnified bit map, on the left, are four gadgets
labeled SX, SY, EX, and EY.  These bits get the starting and ending
points for the line you wish to draw.  The X values should range from
0 to 95; the Y values from 0 to 31.  These are not checked.  Be aware
that these are not blitter registers; they are simply values that the
program will use in calculating the actual blitter register contents
necessary for the line draw.

    The (line)/LINE gadget turns on line mode.  The Setup gadget
takes the SX/SY/EX/EY values, and sets up most of the blitter registers
to draw the line automatically.  It does not set up the function
register, because there are different ways to draw lines.  For a solid
line, use ~AC+A; for a textured line, use ~AC+AB; for an XOR line, use
~AC+A~C, for instance.  It does not perform the blit, however.  Note
that if you want to draw a new line, you need to change the appropriate
SX/SY/EX/EY values, then click Setup, then click GO.

    The next two gadgets, W and H, hold the size of the current
blit.  The W value is in words, and the H value is in bytes.  Legal
values range from 1-64 for W, and 1-1024 for H.  (Of course, the useful
range within this program is much smaller.)

    Next to the H gadget are gadgets for the DESC, FCI, IFE, EFE,
SIGN, and OVF bits of the blitter.  These can get set or cleared by
selecting them.
Underneath these gadgets is the Function gadget.  In this gadget you
enter the function you want to perform.  0 is clear all, 255 is set all,
and other combinations can be entered directly as minterms.  For
instance, the A~C+~CA presented earlier means exclusive or the A and C
bits for the destination.  To the right of the Function gadget, you will
find the Log File gadget.  Type a name in this gadget to accumulate a log
file; a null name will result in no file.

    The lower left hand corner contains the actual blitter registers
and their values in hexadecimal.  These are the values that are fed to
the blitter when you select GO.  As you enter new numbers into the string
gadgets corresponding to blitter registers, these values will change to
reflect the new values.  (Actually, they will only change if you hit
carriage return after entering the numbers into the string gadget; if you
simply select another gadget after entering data into a string gadget, the
old value will stay displayed until you select CALC or GO.)  This can be
used to calculate minterms, for instance.  Entering ABC+A~B~C+~AB~C+~A~BC
into the Function gadget hitting return will put 96 in the least
significant eight bits of CON0; this is the hexadecimal value reflecting
the above minterms.

    At the lower right is a table of string gadgets.  Each row is for
a single DMA channel.  The first column is the USE bit; is that channel
on or off?  Y means on, N means off; selecting the gadget toggles it.  The
next column contains the start address for DMA.  These numbers (as in the
remaining string gadgets) can be entered in decimal, hexadecimal (preceded
by a $), binary (preceded by a %), or as an offset from the start of the bit
array (preceeded by M+).  M alone represents the beginning of the blit
array.  The third column is the modulo value which is added to the DMA
channel pointer at the end of each row; this value is in bytes and can be
negative.  The fourth column is the data register; if a channel is turned
off, its data register can be preloaded with a value, and then it functions
as a constant.  For instance, to fill a block of memory with the value
$E931, simply preload the A data register with this value, turn on only the
D channel, and blit with the function A.  Finally, the last column is the
amount to shift the A and B operands, to the right, before using them.
Finally, in the lower left corner of the DMA channel box are string gadgets
for AFWM and ALWM.

    This program has been tested fairly carefully.  Therefore, if the
blitter appears to do something it shouldn't, you probably have set up the
registers wrong.  Remember, the Amiga blitter is a word blitter, not a bit
blitter.  It can be made to look like a bit blitter with some work.  It is
possible, however, that errant blits can muck up some system memory, or
some internal variable memory, so if things really seem awry, reboot and
go back into the program.  Try the same values again, and see if they work
this time.

Tomas Rokicki
Radical Eye Software
Box 2081
Stanford, CA  94309
[phone]
[e-mail]
...lll-crg!decwrl!polya.stanford.edu!rokicki