CHAPTER 10 DIFFERENCES BETWEEN DIGLIB AND Amiga-DIGLIB 16
CHAPTER 11 Amiga-DIGLIB COMMON BLOCKS 17
11.1 GCDCHR.PRM 18
11.2 GCVPOS.PRM 19
11.3 PLTCLP.PRM 20
CHAPTER 12 Amiga-DIGLIB STANDARD DEVICE DRIVER NOTES 21
12.1 HIRES INTERLACED DRIVERS 21
12.2 POSTSCRIPT DRIVER 21
CHAPTER 13 PROGRAMMING EXAMPLE 22
CHAPTER 14 SUBROUTINE DESCRIPTIONS 24
14.1 STRINGS 24
14.2 FUNCTION LISTING 25
14.3 ALPHABETICAL LISTING 28
CHAPTER 15 GUIDE TO WRITING A DEVICE DRIVER 103
15.1 INTRODUCTION 103
15.2 STANDARD DEVICE DRIVER FUNCTIONS 104
15.3 EXTENDED DEVICE DRIVER FUNCTIONS 107
15.4 DEVICE DRIVER EXAMPLES 111
15.5 DEVICE DRIVER ARGUMENTS 111
.fo=/-#-/
.pn=1
CHAPTER 1
THE COMMERCIAL
Amiga-DIGLIB is a free product brought to you by Hal R.Brand and Craig R. Wuest courtesy of the Lawrence Livermore National Laboratory. Since Amiga-DIGLIB was provided to you free (or nearly so), it is my sincere hope that Amiga-DIGLIB will be freely circulated, and enhancements will be also. To aid in this effort of mutual exchange, please send me (Craig Wuest, L-84) any Amiga-DIGLIB software you believe would be of general use to the Amiga-DIGLIB user community. I will evaluate it (and possibly modify it) and will distribute and maintain it if I also believe it is worth distributing with Amiga-DIGLIB.
NOTICE
This computer code material was prepared as an account
of work sponsored by the United States Government.
Neither the United States nor the United States
Department of Energy, nor any of their employees, nor
any of their contractors, subcontractors, or their
employees, makes any warranty, express or implied, or
assumes any legal liability or responsibility for the
accuracy, completeness, or usefulness of any informa-
tion, apparatus, product or process disclosed, or rep-
resents that its use would not infringe privately
owned rights.
The version of DIGLIB provided with this document is an enhanced and debugged version of the original copy that I received from Dr. Wuest.
A Polar plotting routine has been added, Amiga display generation has been made algorithmic, and numerous bugs, mostly related to the way that AbSoft Fortran for the Amiga does memory allocation, have been fixed. At the time of this writing, Dr. Wuest has indicated that he is too busy to adequately support Diglib, so I have chosen to do so in order to satisfy my own needs. -- Jim Locker, SofTech Inc.
CHAPTER 2
INTRODUCTION
Amiga-DIGLIB is a port of the popular graphics package DIGLIB written by Hal Brand for use on PDP-11's and VAX's. The package has been ported to the Amiga environment using Absoft AC/Fortran. I have taken Hal's advice and plagiarized all I could including most of this documentation manual. If you have any problems with DIGLIB contact Hal Brand, if you have problems with the Amiga port contact Craig Wuest. Conversion of existing programs from DIGLIB to Amiga-DIGLIB should be very easy. Chapter 10 contains information pertaining to the differences between the two packages.
Amiga-DIGLIB (Amiga Device Independent Graphics LIBrary) is a collection of FORTRAN callable subroutines designed with the following goals:
1. Easily usable by the casual graphics programmer for 2D
and limited 3D plotting.
2. Device independent (as much as possible).
3. Small and reasonably fast.
4. Device drivers are as simple as possible, and therefore
easy to write, and device drivers may be written in FOR-
TRAN when desired.
5. Compatible (as much as possible) with PLTLIB. This is a
historical artifact that no one now needs be concerned
with except former PLTLIB users.
6. Maintainable.
7. Compatible with AmigaDOS, and Intuition.
8. Compatible with Absoft AC/FORTRAN (F77).
Drivers are being added to Amiga-DIGLIB as the need arises. Before you reject Amiga-DIGLIB because of the lack of a graphics device driver, or you embark on writing a graphics device driver for Amiga-DIGLIB, please check the Amiga-DIGLIB distribution kit as there may be a driver there that has not yet been included into the installation procedures and documentation. Drivers all start with the letters "GD" and then generally have the product number, i.e. GD13HI is the High Resolution Interlaced driver for 13" monitors, such as the Amiga 1080. If you spot a likely candidate, just list the file and the documentation at the top will confirm or deny your suspicion. If you don't find the driver you need, then read chapter 15 and coerce an existing driver that is close into the driver you need. Remember, Plagiarize, plagiarize, plagiarize!
CHAPTER 3
INSTALLATION GUIDE
3.1 MACHINE REQUIREMENTS
The programs provided in this package require an Amiga, or Turbo Amiga. A monitor is also required for plots to be viewed on the screen. A minimum of 512kb of RAM is required. Extra RAM memory or a hard disk is strongly recommended, but then anybody attempting to compile Fortran would benefit from the decreased compile and link time anyway. Turbo users should compile any sources with the -p option. Statically linking main programs to Amiga-DIGLIB is highly recommended. Significant speedup in display of plots will be achieved in this way. Linking from the floppy disks can take quite a long time so be prepared for a wait unless you have enough RAM to work with.
3.2 DISTRIBUTION DISKS
This package is distributed on one 3.5 inch floppy diskette, labeled DiglibDisk.
DiglibDisk:
README.DOC Any late breaking news.
AmigaDIGLIB.doc The documentation for
Amiga-DIGLIB.
AmigaDIGLIB.fmt Scribble! format file
COMPILE.BAT Compilation program for
Amiga-DIGLIB.
COMPILE1.BAT Compilation program for
Turbo-Amigas.
MAKE.BAT A batch file used to build
Amiga-DIGLIB library.
#?.FOR The Amiga-DIGLIB library source
files.
#?.PRM INCLUDE files containing
Amiga-DIGLIB common blocks and
variable declarations.
GRAPH.INC INCLUDE file for amiga graphics.
INTUIT.INC INCLUDE file for amiga intuition.
EXEC.INC INCLUDE file for amiga executive.
amiga.sub Enhanced version of the Absoft
release, with SetRGB4 activated.
loc.sub Needed for DIGLIB.
SKELTN.FTN The skeleton for a device driver.
3.3 INSTALLATION INSTRUCTIONS
1. Copy the contents of the disk to RAM:. F77
and F77LIB can also be copied to RAM: for faster execution.
2. The COMPILE batch file assumes that Amiga-DIGLIB is to be
installed on the current directory, preferably RAM:,
if this is incorrect please edit COMPILE.BAT. Then copy the
COMPILE batch file correct for your machine into RAM: Type:
EXECUTE COMPILE.BAT
The program will compile and produce .SUB object code for
all the Amiga-DIGLIB sources.
3. Use the MAKE batch file to create and assemble the object
modules into the library DIGLIB. Type:
EXECUTE MAKE.BAT
The MAKE batch file assumes that the object files are in
the current directory and will produce the library DIGLIB
in the same directory.
3.4 DEVICE NUMBERS
Amiga-DIGLIB uses device numbers to refer to graphics devices. The correspondence between device number and physical graphic device is determined by the subroutine GSDRVR. Basically, GSDRVR is a multiplexer (or dispatcher) that directs the graphic commands to the currently selected device driver. Each installation will have its own correspondence between device numbers and graphic devices. It is very strongly recommended that the device numbers be assigned starting with 1 and continuing through the integers to the Nth device numbered N. This is most straight forward numbering scheme, and the best scheme for making use of GSDNAM. Also, any other scheme will break SELDEV.
Each installation may have its own correspondence between device numbers and graphic devices. Amiga-DIGLIB provides on-line access to the device names that correspond to the device numbers through the GSDNAM subroutine. The most common use of GSDNAM is to construct menus at execution time of the devices available.
This release of Amiga-DIGLIB supports a standard Amiga CRT driver. This driver, known as GD13HI, employs algorithmic screen generation based upon information contained in the system structure GfxBase. Thus, it supports all Amiga CRTs, including PAL and NTSC as well as the new higher resolution display modes. The driver requires version 1.2 or higher of AmigaDOS. There is no need to alter GSDRVR or GSDNAM unless you need to support a device other than this. Future device drivers under development include a PostScript driver for Apple Laserwriter Printers and an HP7475 Pen Plotter driver.
Thus, any program that makes proper use of GSDNAM can be linked with an Amiga-DIGLIB with any array of devices and still present the proper menu of devices available.
The person who installs Amiga-DIGLIB can edit GSDRVR to properly reflect the target system configuration. This means editing both subroutines contained in the file GSDRVR.FOR.
3.5 EDITING GSDRVR
The file GSDRVR.FOR must be edited to correct the subroutines GSDRVR and GSDNAM to match your installation of Amiga-DIGLIB. The subroutine GSDRVR makes the procedural connection from device numbers to graphics device drivers and the subroutine GSDNAM makes the procedural connection from device numbers to graphics device names.
GSDRVR has two main functions: 1) make sure the selected graphics device driver exists, and 2) call the selected graphics device driver. As stated before, the correspondence between device numbers and physical graphics devices is entirely up to you!!! You can choose to use any number you wish to represent a particular physical graphics device. However, I very strongly suggest that you arbitrarily assign your most used graphics device the number 1, then assign then next most often used device the number 2, etc. for all your graphics devices. This makes writing GSDRVR easier (you can use a GOTO instead of a bunch of IFs). It is also consistent with the scheme that nearly everybody uses. Also, it is the only way to make any real use of the GSDNAM subroutine.
The function that subroutine GSDRVR must perform is:
* If "IDEV" is not a valid graphics device number, then
* if "IFXN" is 7 (Get Device Characteristics), then
set second argument (X) equal to zero,
* return
* Pass control to the graphics device driver you want
selected by the number found in "IDEV". (This is usually
done by a computed GOTO.)
The subroutine GSDNAM is actually optional, but strongly recommended. GSDNAM only function is:
* If "IDEV" is a valid graphics device number, then
* return the device name as an Amiga-DIGLIB string of 39
characters or less
* Else
* return a "null" (zero length) string as the device
name.
A sample version of GSDRVR and GSDNAM is provided as part of the distribution kit. It is suggested that the sample file GSDRVR be edited rather than starting anew.
CHAPTER 4
Amiga-DIGLIB DIVISION
Amiga-DIGLIB has been divided into two main parts: the low level package, and the high level package. The low level package is concerned with simple but general graphics functions, i.e. drawing lines and characters. The high level package is concerned with producing two dimensional plots suitable for scientific data presentation. The high level package is built upon the low level package and is a good example of the use of the low level Amiga-DIGLIB routines.
The low level package routines are: DEVSEL, BGNPLT, ENDPLT, RLSDEV, and all routines that start with the letter "G". In fact, routines that start with the letters "GD" are drivers, "GC" are common block definitions, and "GS" are general graphics routines. The four previously enumerated routines that don't begin with the letter "G" are basically device control.
The high level package routines are named according to the function they preform, and so follow no convention. Care should be taken to avoid possible routine name conflicts with these routines. The most like candidates for name conflicts are: SCALE, SYMBOL, TRACE, and CURVE.
In addition to the standard high level package routines documented here, Amiga-DIGLIB is distributed with some extra high level graphics routines. The most notable are PURJOY and CONTOR. These routines provide for 3D surface display and contour respectively. They are documented in the code file. They are not officially supported as part of Amiga-DIGLIB, but I have much confidence in them, and I will try to correct any bugs reported.
CHAPTER 5
Amiga-DIGLIB COORDINATES
Amiga-DIGLIB makes use of three coordinate systems, and Amiga-DIGLIB drivers make use of one additional coordinate system. The coordinate systems are:
1. World coordinates,
2. Virtual coordinates,
3. Absolute coordinates (expressed in centimeters),
4. Device coordinates.
Only virtual and world coordinates are normally accessible to application programs. Absolute coordinates are used as input to Amiga-DIGLIB device drivers and are subject to clipping to the target device drivers screen space. Device coordinates vary from graphics device to graphics device and are generated by the appropriate Amiga-DIGLIB graphics device driver.
World Coordinates
World coordinates are provided through the "high level" graphics subroutines. World coordinates may have any units the user chooses. World coordinates are converted to virtual coordinates using the subroutine SCALE. In most instances, user written plotting subroutines need never call SCALE.
Virtual Coordinates
Virtual coordinates is the basic coordinate system of Amiga-DIGLIB. All the low level graphics subroutines work in virtual coordinates. All character generation is done in virtual coordinates. Virtual coordinates are converted to absolute coordinates before being sent to the graphics device. The virtual coordinates are first rotated. These rotated values are then scaled independently. Finally, independent translation factors are added.
By default, the rotation is zero degrees, the X and Y scale factors are set to 1.0, and the X and Y axis translations are set to zero. Thus, by default, absolute and virtual coordinates are identical. By providing a built-in mechanism for rotating, scaling, and/or translating coordinates, a plot generated for a particular device can easily be redisplayed on another device regardless of the size of the plotting areas of the graphic devices. In addition, it becomes trivial to rotate the entire plot by some arbitrary angle, or even to produce a mirror reflec tion of the plot. It is also very simple to "pan" and "zoom" over a large plot or collection of plots (see GSETDP and GSWNDO). Since "pan" and "zoom" are implemented by Amiga-DIGLIB, the zooming is done to the precision of real numbers, and so detail is retained during the zooming process.
Virtual coordinates can also be used for window/viewporting. Thus, you can use any portion of the screen and have the virtual coordinates run between any values you choose. (See GSWNDO for more information).
Absolute coordinates
Absolute coordinates are the only coordinates passed to the graphics device drivers. During the GIN operation, the device driver is expected to return absolute device coordinates. Absolute coordinates are chosen so that the point (0.0,0.0) is at the lower left corner of the graphic device. The upper right corner is the point (XLENCM,YLENCM) where XLENCM and YLENCM are the X axis (width) length in centimeters, and the Y axis (height) length in centimeters, respectively. (To find the value of XLENCM and YLENCM, use the Amiga-DIGLIB functions GSXLCM() and GSYLCM(), respectively). Thus absolute coordinates are interchangeable with centimeter coordinates on the device. Line style generation is done by Amiga-DIGLIB software in absolute coordinates. It should be noted that Amiga-DIGLIB filters the absolute coordinates before they are sent to the graphic device drivers so that only those coordinates representable on the graphics device are ever transmitted to the graphics device driver. Amiga-DIGLIB also filters out unnecessary "moves" so that only those moves necessary are sent to the device driver. This improves device performance, but means that "moves" are buffered by Amiga-DIGLIB, and so GSMOVE (with or without ENDPLT) can NOT be used to position the "beam" on graphic terminals.
CHAPTER 6
CHARACTER PLOTTING
Amiga-DIGLIB provides a number of subroutines and functions to aid you in plotting characters and character strings. Amiga-DIGLIB supports character string plotting through the GSPSTR subroutine. GSPSTR plots the character string using characters of the current size (height) and orientation. These parameters are set via the GSSETC subroutine. Sometimes, it is nice to know what the width of the characters is for centering purposes and the like. Amiga-DIGLIB provides a single function, GSLENS, which returns the length of the string argument it was given.
Amiga-DIGLIB uses a simple algorithm for plotting strings. The first character of the string is plotted in the current size and orientation with the bottom left of its character cell being the last specified coordinate. Thus, to plot a string whose first character's character cell is at position (A,B), call GSMOVE(A,B) then GSPSTR(string). This gives left justified strings (when plotted horizontally - rotation of zero degrees). The function GSLENS can be used for plotting centered and right justified strings.
Remember that Amiga-DIGLIB supports descenders. Thus, a lower case character that is a descender (g,j,p,q,y) will dip below the character cell. Thus, a good spacing for lines of graphics text is twice (2X) the character height. Tightly spaced lines can be placed at 1.5X the character height.
Finally, the Amiga-DIGLIB stick font is mechanically spaced, that is, all the characters have the same width. However, the alternate fonts available under VMS are proportionally spaced. Thus, religious use of GSLENS is required, and many simple character placement calculations that worked well with the Amiga-DIGLIB stick font will have to be upgraded to properly use the alternate fonts.
CHAPTER 7
HANDLING DEVICES OF DIFFERENT SIZES
Amiga-DIGLIB uses virtual coordinates as the base level interface coordinate system. Absolute coordinates are never used by the user and should generally be forgotten. This is especially true when the transformation from Virtual to Absolute coordinates is the default transformation because in this case, Virtual coordinates are identical to Absolute coordinates. Since most users operate in this mode, they can think of virtual coordinates as being screen coordinates and need never worry about Absolute coordinates.
Amiga-DIGLIB's use of Virtual coordinates (corresponding usually to centimeter screen coordinates) has advantages and disadvantages. By acknowledging the true device size, users can draw circle that truly appear to be circles and not ellipses. (Note: this requires a properly adjusted graphics device.) It also has the advantage of allowing drawings that must be "to scale" to be drawn as such without any trickery.
The disadvantage of using virtual coordinates is lack of device independence in codes that use absolute numbers for coordinates. For example, if a user does a GSMOVE(25.0,25.0) followed by a GSDRAW(30.0,30.0), then this line will appear only on those graphics devices that are larger that 25.0 cm. square. Most likely, what the user wanted was to draw a line in the upper right hand corner of the device regardless of its size. For this type of approach, the "normalized" coordinate system used by SIGGRAPH-CORE is best suited. Amiga-DIGLIB allows you to work in a normalized coordinate system if you wish by providing two functions,GSXLCM and GSYLCM, that return the currently selected device's X axis length and Y axis length in centimeters respectively. Because virtual coordinates usually are screen centimeters, thesefunctional values can be used to scale the "normalized" coordinates to virtual coordinates. For example, a program section to draw a box enclosing the lower left 25 percent of the screen could be written as:
X50 = 0.5*GSXLCM()
Y50 = 0.5*GSYLCM()
CALL GSMOVE(0.0,0.0)
CALL GSDRAW(X50,0.0)
CALL GSDRAW(X50,Y50)
CALL GSDRAW(0.0,Y50)
CALL GSDRAW(0.0,0.0)
Note that the upper right corner of a box that encloses 25 percent of the screen is at the middle of the screen, thus the factor 0.5! If one wanted the largest square that could fit on the screen:
SQ = AMIN1(GSXLCM(),GSYLCM())
CALL GSMOVE(0.0,0.0)
CALL GSDRAW(SQ,0.0)
CALL GSDRAW(SQ,SQ)
CALL GSDRAW(0.0,SQ)
CALL GSDRAW(0.0,0.0)
Thus, Amiga-DIGLIB can easily handle devices in a device size independent manner, while at the same time allowing the user to make allowance for the device size and aspect ratio.
Amiga-DIGLIB's high level package (MAPSIZ, MAPIT, CURVE, etc.) make allowances for device size even easier. Here, MAPSIZ and MAPSZ2 allow the user to specify screen locations as a percentage of full screen size in both the X and Y directions.
A final problem incurred with Amiga-DIGLIB and varying device sizes is the axes produced by MAPIT will vary in length depending on the device size. Normally, this is not a problem, however, in some cases, it is necessary or desirable to have the X axis produced by MAPIT be the same on-screen length as the Y axis produced by MAPIT. This can easily be done by making the difference between the X length of the plotting box and the Y length of the plotting box equal a "magic number". This magic number comes from the way Amiga-DIGLIB allows space for the axis frame title, tick marks and labels, axis labels, etc. Thus, this "magic number" is not a constant, but must be computed given the character size and tick length that will be used by MAPIT. The following code computes this "magic number" into the variable YGRTR and then allocates as much of the screen as possible, while requiring the X axis length from MAPIT to equal the Y axis length.
INCLUDE GCDPRM.PRM
...
CSIZE = GOODCS(0.3)
TICKLN = 0.9*CSIZE
WIDTH = GSLENS('0'//CHAR(0))
XBORDR = 0.25/XS
YBORDR = 0.25/YS
YGRTR = 4.25*CSIZE+AMAX1(CSIZE/2.0,TICKLN) -
1 (1.5*(ILABSZ()+0.25)*WIDTH+AMAX1(0.0,TICKLN)) +
2 2.0*(YBORDR-XBORDR)
SIZE = AMIN1(GSXLCM(),GSYLCM()-YGRTR)
CALL MAPPRM(0.0,SIZE,0.0,SIZE+YGRTR,CSIZE,
1 TICKLN,.FALSE.)
CALL MAPIT(XMIN,XMAX,YMIN,YMAX,'X'//CHAR(0),
1 'Y'//CHAR(0),'TITLE'//CHAR(0),16+32+256)
Note that ILABSZ is an undocumented function known only to the internals of the Amiga-DIGLIB high level package. Note also, that MAPIT has been called with the ragged axis flags set so that the axes will end where desired in most cases. However, since MAPIT sometimes likes to extend ragged axis when they end very near tick marks, it is necessary to override this feature, which is what the additional value of 256 does. Remember, all this is only useful if you are careful to choose (XMAX-XMIN) = (YMAX-YMIN)!!!!! Also, you will get more pleasing axes frames if you choose XMIN, XMAX, YMIN, and YMAX so that they are nice round numbers.
Finally, note that YGRTR is the magic number for the case where there is to be no second Y axis. When there is to be a second Y axis, then use YGRTR2 as given below:
Obviously, in the computation of YGRTR and YGRTR2, the AMAX1 operation is not necessary as the previous code has chosen TICKLN to be greater than zero. However, the AMAX1 is needed for generality since negative tick lengths are permitted by MAPPRM and MAPIT - they yield plots where the tick mark sticks into the plotting area.
CHAPTER 8
INTERACTIVE USE
Amiga-DIGLIB is designed to make interactive graphics very easy. The drivers were designed to make sure that graphics terminals behave well in an interactive environment, and Amiga-DIGLIB itself has a number of routines for supporting interactive graphics. The most commonly used subroutine with interactive graphics is ENDPLT. This subroutine should be called when ever it is necessary for the user to observe the entire plot. Remember that Amiga-DIGLIB buffers graphics commands to provide increased performance (also necessary for interactive graphics), and ENDPLT forces any buffered graphics commands to the graphics device. Thus, before a program asks the user questions that require him to make decision from the graphics, the program must call ENDPLT to ensure that all the graphics have been displayed.
The most commonly used interaction, however, is not questions, but graphics input. Not all devices support graphics input, but most do. Amiga-DIGLIB provides two methods of graphical interaction. The first follows the old 4010 GIN protocol where a cursor is displayed whenever graphics input is desired, the cursor is flown around by the user, and the GIN operation is terminated by the user pressing a terminal key. In this mode, Amiga-DIGLIB returns the virtual (or world) coordinates of the digitized point selected, and the ASCII character struck that terminated the GIN sequence. This mode of graphics input is accessed through the GSGIN subroutine.
The second form to graphics input makes use of the "buttons" or "switches" common found on the pointing devices of many new graphics systems such as joysticks, mice, track-balls, digitizing pads, etc. In this interaction mode, a cursor is displayed and is flown around by user interaction with the pointing device. However, unlike the 4010 GIN, the operation is terminated by the user "pressing a button" (more generally, changing the state of the buttons or switches) on the pointing device. The new state of the buttons or switches is returned to the caller. This mode of graphics input is accessed through the GSCRSR subroutine.
It should be noted that not all devices are capable of supporting either or both of these graphics input operations. Thus, they are not required of an Amiga-DIGLIB device driver. However, the utility of graphics input is such that it is implemented whenever the graphics device supports it. The main problem is which form of graphics input is implemented. Amiga-DIGLIB takes some of this worry off the programmer by supplying a subroutine, GSINPT, that uses GSCRSR if available, of if not, uses GSGIN if available. The only limitation of GSINPT is that only the X,Y coordinates are selected and a binary selection flag" is returned to the user.
Finally, Amiga-DIGLIB supports graphics input from world coordinates through the subroutines CURSOR and GRAFIN. CURSOR uses GSGIN and GRAFIN uses GSINPT and only differs from them in returning world coordinates instead for virtual coordinates.
CHAPTER 9
PLTLIB COMPATIBILITY
PLTLIB was an early graphics package that Hal Brand distributed. It worked only on the Tektronix 4025 and 4027 graphic terminals. This section is included only for those PLTLIB users that wish to convert to Amiga-DIGLIB. Readers who never used PLTLIB are strongly advised to ignore this section.
As was mentioned before, Amiga-DIGLIB is largely based upon PLTLIB. Most of the high level subroutines (those that work in world coordinates) are unchanged from the point of view of the caller. The low level graphics (those that work with virtual coordinates) are similar to PLTLIB, but codes that made heavy use of PLTLIB low level subroutines will definitely need modification.
The following correspondence exists between PLTLIB and Amiga- DIGLIB:
PLTLIB Amiga-DIGLIB equivalent
-------- -----------------------
ALLOCG MAPPRM,MAPSET,MAPSIZ,PLTBOX,FULMAP
ALLOCW none
CCOLOR GSCOLR
CLLINE CLLINE
COMMNT none
CURSOR CURSOR
DFNCOL none
DRAW GSDRAW
ERASEG BGNPLT
ERASEW none
GIN GSGIN
LABLE GSPSTR
MAPIT MAPIT
MINMAX MINMAX
MIXCOL GSDRGB
PLTMTY ENDPLT
POINTC POINTC
POINTS POINTS
POSNB GSMOVE
RPOSNB none (GSMOVE)
SCALE SCALE
SETLIN GSLTYP
TRACCY TRACCY
TRACE TRACE
TRACEC TRACEC
TRACEY TRACEY
TXTCOL GSCOLR
VECTOR none (GSDRAW)
Those users who liked the ability of PLTLIB to fully manipulate the 4025 will probably be disappointed with Amiga-DIGLIB. In the name of device independence the total control over the 4025 afforded by PLTLIB was dropped by Amiga-DIGLIB. Amiga-DIGLIB always (and uncontrollably) allocates 30 lines of workspace window, and uses lines 1 thru 30, columns 1 thru 80 for the graphic region. Amiga-DIGLIB then places multiple plots within the graphic region by using translation factors. Amiga-DIGLIB's strong point over PLTLIB is the device independence. If you only have 4025s and expect that 4025s will be your only graphics device, then PLTLIB may be a better choice than Amiga-DIGLIB.
NOTE
You can modify the placement of the graphics area in
the workspace, but it must remain 30 lines by 80 col-
umns. Thus, after calling "DEVSEL" you may send the
4025 a command to erase the workspace and redefine the
graphics area somewhere else. For those wishing to
modify the size of the graphics area, I suggest you
contact Hal R. Brand.
CHAPTER 10
DIFFERENCES BETWEEN DIGLIB AND Amiga-DIGLIB
The package Amiga-DIGLIB is a port for DIGLIB version 3 taken from the NESD VAX. There are very few known differences between the two packages. If you find any incompatibilities please let me know about them.
1. All real variables passed to Amiga-DIGLIB must be defined
as REAL*4, this is the default for the Absoft AC/Fortran
compiler.
2. All integer variables passed to Amiga-DIGLIB must be de-
fined as INTEGER*4, this is the default for the Absoft
AC/Fortran compiler.
3. There is no support for multiple fonts in Amiga-DIGLIB
(i.e. GsFont is not available).
4. There is support for the user to define the displayed
color corresponding to a color number (i.e. GsDrgb is
available). The hue/lightness/saturation method of de-
fining color is not supported on the Amiga.
5. All character arrays and strings must be defined as zero
terminated. This is done by following the last quote of
the definition by a //CHAR(0) (// denotes character con-
catenation).
STRNG = 'THIS A ZERO TERMINATED STRING'//CHAR(0)
6. Amiga-DOS does not support a screen dump. However there
are public domain screen dump routines available as well
as commercial packages. I will attempt to evaluate a PD
screen dump routine for inclusion with the Amiga-DIGLIB
package.
CHAPTER 11
Amiga-DIGLIB COMMON BLOCKS
Amiga-DIGLIB comes with a number of files with the extension "PRM". These files are common block descriptors used by Amiga-DIGLIB. Some of them are useful to application programmers. The PRM files that may be of use are:
1. GCDCHR.PRM - Current device parameters
2. GCVPOS.PRM - Current position in virtual coordinates
3. PLTCLP.PRM - Limits chosen by MAPIT
4. GCBIG.PRM - Master Common and variable declaration
block to be INCLUDEd in the user's main
program. F77 does not explicitly save
variables in COMMON from one subroutine
to the next unless the SAVE statement is
used or all the COMMONs are declared in
the user's main program or the -h option
is used when compiling all the sources in
DIGLIB.
5. GCCOMN.PRM - Common blocks and variable assignments from
GCBIG.PRM. Used when a main program needs to
separate the character stroke data block from
the COMMON statements because of EQUIVALENCE
statement ordering in the program
6. GCDAT.PRM - Character stroke data block from GCBIG.PRM. See
GCCOMN.PRM for usage.
Users would be best off to use the editor to insert these files into their sources.
The following list is not necessarily a complete list of all the available device drivers. As with most software projects, Amiga- DIGLIB suffers from the problem that the software advances faster than the documentation. Thus, users are strongly encouraged to look at all source files beginning with the two letters GD as these source files will contain the device drivers before concluding that Amiga-DIGLIB has come to you without a particular driver.
12.1 HIRES INTERLACED DRIVERS
The hires interlaced driver is capable of displaying sixteen colors on a 640x400 screen. The screen can be dragged down or switched to the back at any time by using the appropriate gadgets. It is necessary to set the stack up to at least 50000 to avoid spurious crashes. Also in the event of a heap space overflow message you should set the heap of an executable program up to 100000. Finally, the Amiga can only support a few open interlaced screens before it runs out of chip memory. Keep this in mind when writing programs that open more than one screen or window at a time.
This driver uses an algorithmic screen generation technique which works equally well on all NTSC and PAL display devices, as well as the new Amiga displays. The only requirement is that the display type must be supported by and correctly defined in Intuition.
You may select a title which will be placed in the title block of your display window by typing "w_title = "My Title"//CHAR(0)" prior to commencing the plot.
12.2 POSTSCRIPT DEVICE DRIVERS - ***Tentative***
This driver operates by writing an ASCII text file that contains the proper command sequences to make a plot. The file is written to POST.DIG, and when RLSDEV is called, the file is closed. The file POST.DIG can then be transferred to the postscript device. The following example assumes that an APPLE LASERWRITER is connected to the serial port. Use Preferences to set the serial port as:
BAUD 9600
PARITY NONE
8 BIT WORD SIZE
1 STOP BIT
Then type:
COPY POST.DIG SER:
One final note: When printed singly, all works fine. However, if two or more POST.DIG files are concatenated and then printed, they will be printed all on one page. To overcome this problem, I suggest that you prepare a file with only a form-feed (CTRL/L) in it, and concatenate the POST.DIG files together by intervening the form-feed file.
CHAPTER 13
PROGRAMMING EXAMPLE
The following FORTRAN program is a general shell into which all graphics programs should fit.
.
.
.
C
C START OF GRAPHICS
C SET THE DISPLAY TITLE (NB VARIABLE IS CASE SENSITIVE)
w_title = "My Plot Title"//CHAR(0)
C
CALL SELDEV(ILUN)
C
C ERASE THE SCREEN OR GET A NEW PIECE OF PAPER
C
CALL BGNPLT
C
C Amiga-DIGLIB APPLICATION SPECIFIC GRAPHICS HERE
C
.
.
.
C
C MAKE SURE ALL GRAPHICS HAVE BEEN OUTPUT TO THE DEVICE
C SINCE WE ARE ALL DONE GRAPHING BY THIS POINT.
C
CALL ENDPLT
.
.
.
C
C PROGRAM EXIT
C
CALL RLSDEV
STOP
END
High level graphics programming example:
PROGRAM DEMO
C
DIMENSION T(101), Y(101)
INCLUDE GRAPH.INC ! AMIGA GRAPHICS LIBRARY
INCLUDE INTUIT.INC ! AMIGA INTUITION LIBRARY
INCLUDE EXEC.INC ! AMIGA EXECUTIVE LIBRARY
C DECLARE ALL COMMON BLOCKS HERE TO SAVE THEIR
C CONTENTS IN ALL SUBSEQUENT SUBROUTINE CALLS
INCLUDE GCBIG.INC
DATA NPTS /101/
C
C GENERATE AN EXPONENTIAL DECAY CURVE
C
TMIN = 0.0
TMAX = 20.0
DT = (TMAX-TMIN)/(NPTS-1)
DO 100 I=1,NPTS
T(I) = TMIN + DT*(I-1)
100 Y(I) = 100.0*EXP(-T(I)/5.0)
C
C SELECT THE GRAPHICS DEVICE
CALL SELDEV(4)
CALL BGNPLT
C
C USE WHOLE SCREEN FOR PLOT AND LET Amiga-DIGLIB PICK
C CHARACER SIZE
C
CALL MAPSIZ(0.0,100.0,0.0,100.0,0.0)
C
C FIND Y LIMITS
C
CALL MINMAX(Y,NPTS,YMIN,YMAX)
C
C GENERATE THE AXES WITH LABLES
C
CALL MAPIT(TMIN,TMAX,YMIN,YMAX,'TIME IN
1 SEC.'//CHAR(0),'100*EXP(-T/5)'//CHAR(0)
2 ,'EXPONENTIAL DECAY CURVE'//CHAR(0),0)
C
C PLOT THE CURVE
C
CALL TRACE(T,Y,NPTS)
C
C END OF PLOTTING FOR NOW
C
CALL ENDPLT
CALL RLSDEV
STOP
END
CHAPTER 14
SUBROUTINE DESCRIPTIONS
14.1 STRINGS
ALL REFERENCES TO "STRING" VARIABLES OR CONSTANTS
REFER TO "NULL" (CHAR(0)) TERMINATED STRINGS AS
SUPPORTED BY F77!!!
On the Amiga with Absoft AC/FORTRAN strings are implemented as CHARACTER*1 arrays. Thus, for a variable length string of up to 80 characters called MYSTR use:
CHARACTER*1 MYSTR(82)
The reason for a dimension of 82 is that 1 extra byte is needed for the zero byte terminator, thus 81 bytes are required. For performance (and other reasons) it is best to always force CHARACTER arrays to have an even number of elements, thus 81 is "rounded up" to 82. Absoft AC/FORTRAN allows you to define a zero terminated string by following the ending quote with a CHAR(0).
CALL MAPIT(TMIN,TMAX,YMIN,YMAX,'TIME IN SEC.'//CHAR(0),
Purpose: This subroutine will plot a function Z=F(X,Y) as a
lined surface. The function must be defined on a regu-
lar grid. This routine will optionally remove hidden
lines.
Arguments:
Input
Z * Type: real array.
* The function values: Z(I,J)=F(Xi,Yj),
where
Xi = XMIN + (i-1)*(XMAX-XMIN)/(KX-1)
Yj = YMIN + (j-1)*(YMAX-YMIN)/(KY-1)
IZDIM1 * Type: integer constant or variable.
* The first dimension of the Z array -not
necessarily the number of X values.
IZ * Type: character array.
* A working array of bytes dimensioned
at least KX*KY long.
KX * Type: integer constant or variable.
* The number of X values in the Z array.
KX <= IZDIM1 of course.
KY * Type: integer constant or variable.
* The number of Y values in the Z array.
CAMLOC * Type: real array.
* The relative location of the viewer in
space. The viewer always faces toward
the center of the surface.
CAMLOC(1) = distance from surface in
units the same as those of Z.
CAMLOC(2) = angle between the viewer
and the X axis in degrees.
Usually, multiples of 30 or
45 degrees are best.
CAMLOC(3) = angle between the viewer
and the XY plane located at
Z=(ZMIN+ZMAX)/2 in degrees.
Thus 90 degrees is directly
above the surface - an unex-
citing picture! Usually the
angle is selected near 45
degrees.
XYLIM * Type: real two dimensional array dimen-
sioned (2,6).
* General parameters:
XYLIM(1,1) = XMIN ==> the minimum
value of X.
XYLIM(2,1) = XMAX ==> the maximum
value of X.
XYLIM(1,2) = YMIN ==> the minimum
value of Y.
XYLIM(2,2) = YMAX ==> the maximum
value of Y.
Note: Z(I,J) = F(Xi,Yj) where:
Xi=XMIN+(i-1)*(XMAX-XMIN)/(KX-1)
Yj=YMIN+(j-1)*(YMAX-YMIN)/(KY-1)
XYLIM(1,3) = ZMIN ==> the minimum
XYLIM(1,3) = ZMIN ==> the minimum
value of Z.
XYLIM(2,3) = ZMAX ==> the maximum
value of Z. These Z values
define the range of Z values
to fit on the screen. It is
strongly advised that ZMIN
and ZMAX bound Z(I,J).
XYLIM(1,4) = X/Z axis length ratio.
If this parameter is 0, then
X and Z are assumed to have
the same units, so their rel-
ative lengths will be in pro-
portion to their ranges. If
this parameter is nonzero,
then the X axis will be
XYLIM(1,4) times as long as
the Z axis.
XYLIM(2,4) = Y/Z axis length ratio.
Same as XYLIM(1,4), but for Y
axis.
XYLIM(1,5) = plot width in virtual
coordinates
XYLIM(2,5) = plot height in virtual
coord. Note: The plot is
expanded/contracted until it
all fits within the box def-
ined by XYLIM(1,5) and
XYLIM(2,5).
XYLIM(1,6) = virtual X coord. of the
lower left corner of the plot
box.
XYLIM(2,6) = virtual Y coord. of the
lower left corner of the box.
XLAB * Type: string constant or variable.
* The X axis lable.
YLAB * Type: string constant or variable.
* The Y axis lable.
ZLAB * Type: string constant or variable.
* The Z axis lable.
CSIZE * Type: real constant or variable.
* The character size in virtual coord.
for the tick mark lables and the axis
lables.
MARPLT * Type: integer constant or variable.
* Hidden line flag:
0 ==> draw all lines, hidden or not.
1 ==> suppress all lines hidden by
the surface, but display both
the top and bottom of the
surface
3 ==> suppress all lines hidden by
the surface, and all lines
showing the bottom of the
surface.
Add 4 to MARPLT if you do not want
the axes nor the ticks
labeled. This is useful on
small plots.
Output
None.
RLSDEV
Usage: CALL RLSDEV
Purpose: This subroutine releases the current device. After
this subroutine is called, you must call DEVSEL before
calling any other Amiga-DIGLIB subroutine. The purpose of
"RLSDEV" is to make sure your graphics device is
restored to a proper working state. This subroutine
should be called before exiting by any program that
uses Amiga-DIGLIB. RLSDEV closes the screen created by
DEVSEL.
Arguments: None.
Programming notes:
* It is highly recommended that you use RLSDEV.
RSTMAP
Usage: CALL RSTMAP(AREA)
Purpose: This subroutine restores a world to virtual coordinate
transformation that was previously saved using SAVMAP.
Arguments:
Input
None.
Output
AREA * type: real array of 15 elements.
* The array of world to virtual coordi-
nates transf. values previously saved
by SAVMAP.
Programming notes:
* Very unpredictable things will happen if RSTMAP is fed
anything but the same values output by SAVMAP.
* RSTMAP can be used to restore the mapping context for
a plot with two Y axes (see SYAXIS) or to restore the
mapping context to a entirely different plot.
SAVMAP
Usage: CALL SAVMAP(AREA)
Purpose: This subroutine allows the caller to save the current
world to virtual coordinate transformation and clip-
ping information. This subroutine is generally only
useful when the caller wishes to maintain more than
one world coordinate system.
Arguments:
Input
None.
Output
AREA * type: real array of at least 15 ele-
ments.
* The area in which to store the current
world to virtual coordinate transforma-
tion.
Programming notes:
* This subroutine is very useful when the user has two Y
axes on a single plot and is using SYAXIS.
* This subroutine is very useful when the user desires
to display two separate plots on the same device, or
on different devices, and wishes to move back and
forth between the plots.
* The subroutine RSTMAP restores the world to virtual
transformation saved by SAVMAP.
SCALE
Usage CALL SCALE(WORLDX,WORLDY,VIRTX,VIRTY)
Purpose: This subroutine converts world coordinates to virtual
coordinates.
Arguments:
Input
WORLDX * type: real constant or variable.
* The x value in world coordinates to
convert.
WORLDY * type: real constant or variable.
* The y value in world coordinates to
convert.
Output
VIRTX * type: real variable.
* The corresponding x value in virtual
coordinates.
VIRTY * type: real variable.
* The corresponding y value in virtual
coordinates.
Programming notes:
* This subroutine is equivalent to PLTLIB's SCALE. The
only difference is that real values (the virtual coor-
dinates) are returned instead of integer values (4025
device coordinates).
SELDEV
Usage: CALL SELDEV(LUN)
Purpose: SelDev displays the names of the devices available on
the computer along with the associated device number.
It then asks for the number of the device you wish to
use. If that device is not available, it tells you so
and asks for another device to use.
Argument:
Input
Lun : * integer constant or variable.
* It is the logical unit number to be
used by the graphics device.
Output
None.
Programming Notes:
* SelDev uses GsDname to obtain the name of a device
from its device number. It uses DevSel to set the out-
put device once a device number has been entered from
the keyboard. If no devices are available, you are
stuck!
SYAXIS
Usage: CALL SYAXIS(YLOW,YHIGH,YLAB,IAXES)
Purpose: This subroutine places a second Y axis on the current
plot. The current world to virtual coordinate trans-
formation is overwritten with the new Y axis values.
Arguments:
Input
YLOW * type: real constant or variable.
* Minimum limit for the second Y-axis in
world coordinates.
YHIGH * type: real constant or variable.
* Maximum limit for the second Y-axis in
world coordinates.
YLAB * type: string constant or variable.
* Second Y-axis label.
IAXES * type: integer constant or variable.
* Axes type as per MAPIT, but X-axis
information is ignored.
Output
None.
Programming notes:
* The second Y axis will not be contained in the speci-
fied plotting region if the region was defined by MAP-
SIZ, FULMAP, PLTBOX, MAPPRM(,,,,,,.FALSE.), or MAP-
SET(,,,,,,.FALSE.).
* The second Y axis will be contained in the specified
plotting region if the region was defined by MAPSZ2,
PLTBX2, MAPPRM(,,,,,,,.TRUE.), or MAP-
SET(,,,,,,.TRUE.).
* SYAXIS overwrites the Y axis portion of the current
world to virtual coordinate transformation. If the
users desires to retain the old transformation, he
should save it with SAVMAP.
SYMBOL
Usage: CALL SYMBOL(ISYMNO,SYMSIZ)
Purpose: This subroutine places a centered symbol at the cur-
rent location in the desired size. There are currently
4 symbols defined. You are welcome to edit the file
and create more.
Arguments:
Input
ISYMNO * type: integer constant or variable.
* The number of the symbol to draw:
1 ==> triangle,
2 ==> square,
3 ==> diamond,
4 ==> hour glass.
SYMSIZ * type: real constant or variable.
* The height (size) of the symbol in vir-
tual coordinates.
Output
None.
Programming Notes:
* To place symbol number 2 at (X,Y) in world coordi-
nates:
CALL SCALE(X,Y,VX,VY) CONVERT WORLD TO VIRTUAL COORD
CALL GSMOVE(VX,VY)
CALL SYMBOL(2,0.4) SYMBOL 2, SIZE IS 0.4
TRACCY
Usage: CALL TRACCY(XMIN,XMAX,YARRAY,NUMPTS)
Purpose: This subroutine connects the world coordinate points
with straight lines. The X values of the points are
assumed to be equally spaced between XMIN and XMAX.
Any lines that lie outside the axes frame are not dis-
played.
Arguments:
Input
XMIN * type: real constant or variable.
* The world X coordinate of the first
point.
XMAX * type: real constant or variable.
* The world X coordinate of the last
point.
YARRAY * type: real array.
* The array of corresponding Y world
coordinates.
NUMPTS * type: integer constant or variable.
* The number of points to connect.
Output
None.
Programming notes:
* MAPIT must be called before using TRACCY.
TRACE
Usage: CALL TRACE(XARRAY,YARRAY,NUMPTS)
Purpose: This subroutine connects the world coordinate points
given with straight lines. If enough points are given,
the curve formed will appear nearly smooth.
Arguments:
Input
XARRAY * type: real array.
* The array of X world coordinates of the
points.
YARRAY * type: real array.
* The array of corresponding Y world
coordinates.
NUMPTS * type: integer constant or variable.
* The number of points to connect.
Output
None.
Programming notes:
* MAPIT must be called before using TRACE.
TRACEC
Usage: CALL TRACEC(XARRAY,YARRAY,NUMPTS)
Purpose: This subroutine connects the world coordinate points
given with straight lines. If enough points are given,
the resultant curve will appear smooth. Any lines that
lie outside the axes frame are not displayed.
Arguments:
Input
XARRAY * type: real array.
* The array of X world coordinates of the
points.
YARRAY * type: real array.
* The array of corresponding Y world
coordinates.
NUMPTS * type: integer constant or variable.
* The number of points to connect.
Output
None.
Programming notes:
* MAPIT must be called before using TRACEC.
TRACEY
Usage: CALL TRACEY(XMIN,XMAX,YARRAY,NUMPTS)
Purpose: This subroutine connects the world coordinate points
with straight lines. The X values of the points are
assumed to be equally spaced between XMIN and XMAX.
Arguments:
Input
XMIN * type: real constant or variable.
* The world X coordinate of the first
point.
XMAX * type: real constant or variable.
* The world X coordinate of the last
point.
YARRAY * type: real array.
* The array of corresponding Y world
coordinates.
NUMPTS * type: integer constant or variable.
* The number of points to connect.
Output
None.
Programming notes:
* MAPIT must be called before using TRACEY.
CHAPTER 15
GUIDE TO WRITING A DEVICE DRIVER
15.1 INTRODUCTION
This documentation is intended for anyone who desires to add a graphics device driver to Amiga-DIGLIB. It is assumed that the reader is proficient in FORTRAN or MACRO and has some knowledge of graphics. In addition, the reader should become intimately familiar with the target graphics device.
I request that debugged Amiga-DIGLIB device drivers be forwarded to Craig Wuest, L-84 for distribution and maintenance. Yes, that is right! You write it, I'll distribute and maintain it to the best of my ability and available time. Please send a floppy with the graphic driver to Craig Wuest L-84. I will make a copy and return your floppy ASAP. Note also, that before embarking on an adventure through graphic device driver land, it will probably be very useful to check with Craig Wuest x32909 to see if such a driver already exists, or whether there is a very similar driver which can be modified. It is nearly always easier to make minor modifications than to start from scratch.
Amiga-DIGLIB was written to be as device independent as possible. Accordingly, it was assumed that the graphics device was only capable of performing two simple graphics primitives: move and draw. Amiga-DIGLIB does, however, provide for some "extended" primitives such as: set color, graphics input, and define color. Because Amiga-DIGLIB only uses move and draw, authors of graphics device drivers need not worry about character generation, line types, etc. Amiga-DIGLIB performs these functions using only move and draw.
Amiga-DIGLIB graphics device drivers basically perform two
functions:
1. Formatting of graphics commands, and
2. Outputting of the formatted graphics commands.
Formatting of graphics commands is very device specific, and will not be discussed here. See the programming manual for your graphics device for this information. Output of the formatted graphics commands is, however, common among all Amiga-DIGLIB drivers in the sense that all Amiga-DIGLIB drivers either handle the I/O themselves, or pass of the formatted graphics commands to the
operating system to be output. All Amiga-DIGLIB graphics device drivers that drive graphic terminals use the terminal I/O capability of the operating system to perform the output operation.
15.2 STANDARD DEVICE DRIVER FUNCTIONS
Amiga-DIGLIB device drivers must perform 7 basic graphics primitives:
1. Initialize the graphics device and prepare it for graph-
ics commands.
2. Prepare a fresh plotting surface on the graphics device
and reset the drawing parameters to the "initial state".
3. Move from the current (X,Y) position to a new (X,Y)
position without drawing a line.
4. Draw a line from the current (X,Y) position to a new
(X,Y) position (in the current color).
5. Transmit any graphics commands formatted, but not yet
output to the graphics device.
6. Release the graphics device.
7. Return to the caller information about this graphics
device (Device Characteristics Values).
INITIALIZE - function 1
To initialize a graphics device, the graphics driver should first take exclusive control of that device on a multi-user system. Then the device should be sent commands to prepare the device for the commands that the graphics driver will generate. Commands should also be included to set any special parameters
(i.e. line types) the device may have to the proper values. If possible, the initialize function should not erase the screen. This will allow for multiple programs to all draw on the same "drawing surface". Sometimes, to initialize the device requires the screen to be erased. If that is the case, just document it as a feature.
On color devices, initialize should set the desired background color and foreground color for future drawing if possible. In addition, for devices with definable color sets, initialize should set color 2 to be red, color 3 to be green, color 4 to be blue, color 5 to be yellow, color 6 to be magenta, and color 7 to be cyan. Unless you definitely want a different foreground/background color scheme, color 0 (background) should be set to black, and color 1 (foreground) to white.
Initialize is also responsible for returning an error indicator when the device can not be selected, or some other problem exists.
BEGIN PLOT - function 2
The begin plot function should erase the screen or (more generally) prepare a fresh plotting surface on the graphics device (i.e. advance the page on a plotter, etc.). In addition, it should set colors 0 to 7 to their proper default values (black, white, red, green, blue, yellow, magenta, cyan respectively). It should also set the current drawing color to color 1. Care should be taken to make sure that the driver's perception of the state of the device remains consistent with the device's state. Usually, it is necessary to either force out any commands left in the command buffer (if one is maintained) or to send commands/set state memory variables to make sure that consistancy is maintained. For example, if the driver remembers the current position that the device is going to draw from, it is typically updated when a command is buffered for the device. If this buffer is discarded instead of being sent to the device by BGNPLT (as is done in some Amiga-DIGLIB drivers), then care must be taken to ensure that any possible device states that the driver perceived as changed but really weren't are made consistent!
MOVE and DRAW - functions 3 and 4
Amiga-DIGLIB always works in centimeter coordinates as far as the graphics device drivers are concerned. Thus all coordinates that flow into or out of the graphics device driver are in centimeters. Also, Amiga-DIGLIB performs clipping of all coordinates based on the device's Device Characteristics Values, eliminating all coordinates that lie outside the graphics devices accessible area.
ENDPLT - function 5
It is often desirable to buffer the graphics commands before sending them to the graphics device. In fact, a good size buffer will usually increase the graphics throughput because of the overhead of the operating system for I/O. The problem with buffering graphics commands is that some will almost always remain
in the buffer after the last graphics subroutine has been called and the plot will be incomplete. Amiga-DIGLIB solves this problem by requiring the user to call ENDPLT. ENDPLT then calls the graphics driver with function code 5. The graphics driver should then send out the last buffer (even though it is not yet full).
RELEASE DEVICE - function 6
Release device is the antithesis to initialize device. The function of release device is to return the graphics device to its initial state, or atleast to something close to its initial state. Release device should not erase the graphics (if possible).
RETURN DEVICE CHARACTERISTICS - function 7
The definitions of each of the 8 device characteristics values is given in section 16.5. The 4 values "X axis length", "Y axis length", "X axis resolution", and "Y axis resolution" are simple to determine by consulting the graphics device specifications, or by measurement and calculation. However, when using the measurement and calculation method, the following pitfall exists:
1. Because the graphics device is out of adjustment, the X
resolution and the Y resolution appear different, and
2. Due to roundoff and measurement errors, the product of
the resolution times the screen size when rounded is
greater than the device's maximum addressable point.
The problem with 1) is that when a 45 degree line is drawn, it will truly be drawn at 45 degrees, but the user will not think so because the line is jagging every once in a while along its length. My solution to this problem is to set the "X axis resolution" and "Y axis resolution" to the same value unless it is specifically known that they should be different. Lines drawn at 45 degrees may not be exactly 45 degrees, but the user will think so, and so you are not plagued by users thinking the driver is sick!
The problem with 2) is that lines drawn at the supposed right and/or top of the screen get clipped, or worse, the device driver will get passed a coordinate that is outside the device's addressable range.
The solution to this problem is to average the X and Y resolution to get a single resolution for both X and Y unless it is specifically known that the X and Y resolution are different. Then, using the device's maximum addressable points in X and Y, and the resolution, back calculate the axis lengths.
Example:
Measurement yields an X axis length of 15.7 centime-
ters and a Y axis length of 10.4 cm. The device coor-
dinate ranges are 0 to 639 in X, and 0 to 419 in Y.
So:
X axis resolution is 40.7 graphic units per cen-
timeter Y axis resolution is 40.3 graphic units per
cm. averaging, we get 40.5 GU/CM.
Thus, we set:
X axis resolution = 40.5 GU/CM.
Y axis resolution = 40.5 GU/CM.
X axis length = 639/40.5 = 15.7778 CM.
Y axis length = 419/40.5 = 10.3457 CM.
The 8th returned value also requires some discussion. This value is new to Amiga-DIGLIB V3 and its support of hardware/software polygon fill. For devices that do not support solid filled polygons, Amiga-DIGLIB's polygon primitive GSFILL contains a software polygon fill algorithm. The algorithm can handle any polygon (but maybe not the way you want, intersecting polygons are of dubious value in my opinion). The 8th device characteristic value only pertains to device characteristic value only pertains to the software fill algorithm. It tells the software fill algorithm just how dense to draw the horizontal lines that fill the polygon. You should choose this value via trial and error. I suggest choosing it large and working down. The way to get a first guess is to estimate the width of the plotter pen in resolution (graphics) units. Thus, for a pen that drew a line 2 mm. thick, on a plotter with 0.5 mm. per graphics unit, a good first guess would be 2.0/0.5 = 4. Thus, drawing every 4th line (skipping 3) should still produce an acceptable solid fill. Note that this parameter should always be one (1) when the size of the (virtual) pen is 1 graphic unit as is the case with all raster scan devices.
Since this 8th device characteristic value is new, DEVSEL will automatically default it to be 1 if the device driver returns only 7 values. However, this is a backward compatibility feature, and all new Amiga-DIGLIB device drivers should return all 8 values!
15.3 EXTENDED DEVICE DRIVER FUNCTIONS
In addition to the 7 basic graphic primitives, Amiga-DIGLIB defines 6 extended functions that you may optionally implement. Amiga-DIGLIB graphics device drivers may implement none, all, or any combination of these functions.
1. 8) Set current drawing color or intensity.
2. 9) Graphics input with pick character.
3. 10) Define a color numbers visual value using RGB coor-
dinates.
4. 11) Define a color numbers visual value using HLS coor-
dinates.
5. 12) Graphics input with device dependant "button" input.
6. 1024+N) Draw a solid filled polygon of N sides I suggest
implementing 8) and either 9) or 12) if possible. Amiga-
DIGLIB has a software polygon fill algorithm, so you can
get filled polygons regardless of whether you implement
the polygon fill section. However, hardware (firmware)
fills are typically much faster.
SET COLOR - function 8
Amiga-DIGLIB uses numbers to express the color it wants to use. The Amiga-DIGLIB color convention is:
0 is the background color (usually black)
1 is the primary foreground color (usually white
if possible)
2==>n are the secondary foreground colors
default colors are:
0 Black 4 Blue
1 White 5 Yellow
2 Red 6 Magenta
3 Green 7 Cyan
8 - 15 System Default
If your graphics device has fixed colors, then the graphics driver should map the Amiga-DIGLIB colors numbers into the graphics devices color numbers so that the proper color correspondence exists.
GRAPHICS INPUT WITH PICK CHARACTER - function 9
This function requires a keyboard, since it must return a "pick character". This is no problem with graphics terminals, but with graphics heads, there is often no keyboard for getting the "pick character". This can be handled by using the interactive terminal keyboard. I admit this is a kludge, but there seems no
alternative.
To perform a graphics input with pick character operation, the following steps are necessary:
1. Make the graphic cursor visible if it is not always vis-
ible,
2. Allow the user to position the graphic cursor,
3. When the user strikes a character at the graphics key-
board, read the graphic cursor position,
4. Return the character struck, the X position (in cm.) and
the Y position (in cm.) of the graphic cursor, and
5. Make the graphic cursor invisible if possible.
If your graphic device does not have a keyboard, then the
user's terminal is the logical choice.
DEFINE COLOR USING RGB - function 10
Amiga-DIGLIB provides a mechanism for selecting the color associated with by Amiga-DIGLIB color number using the (Red, Green, Blue) color coordinate system.
DEFINE COLOR USING HLS - function 11
Amiga-DIGLIB does not provide a mechanism for selecting the color associated with any Amiga-DIGLIB color number using the (Hue, Lightness, Saturation) color coordinate system.
GRAPHICS INPUT WITH BUTTON INPUT - function 12
This form of graphics input is designed for graphics devices that use mice, digitizers, joysticks, or the like. Theoretically, the pointing device contains a set of buttons, any or all of which may be "pressed" or otherwise caused to change binary state. When a state change occurs, the graphics input operation
is concluded, and the new state of the buttons is returned. The buttons are numbered from 1 to N for a N button device. The state of each button is represented by a bit in the "button state" returned variable. The correspondence between buttons and bits is:
Bit = 2**(n-1)
Where n is the button number.
A bit value of one means the button is "set" or "pressed", and zero means the corresponding button is "clear" or "not pressed".
For devices that support both graphics input with "pick character" and graphics input with "button" input, it is desirable to use different cursors if possible. This will allow the user to determine what action is necessary to terminate the graphics input.
To perform a graphics input with button input operation, the ollowing steps are necessary:
1. Make the graphic (button) cursor visible if it is not
always visible,
2. Allow the user to position the graphic cursor,
3. When the selects the current position by pressing a
"button", read the graphic cursor position,
4. Return the button state after the button was pressed,
the X position (in cm.) and the Y position (in cm.) of
the graphic cursor, and
5. Make the graphic (button) cursor invisible if possible.
DRAW SOLID FILLED POLYGON - function 1024+N
The number of vertices are passed in as a part of the function code. I realize this is unorthodox, but everything else requires too much overhead. Two sophistications of hardware fill are supported by Amiga-DIGLIB. The first is the simple "convex polygon fill". The second is the "any polygon fill". Some devices can only handle convex (non-intersecting) polygons. If you set the DEVICE CHARACTERISTICS bit telling Amiga-DIGLIB that the device can only handle convex polygons, Amiga-DIGLIB will supply software fill for the concave polygons, and call the driver for the convex polygons.
DEVICE CHARACTERISTICS and the EXTENDED FUNCTIONS
All implementators of primitives 8, 10, 11 and/or 1024+N need be aware of the interaction of these primitives with the Device Characteristics Values (primitive 7). Device characteristics value number 6 is the number of foreground colors. This includes color 1 but not color 0. All devices have atleast one foreground color. In addition, device characteristics value 7 has the 2 bit set if the device is capable of writing in the backround color (color 0). Pen plotters and storage tubes are not capable of writing in the background color, but most other graphic devices can handle this function. Let's take the example
of the Tektronix 4027 terminal to see how the device characteristics values (color only) are set. A 4027 has the ability to display 8 colors simultaneously, out of a palate of 64 total colors. In addition, the 4027 has a programmable Look-Up Table (LUT) so that colors may be defined. Reading the manual, we find that colors may be define by both RGB and HLS. Thus we would:
1. Implement primitive 8,
2. Implement primitives 10 and 11,
3. Set device characteristics value 6 to 7 foreground col-
ors (one of the 8 colors must be background), and
4. Set device characteristics value 7 to 1+4+32+64+128.
Note that we added 4 to the value of device characteristics value 7. This reflects the fact that the 4027 can draw in the background color (erasing color).
If we were to implement the polygon fill section of the 4027 driver, we would set bit 7 of the device characteristics bit (value 256) and leave bit 8 (value 512) clear because the Tek. 4027 can handle polygons all polygons.
Before you start writing an Amiga-DIGLIB device driver, you should first arm yourself with a good programmers manual for the target graphics device. Then, find an Amiga-DIGLIB driver for a similar device and plagiarize, plagiarize, plagiarize! Make sure you don't just kludge it though.
15.4 DEVICE DRIVER EXAMPLES
The file "SKELTN.FTN" gives a skeleton graphics device driver written in FORTRAN that may be edited with an editor and used as a starting point for writing an Amiga-DIGLIB graphics device driver. However, there is no reason that this skeleton need be used at all, nor even that the device driver be written in FORTRAN as opposed to MACRO. In addition to "SKELTN.FTN", I have included the file "GD13HI.FOR" and "GD12HI.FOR which are working drivers.
NOTE
By convention, all graphics device driver names start
with the letters "GD" for Graphic Driver.
15.5 DEVICE DRIVER ARGUMENTS
The graphics device driver has 3 arguments:
1. The graphics function to be performed,
2. A real array whose meaning is dependant on the
graphics function to be performed, and
3. A real array whose meaning is dependant on the
graphics function to be performed.
INPUT
IFXN * TYPE: INTEGER CONSTANT OR VARIABLE.
* THE GRAPHICS FUNCTION TO PERFORM:
1 ===> INITIALIZE THE GRAPHICS DEVICE
TO PREPARE IT FOR GRAPHICS
(AND ON MULTI-USER SYSTEMS,
TAKE EXCLUSIVE CONTROL OF THE
DEVICE.)
2 ===> OBTAIN A FRESH PLOTTING SUR-
FACE ON THE GRAPHICS DEVICE.
3 ===> MOVE TO A NEW POSITION (X,Y),
WHERE THE UNITS OF BOTH X AND
Y ARE IN CENTIMETERS.
4 ===> DRAW A LINE TO THE POSITION
(X,Y), WHERE THE UNITS OF X
AND Y ARE IN CENTIMETERS.
5 ===> TRANSMIT ANY BUFFERED GRAPHICS
COMMANDS THAT HAVE NOT YET
BEEN TRANSMITTED TO THE
GRAPHICS DEVICE.
6 ===> RELEASE CONTROL OF THE GRAPH-
ICS DEVICE.
7 ===> RETURN TO THE CALLER THE
DEVICE CHARACTERISTICS OF
THIS DEVICE.
8 ===> SET THE CURRENT DRAWING
COLOR.
9 ===> PERFORM A GRAPHICS INPUT WITH
PICK CHARACTER OPERATION,
RETURNING THE USER SELECTED
LOCATION (X,Y) WITH X AND Y
SPECIFIED IN CENTIMETERS.
10 ==> SET THE VISUAL COLOR ASSOCI-
ATED WITH A SPECIFIED COLOR
NUMBER TO THE RGB VALUE PRO-
VIDED.
11 ==> SET THE VISUAL COLOR ASSOCI-
ATED WITH A SPECIFIED COLOR
NUMBER TO THE HLS VALUE PRO-
VIDED.
1024+N==> DRAW FILLED POLYGON HAVING
N SIDES.
XA * TYPE: REAL ARRAY.
* DEPENDANT OF THE GRAPHICS FUNCTION
GIVEN BY "IFXN".
1 ===> XA(1) IS RT-11 CHANNEL NUMBER
ON WHICH TO PERFORM I/O, OR
RSX-11M LOGICAL UNIT NUMBER
ON WHICH TO PERFORM I/O.
XA(2) --> XA(7) UNUSED.
2 ===> XA(1) --> XA(7) UNUSED.
3 ===> XA(1) IS THE X COORDINATE IN
CM. FOR THE MOVE OPERATION.
XA(2) --> XA(7) UNUSED.
4 ===> XA(1) IS THE X COORDINATE IN
CM. FOR THE DRAW OPERATION.
XA(2) --> XA(7) UNUSED.
5 ===> XA(1) --> XA(7) UNUSED.
6 ===> XA(1) --> XA(7) UNUSED.
7 ===> XA(1) --> XA(7) UNUSED.
8 ===> XA(1) IS COLOR FOR SUBSEQUENT
LINES. XA(2) --> XA(7)
UNUSED.
9 ===> XA(1) --> XA(7) UNUSED.
10 ==> XA(1) IS THE COLOR TO DEFINE.
11 ==> XA(1) IS THE COLOR TO DEFINE.
12 ==> XA(1) --> XA(7) UNUSED.
1024+N ==> XA(1) --> XA(N) X VER-
TICES OF POLYGON.
YA * TYPE: REAL ARRAY
* DEPENDANT OF THE GRAPHICS FUNCTION
GIVEN BY "IFXN".
1 ===> YA(1) IS THE ERROR FLAG FOR
DEVICE SELECTION:
0 ==> NO ERRORS
>0 ==> ERROR
YA(2) --> YA(3) UNUSED.
2 ===> YA(1) --> YA(3) UNUSED.
3 ===> YA(1) IS THE Y COORDINATE IN
CM. FOR THE MOVE OPERATION.
YA(2) --> YA(3) UNUSED.
4 ===> YA(1) IS THE Y COORDINATE IN
CM. FOR THE DRAW OPERATION.
YA(2) --> YA(3) UNUSED.
5 ===> YA(1) --> YA(3) UNUSED.
6 ===> YA(1) --> YA(3) UNUSED.
7 ===> YA(1) --> YA(3) UNUSED.
8 ===> YA(1) --> YA(3) UNUSED.
9 ===> YA(1) --> YA(3) UNUSED.
10 ==> YA(1) IS % RED COMPONENT OF
COLOR. YA(2) IS % GREEN COM-
PONENT OF COLOR. YA(3) IS %
BLUE COMPONENT OF COLOR.
11 ==> YA(1) IS THE HUE (0-360).
YA(2) IS THE LIGHTNESS
(0-100). YA(3) IS THE SATURA-
TION (0-100).
12 ==> YA(1) --> YA(3) UNUSED.
1024+N ==> YA(1) --> YA(N) Y VER-
TICES OF POLYGON.
OUTPUT
XA * TYPE: REAL ARRAY.
* DEPENDANT OF THE GRAPHICS FUNCTION
GIVEN BY "IFXN".
1 ===> XA(1) --> XA(7) UNUSED.
2 ===> XA(1) --> XA(7) UNUSED.
3 ===> XA(1) --> XA(7) UNUSED.
4 ===> XA(1) --> XA(7) UNUSED.
5 ===> XA(1) --> XA(7) UNUSED.
6 ===> XA(1) --> XA(7) UNUSED.
7 ===> XA(1) --> XA(7) ARE SET TO
THIS DEVICES CHARACTERISTIC
WORDS:
XA(1) = DEVICE ID. (A UNIQUE DEVICE NUMBER OBTAINED
FROM HAL BRAND X26312.
XA(2) = X AXIS LENGTH OF THIS DEVICE IN CM.
XA(3) = Y AXIS LENGTH IN CM.
XA(4) = X AXIS RESOLUTION IN GRAPHICS UNITS (GU) PER
CENTIMETER.
XA(5) = Y AXIS RESOLUTION IN GU/CM.
XA(6) = NUMBER OF AVAILABLE FOREGROUND COLORS ON THIS
DEVICE.
XA(7) = DEVICE CHARACTERISTICS BITS. THE SUM OF:
0 IF STROKE (PLOTTER) DEVICE.
1 IF RASTER DEVICE.
2 IF DVST (STORAGE TUBE)
3 PRINTER/PLOTTER
4 IF DRAWING IN THE BACKGROUND COLOR
(COLOR 0) IS AVAILABLE.
8 IF DEVICE IS A HARDCOPY DEVICE.
16 IF DEVICE IS A SHAREABLE DEVICE.
32 DEVICE'S COLORS ARE HLS SELECTABLE.
64 DEVICE'S COLORS ARE RGB SELECTABLE.
128 GRAPHICS INPUT WITH "PICK CHARACTER"
IS AVAILABLE.
256 DEVICE DRAWS FILLED POLYGONS.
512 DEVICE REQUIRES CONVEX POLYGONS.
1024 GRAPHICS INPUT WITH BUTTONS IS AVAILABLE.
XA(8) = 1 + THE NUMBER OF SCAN LINES TO SKIP WHILE
