REVIEWS

COMPUTE!'s Technical Reference Guide
ATARI ST
Volume One: VDI

by Sheldon Leemon
COMPUTE! PUBLICATIONS, INC.
P.O. Box 5406
Greensboro, NC 27403
(919) 275-9809
343 Pages $18.95

by Charles F. Johnson

Charles — and our readers — will be glad to hear that Volume Two is on its way. Its topic, naturally, is GEM's AES.

Sheldon Leemon (DRX on Delphi) has been an active supporter of Atari computers for years. He has published articles and programs in just about every Atari-specific magazine, and caused quite a stir in the Atari community a while back when he wrote an article entitled "The Myth of ST Superiority."

With the intention of "debunking" claims made by some ST supporters, he compared the ST to the Commodore Amiga—not always in the ST's favor—and faced a lot of criticism, even outright animosity from some quarters. One of the points he made at the very beginning of the article, however, was that he liked and used both machines, and preferred the Amiga by only a slight margin.

With this in mind, we shouldn't be surprised to find that Mr. Leemon is the author of a book—indeed, a series of books—about programming the ST. COMPUTE! Books is publishing the series that can now be found on the stands (I found mine at Walden Books in Los Angeles). In the typical long-winded fashion of COMPUTE! Books, the title is (take a deep breath), COMPUTE!'s Technical Reference Guide, ATARI ST, Volume One: VDI. Gasp.

Since I don't want to type this every time I mention the book, I'm going to call it COMPUTE!'s VDI for purposes of this review. For $18.95, you get 343 pages of documentation on the VDI graphics functions built into the ST's operating system. So how is it? In a word, excellent.

This book is so good that I now use it instead of the Developer's Kit docs or the Abacus GEM Programmer's Reference when I need to know something about the VDI.

For the beginners among us, VDI stands for "Virtual Device Interface." The VDI part of the ST's operating system is supposed to provide a uniform way to access all possible graphics peripherals. Using the VDI, a programmer can employ the same graphics commands to produce output on any hardware device (printer, plotter, monitor screen) without necessarily knowing the down-and-dirty details of each device's operation.

The first part of COMPUTE!'s VDI (before the appendices, which take up almost half of the book) contains chapters covering "Setting Up the Graphics Environment," "Drawing Points and Lines," "Color," "Filled Shapes," "Drawing and Manipulating Image Blocks," "Text," and "Input Functions." Each chapter contains several short demo programs to illustrate the points covered. To minimize typing errors, the examples are reproduced from printouts, not typeset.

The basics of programming the VDI are covered in terms of BASIC (ST BASIC—ugh), C and assembly language. For C and assembly programmers, a program "shell" is listed, taking care of all GEM initialization procedures; you simply key in the demo programs, then link them to this shell, which saves a lot of tedious retyping. There are complete and easy to follow instructions for compiling and linking the example programs, using the Alcyon C compiler and AS68 assembler from the Atari Developer's Kit. The C examples will translate easily (for the most part) to Megamax or Mark Williams C. To use the assembly examples with another assembler, you'll probably have to modify them somewhat.

These sections of the book are handled very well, except for one huge mistake in the discussion of the ST's screen memory organization (pages 69-70). Mr. Leemon's description of the monochrome screen's organization is correct; however, the descriptions of low and medium resolution are seriously flawed.

Leemon says that the first byte in low-resolution screen memory contains the pixel data for the first 2 pixels (horizontally) on the screen. Since 4 bits can hold a value from 0 to 15, each 4 bits of that byte contains a value from 0 to 15, which represents the color that appears at that location. For example, if the first byte of screen memory was hexadecimal $4E, the first 2 pixels would be colored according to the contents of color registers 4 (hex 4) and 14 (hex E). Sounds logical, and indeed, the Atari 8-bit's screen memory is organized in exactly this way. The only problem is that, for the ST, it's dead wrong.

The ST's screen memory is more complicated than this in reality. The color data for the first pixel in a low-resolution display is spread among the first four words (a word is defined as 2 8-bit bytes) of screen memory, in a scheme sometimes referred to as "bit-planes." The first 4 bits of color data are contained in the leftmost bits (bit 15) of the first four words. The next pixel's color value is contained in the next bit of the first four words (bit 14), etc. The Abacus book Atari ST Internals has a fairly good description of the ST's screen memory. Consult Abacus and forget about pages 69–70 in COMPUTE!s VDI.

Appendix A of COMPUTE!s VDI provides a complete list of every documented VDI function, in a clear, well written manner. This is the section of the book you'll probably find yourself using the most, once you've digested the introductory material in the beginning pages.

Each VDI call is listed by its title (e.g., Inquire Current Polyline Attributes) and its name according to the C bindings (e.g., vql__attributes), followed by a description of the call's purpose, the devices it's required for (e.g., screen, printer or metafile), an example of its usage and C syntax, and the proper parameters for the VDI arrays. Even those VDI calls that require the use of GDOS are listed here. In fact, throughout the book, GDOS is referred to as an integral part of the VDI system. Atari's current policy regarding GDOS states that developers must pay a one-time $500 fee to license GDOS for commercial software; it's unclear where this leaves the hobbyist programmer who writes software primarily for public domain distribution.

Appendix B lists the extended codes for every key on the ST's keyboard, including all ALT, SHIFT, and CONTROL key combinations. This comes in handy when you want to check for input from the function keys, the numeric keypad, or the cursor key group. Unfortunately, we find another error in Appendix B...the extended key codes for the right and left arrow keys are reversed.

Appendix C is a description of the G-DOS/VDI font file format. All disk-based fonts to be used with the VDI text font calls (such as vst__load__fonts and vst__font) must be stored in this format. Appendix D shows the entire default ST ASCII character set. (Is there a law stating that every reference book for the ST must include an ASCII table?)

Aside from the errors mentioned above, and a small mistake on page 37 (SET-BLOCK is incorrectly described as an XBIOS function—it's a GEMDOS function), I can find very few nits to pick with COMPUTE!s VDI. Along with a plethora of programming examples, it contains three indexes—a conventional index by keywords, and indexes to the VDI functions, both alphabetically and by function number. I could find no errors at all in Appendix A, the VDI Function Reference. The language of the book is clear and, given the technical nature of the subject, relatively free of computer buzzwords. It's soft cover opens flat for easy access during long programming sessions. If you're programming on the ST (for fun or professionally), COMPUTE!s VDI should be on your necessary list.

Well done, Sheldon! I'm anxious to see a volume devoted to the Application Environment Services (AES) section of GEM; to date, all sources of AES documentation repeat the same errors ad nauseam. An AES reference book of the same quality as COMPUTE!s VDI would be greatly appreciated. And please, correct that screen memory mistake in any second printing!