CP/M/CPM_CDROM.iso/beehive/utilitys/pudd.arc/PUDD.DOC

Text File | 1991-08-11 | 25KB | 485 lines

******************************************************************************

                              P  U  D  D

                          PUblic Domain Draw

******************************************************************************

a program written in Turbo Pascal for the TeleVideo TPCi and 803 computers

author:               Greg Jackson
date:                 08/30/85
major interest:       anyone with Televideo 803, 803H, or TPC-1

software required:    to run PUDD.COM          :none
                      to create new PUDD.COM   :Turbo Pascal

contains:             A useful graphics drawing program
                      and some introductory screen files (*.scr)

hardware:             Epson printers are supported

legal mumbo:          This program is public domain.  If you try
                      to sell it you will burn in Hell in an
                      infinite loop.  There is no Reset button for
                      this situation.  Please keep the name of the
                      files the same when you pass this program through
                      the RBBS systems.  Please share this program with
                      others who have the above mentioned computers

updates:              Future versions are best shared through the
                        POWER BOARD @ [phone]
                      If the Power Board is down or you don't have
                      a modem, you may contact me directly....
                         Greg Jackson
                         1616 Capital Ave
                         Madison, WI 53705
                         [phone]
                      The best time to call is early evening.  Please
                      remember your time zone.
modfications.....
          10/85     added write functions and changed menus a bit  G.J
          11/85     added the c(U)rve function                     G.J

NOTICE.......
  This file is used by PUDD.COM for on-line help.  It should be on the default
  drive if you want (H)elp to work.  It can be left off if you need room.


Section 00           Documentation Sections

   The documentation is divided into numerous sections.  Each section has a
   specific number associated with it.

   1  General Instructions                        15 Circles and curves
   2  General Drawing
   3  The Arrow
   4  Entering text
   5  Filling areas
   6  Fill style and index
   7  Erasing
   8  Help files
   9  Screen file                                 94 How to compile
   10 Printing                                    95 (x,y) pairs & aspect ratio
   11 Write                                       96 Purpose of program
   12 Drafting                                    97 Turbo Pascal
   13 System crash                                98 Invitation to source code
   14 Drawing techniques                          99 Programming notes


Section 01           General Instructions

 Pudd stands for PUblic Domain Draw.  It is a generally useful and simple
 drawing program for CP/M Televideo computers with graphics capabilities.

   Some of the important things to note are....
     Screens saved are 20k in size
     Numeric lock must be ON to move the crosshair
     The only printer supported is the Epson series
     Source code is provided
     The program is free

 The general idea is simple, from the main menu you can select printing, file
 access, the graphic screen, or a menu which allows modification of all default
 values.  In the graphic mode the full screen is provided. To return from the
 graphic mode to the main menu just press the 'R' key.  All other functions
 available from the graphic mode are noted on the main menu.  Some of these
 functions may lead you to other sub-menus.  Most graphic functions are
 canceled by the same command that started them.  For example: to erase an
 area press 'E' then move the crosshair around.  When you have the area
 marked out press the 'E' again.  Some of the functions that work this way
 are e(X)tensive, (B)ox, and (E)rase.

Section 02        General Drawing

There are two positions to keep in mind while running pudd.  One is obvious,
if you have the crosshair turned on that is.  This is the crosshair position or
current curser position.  The other is the current screen position.

Both of these positions are initially set at (0,0).  Both positions are indicated
on the main menu.  The screen is seen as an x,y cartisean set in the first
quadrant.  The horizontal ranges from 0-639 and the vertical goes from 0-239.
All this means is that the lower left is position (0,0), the upper left is
(0,239), the upper right is (639,239), and the lower right is (639,0).

The crosshair position is changed every time the crosshair is moved.  It is also
changed when text is entered.  The current screen position is changed when
drawing is done.  This is seen by using the Draw command.  Draw will draw
a line from one position to the next and then set the screen position to
where the crosshair is.  Draw is great for making any kind of polygons.

The line command is similar to the draw command except the screen position
is not changed.  If you do a number of line commands while moving the
crosshair between each one, you will create a number of lines radiating from
a single point.  The arrow works in a similar fashion to the line.

The extensive draw command is a continous drawing function. You will leave a
line where ever you move the curser.  You may change the speed of the cross
hair movement but you may not change the line style.  Extensive drawing is
canceled by the (X) command.
Another way to change the current screen position is to set a point.  This will
set the screen position to where the crosshair is and light a single pixel at
that point.

Section 03   The Arrow

The arrow is drawn from the current screen position to the current
crosshair position.  In general the current screen position is the last
(P)oint set or the end of the last line (D)rawn.

The arrow is like the line only an arrowhead is put on the end of the line.
It is a bit slow because is does some trig functions while figuring the
arrowhead.  It was done this way to make the code easy to modify.  If you
want a longer, shorter, wider, or narrower it's a simple matter to modify
the default values in the source code.  If you're really motivated you can
make these defaults available in the program so they can be changed while
running pudd.  See programming notes if you're interested.

Section 04       Entering Text on the Graphic screen

Entering text is pretty simple.  While in the graphic mode, enter a 't' for
text. Then type anything you want. Both the back space and del key will work
as destructive backspaces. Writing over with spaces can be a quick way to
delete areas on the screen.

Section 05      Filling an area

An area is filled in the current fillstyle and index.  The area must be
defined by either the edges of the screen itself or by a solid line or area.
If you attempt to fill an area bounded by dotted lines you will have problems.

Section 06     FillStyle, index, and all that jazz........

If you are reading this only after having tried to understand this stuff by
reading the menus, you are probably frustrated.  Don't worry, I'll get you
through this.  The fillstyle and fill-index will affect both the fill and
block functions.  Basically, anytime you deal with an area as a whole.
There are 4 styles and 8 indices.  Always think of the style first:

--If you choose style `Hollow' then the index is meaningless. When you create
 a block with the block function, you will have a nice little hollow
 rectangle.  This also affects the fill function.  You will fill an area with
 nothingness.  If you think this is nonsense, you're right, since an area
 is defined as nothingness.  If effect, you are turning the fill function off
 by selecting a fill style of `Hollow'

--When you choose a style of `Solid' the index is also meaningless.  The block
 function will result in a solid block and the fill function will result in a
 solid area.

--Select the `Pattern' function and the index becomes interesting.  Each index
 will yield a different pattern when doing either a fill or a block.  The
 patterns are pretty bland and really result in 8 different shades of gray.
 The brightest of these yields the same result as selecting the `Solid' style.

--When you use the `Hatched' setting for style the index has a different
 meaning.  Now there are 8 different types of hatched patterns.  Each index
 will provide a different pattern.

Now that you've got this all down, the menu that you see when you (C)hange
the settings should make some sense.

Section 07     Erasing things on the screen

You can erase  everything
               a line or curve
               a point
               or a rectangular area

--To blow away everything you (W)ipe the screen.  You will be prompted to
 confirm this radical solution

--To erase a line, curve, or point you actually set the color to black and the
 mode to replace.  This means you are drawing with black.  If you have the
 mode wrong you will still be drawing in black but it may be ignored.  The
 functions work the same as they did before.  For example, if you want to
 erase a line then set a (P)oint at one end and go to the other end, then
 use either (D)raw or (L)ine.  Even the arrow can be blacked out by another
 arrow.

--To erase a rectangular area use the (E)rase feature. The first 'E' entered
 will begin the function. The move the crosshair around until you get the
 stuff surrounded that you want out. After you have the box in the right
 place just enter another 'E'. (E)rase is the easiest way to erase things.
 It also works on horz lines, vertical lines, and points, since these are
 really rectangular areas with one or both sides of dimension 1.

--To erase text you can enter spaces or backspaces over the top or else
 use the (E)rase feature to cut out the area.

--To erase the crosshair you use the (C)hange status to turn it off.

Section 08       The Help File

The file that came with this program called PUDD.DOC is used by pudd for on-
line help.  It is a standard text file.  As such you can add to it or subtract
from it as you please.  If the file has been edited so that the section numbers
are in the leading columns you will be able to read any section while running
pudd.  If you delete sections the program will merely respond with an error
message when you try to call them up.  If the file is missing entirely you
also get an error message but no other problems will occur.

Section 09       The Screen Files

Every time you save the screen you create a 20k file.  This is true even
if you are saving a blank screen.  The default file type is .SCR.  Since
these files are pretty big you might want to squeeze them with something
like NewSweep.Com.  If there is not enough room on the disk you may find
that the program will crash during a save. sorry.......

Section 10       Printing the screen

There are 3 styles of printing.  The first is pretty quick.  It is small
and in a horizontal format.  The second is vertical and has the correct
aspect ratio.  As a larger picture, it takes a bit longer.  The major
problem with the 2nd printout is that the horz lines have a different line
width than the vertical lines.

The third is the largest printout.  It takes twice as long as #2.
In addition to being the biggest, it also provides a balanced line width,
correct aspect ratio, and darker lines.

As of this date the only printer that is supported is the Epson and various
Epson clones.  If you want your printer supported but you don't know how to
program in Pascal, there is a way out.  All you have to do is buy me a printer
just like yours.  I intend to support all the printers I own. Right now all
I have is an Epson.  I would particularly like to find someone who would buy
me a laser printer.

Actually, I don't expect anyone to do this.  Since there are a number of
different printers out there I have commented the printing procedures
rather extensively.  It should be possible for even a beginning programmer
to get his printer working.  Please send any other printer installations
to the address listed at the head of the PUDD.DOC file.

Section 11     The write function

If you know what write is about you have no need to read this.  If you have
not used the write function I suggest you try it out, often.  Real often.
Write may turn out to be one of my favorite features.  One note though, it
seems to work better when larger integers are chosen.  Don't be afraid to
enter large numbers.

Section 12     Drafting (Pudd as a mini-CAD)

Drafting, as opposed to sketching or doodling, has quantitative vs qualitative
implications.  While Pudd is nothing like the real Computer Aided Design tools,
it can be used as a small scale drafting tool when used with printout #3.

Printout #3 provides hard copy where the screen is exactly 7.5" x 10".  With
this size each pixel on the screen represents a printed area 1/64" wide and
1/32" high.  For example, if you set the curser speed to 2, then each movement
of the curser represents 1/16" on the paper.  If you select the Box function
then press the left arrow 16 times, the up key 16 times, then complete the box
by pressing a second 'B', you will have created a box that will print out as
1" square when using printout #3.  Remember that the curser generally moves
two units left or right for every one unit up and down (see help on aspect
ratios).

Section 13     Screw Ups

There is a great deal of error trapping throughout the program.  Despite all
of this you may find some way of dumping out the program when you don't want
to.  This usually seems to happen when the screen is in the graphic mode.
Since cp/m operates in the text mode you will end up at the `A>' prompt
but not know it.  To force the machine into the alpha screen just press
the 'alt' key while you are holding down the 'shift' key.  If you do a
reset you will erase the screen.  If instead, you start up PUDD again you will
probably find the drawing still there.

One note, don't use the shift/alt trick to try to find out where you are
on the graphic screen by flipping to the alpha screen.  The Xpoz, Ypoz
positions that are on the main menu are only updated when you do the proper
mode change (ie: (R)eturn) from the graphic mode.

Section 14   Techniques for drawing

The combinations of modes, styles, and functions offer almost endless
combinations which provide a great number of techniques.  I have included
only a few here.  I would like to hear more from users of PUDD.

  To reverse image: Set fillstyle to pattern, fillindex to 7, and mode
    to overwrite.  Now everytime you draw a box you will get the negative
    of what you had before.  IE: white is black and black is white.

  Overlays: Using the file function of Overwrite screen you can create
   templates to draw within.  This can serve a similar function to the
   boilerplate approch to text editing on a word processor.

Section 15    Curves and other round things

  The (U) function will draw a circle or some portion thereof.  The
 position of the crosshair at the time you begin the function is taken
 to be the center of the curve or arc.  The curser should then be moved
 to the point where you want your arc to begin.  Any key pressed, other
 than a curser movement key or curser speed selection, will serve to
 select the beginning of the arc.  This second point also sets the radius
 of the curve.  A third point is needed to find the end of the arc.  This
 third point is used to find the angle but the radius remains the same as
 the distance between the first and second points.  If you select the
 third point at the same position as the second point (ie: arc begins and
 ends at same point) then you will be asked if you want a full circle or
 nothing at all.  Respond to your pleasure.  Arcs will be drawn ccw or cw,
 according to your wishes.  There is no default.


Section 94     How to compile

You should have PUDD.COM with the other stuff so it really is not
necessary to compile.  You will have to do it if you want to modify PUDD
or if you just want to see Turbo sweat it out on a medium size program.  At
last count there was ~2600 lines of source code.
  to compile
     1) have all *.pas files on the default drive
     2) load Turbo
     3) set (O)ptions to (C)om file
     4) set (S)tart address to 2432
     5) set (E)nd address to D942
     6) set (M)ain to PUDD
     7) compile

The only thing that is not obvious is the change in the start and end
address. These values are used for the TPCI (TelePort 1).
I have used a big array in the print2 and print3 routines (see pudd-04.pas)
which is put between the pascal library and the beginning of the actual
pudd code.  See your Turbo Pascal manual under "Execution of A Program File"
and "Absolute variables".  It explains why you should move up the start
address.

I have found that sometimes the default end address will be moved down
when you use a resident extension on your system (ie: EX.COM or others).  If
you find that the end address is not at D942 then move it up there.  Turbo
will look up to find what seems to be the end of memory.  If something is in
the way it will see a system that's too small.

If none of this makes any sense to you, don't worry. Just do it as described
and you should not have problems.

Section 95     The cartisean set and aspect ratios

If you remember anything from high school math you will recognize the screen
coordinates are like the coordinates used in the first quadrant of the
cartisean set.  The lower left corner is (0,0), the upper left is (0,239), the
upper right is (639,239), and the lower left is (639,0).  You will also
remember that lines between the points (0,0), (0,10), (10,10), (10,0) will
form a square.  This is a fine theory but there is a problem on your computer
screen.  Since there are so very many dots left to right and so few dots up and
down, the points I mentioned will not look very square.  The aspect ratio of
screen is about 3/4.  That means it's about 3/4 times tall as it is wide.  In
order to make a square square (or a spade a spade), it would require 3/4 as
many dots up and down as right to left.  Let's see......
                       3/4 x 640 = 480
Now the wizz kids out there will be quick to realize that the pixel (dot)
height of the screen, 240 dots, is exactly 1/2 of what we want.  This makes
a square out of (0,0), (0,10), (20,10), and (20,0).  Another way to see it is
that 2 x "actual horz distance" = "actual vertical distance".  For this reason
the curser moves two dots over for every one dot up or down.  This is true for
all curser movements except when the curser movement speed is set to one.  If
it were always true then you would never have access to half of the screen
(every odd dot).  You can check this out by using one of the diagonal keys at
different speeds.  At all speeds greater than 1 the line is pretty much a
45 degree line.  At a speed of one the slope is much less.  Keep this in mind
so you don't muck up your drawings.

The stuff you put on the screen can be pretty useful but not in an exacting
technical way.  Normally any technical work with a computer drawing program
will be done from hard copy.  Since we don't have any fancy digitizers to
play with the hard copy is what comes out of your printer.  With this in
mind you should be aware that the aspect ratio on the small printout is
not perfect.  We have stated that a block of 20 x 10 will be a square.
Lets call it 400 x 200.  On the small printout the aspect ratio is about
17% off.  This means you should not take exact slopes or ratios or other
relative measurements from the small printout.  The large printout has a very
good aspect ratio.  You should find a 400 x 200 square to be square on your
paper within a single printer point.

Section 96       Purpose of the program

 While this program is generally useful, it is not going to put the MacIntosh
 out of business.  Nor is it going to keep me from buying an Amega as soon as
 I have the $.  Drawing is only one of the purposes of this program.  I began
 writing PUDD, not only to get a drawing program, but also to get some practice
 in Pascal.  I hope that others get interested in the program for the same
 reason.  Recreational programming can be a lot of fun but amortization tables
 get a little boring after a while.  Since I find computer games about as
 exciting as TV's Bloops and Blunders, I had to find another outlet for my
 programming energies.  Pudd works well for absorbing personal energy. I would
 like to invite you to get involved in PUDD as well.

 One of the nicest things about a structured language like pascal is that you
 can add many procedures without having to deal with, or even understand, the
 main body of the program.  While this is frowned on in many circles, it is
 often the core of recreational programming. There is a lot of room left in
 the 64k memory. If you want to add a special purpose feature to your version
 of Pudd you need not read more than half a dozen short procedures in order to
 gain enough of an understanding to write your own procedures.  I invite you
 to give it a try.  Graphics programming can be fun.

Section 97     Turbo Pascal

Turbo Pascal is the greatest thing since a pocket on a shirt.  If you have an
interest in recreational programming, or any programming for that matter, but
all you know is Basic then you need Pascal.  I will not dignify Basic by trying to
compare it to anything else. One might as well compare Pig Latin to
Shakespeare. If you need to come to grips with real world computing then Pascal
is a great first step.  Pascal is the best introduction to structured
programming and provides an easy step to `C' (the language of Unix).

Turbo Pascal is an outstanding value.  I started programming on CP/M using
MT+ Pascal.  MT+ cost more than $300 and is a pain in the butt to run.  If
you are considering messing with Pascal, don't waste your time on MT+, JRT
Pascal, or any of the others.  I have heard a number of rationalizations for
stealing software.  Most of them are based on the high cost or low quality of
the software in question.  None of these apply to Borland products.  Get Turbo
but buy it, don't steal it.

Section 98     Source code

The source code for this program will always be available.  If you have
PUDD.COM but none of the *.pas file from whence it was created, you can
write or call to get the complete set of files.  See the beginning of the
PUDD.DOC file (that's what you're reading right now) for info.

Section 99     Programming notes

The source code is an amateur product.  I did this as a means to learning
pascal.  If you, as a more experienced programmer, find fault with the code;
I would appreciate your comments.

A primary consideration in the code is readability.  In a number of places,
this objective was considered more important than speed or elegance.  Taking
a top-down approach, the primitive graphics procedures are usually called
indirectly.  These are the things in files Tools#.pas.  They contain a lot
of machine language inline code and are not easy to mess with unless you know
a lot about the TeleVideo and machine language.  The most extensively commented
procedure is the print routine.  This was done to help those who need to modify
it to work on their printer.  If you get a modified version working on your
printer, please send it to me.  If you cannot do so, drop me a line.  I will
try to collect versions that run on as many printers as possible.

Other notes:

There are a number of places where trig is used.  If you have not worked with
angles in software before remember that all the functions work with radians,
not degrees.  If it's been a long time I'll prompt you....
      there are 2 pi (about 6.28) radians in each 360 degrees
      the slope of a line is (change in y)/(change in x)
      the inverse tangent of slope yields the angle in radians

While inverse tangent is not a standard pascal function, it is part of
Turbo Pascal. Thanks Borland!

The code is sort of a hacker special.  There are a number of global variables.
I tried to point these out where they occur but I might have missed one.  Don't
be too surprised if you also find an i,j,k or a temp declared which are never
used.

There is a bit of order to the include files listed in the main file,
PUDD.PAS.  The procedures generally reference those above them, as the order
of the list would imply.  The files TOOLS# are the most primitive and contain
direct references (through inline hex code) to the graphics procedures.
As you look down the list you will see general procedures that you may even
want to use elsewhere.  The files PUDD-##.PAS contain the procedures that
the main program calls.