Ultra Hires Graphics 1.0
  Appeared in RUN Magazine, February 1986

  By Louis Wallace and David Darus
                                             The C128 computer is without doubt a remarkable machine.  It contains one of the best BASIC languages ever included with a micro, has 128K RAM and is expandable, supports hires graphics in composite mode, contains both a working C64 and a Z-80 CP/M computer, has a great keyboard and a beautiful 80 column display.  And perhaps best of all it is inexpensive!  What more could you want?
    Well, one thing I always want is higher resolution graphic displays.  And the 80 column screen on the C128 was a welcome blessing to many of us who find 40 columns a limitation, but still prefer Commodore computers over others.  This new 80 column capability is made possible by a second graphics chip, the 8563.  This is a very powerful device, and it makes possible the crisp, clear color text the C128 makes in 80 column mode.
    There is presently a cloud of mystery surrounding the graphic capabilities of this new addition to the Commodore computer family, and I hope this article will go far toward dispelling the questions I know many of you have.
    First and foremost the question arises about bitmapping (hires graphics).  Since the 80 column text is made possible by a resolution of 640 X 200, many of us hoped we would be able to use that for graphics.  However, BASIC 7.0 contains no provision for high resolution graphics of the 80 column display.  We were told originally that we might be able to do some elementary graphics via custom characters on the 80 column screen, but not true hires graphics.  And the technical specifications for the 8563 state it has only limited bitmapping capabilities.  This got us interested in seeing just how limited it is.
    I am pleased to announce that our research has led to the discovery that yes, it is possible to use the 640 X 200 screen in bitmap mode!
    That means you can have twice the resolution of the C64 or C128 in composite mode!  And since it is a RGB display, the graphics are crisper and cleaner than ever.  In case you are interested, 640 X 200 is as high of resolution as the IBM PC or even the AMIGA can do (in none interlaced mode).     The 8563 has a special 16K RAM area completly separated from the normal system RAM, so no user RAM is needed for the display.  However, trying to communicate with the chip is very difficult because of that very reason.  In fact there are only two addresses in the whole C128 memory map that have any effect on the chip at all.  These registers, $D600(54784) and $D601 (54785) serve as a window from which you may address the chip registers and its 16K RAM bank.  The first, $D600 is the 8563 register select byte, and the second $D601 is the 8563 data I/O byte.     To access the chip you must put the chip register number you want to read or write to into $D600, wait until the chip is ready, and then peek or poke the value you want into $D601.  It is quite a bottleneck, and effectively precludes any usable hires graphics from basic using peeks or pokes.  But from machine language it is a different story.
    We have created a set of commands that are wedged into the C128 that use machine language to take advantage of the C128's 640 X 200 graphic power.  These commands will give you a very powerful command set that works with BASIC 7.0 and allow you to use these new graphics freely.
    There are 14 new commands, most of which are used to work with the 640 X 200 display. One, @FONT, is a special command only for 80 column text mode that allows you to download new character sets from system RAM to the 80 column chip RAM.  Since the 80 column text screen allows for 2 complete character fonts at once you can use @FONT for some very interesting text displays.

   C128 ULTRA HIRES COMMAND SET
@FONT,Char Set #,RAM Address
@TEXT         
@GRAPHIC,BC,FC
@CLR,Value
@DOT,X,Y,Mode
@DRAW,X1,Y1,X2,Y2,Mode
@BOX,X1,Y1,X2,Y2,Mode
@BAR,X,Y,dX,dY,Ht,Mode
@SAVE,Type,"filename" 
@LOAD,Type,"filename"
@CHAR,Charset Address,X,Y,Ht,Width,"string"
@COPY,SX,SY,dX,dY,Destination X,Desination Y
@STASH,Buffer Address,X,Y,dX,dY
@FETCH,Buffer Address,X,Y

    Along with this article there are a number of programs.  The first is called  C128 ULTRA HIRES.  It is a basic loader type of program that will poke the machine language into memory for you and save the program as a small machine language module called ULTRA HIRES that can be easily loaded into memory.  The second program is called ULTRA HIRES BOOT and should be used to load ULTRA HIRES and setup the computer for its use.  You should run it only once, as ULTRA HIRES creates some tables that cannot be written over.  The best method is to use the C128's autoboot feature and create an autoboot disk that loads and runs ULTRA HIRES BOOT for you.  This boot does several things.  First it issues a GRAPHIC 1,1:GRAPHIC 5 command.  This is the only time you should use the normal GRAPHIC command.  It allocates a 9K area in the computer to be used for composite hires graphics.  Since we are going to be using the new ULTRA HIRES mode, this area can now be used to hold the machine language commands in the wedge.  Next it pokes the start of basic variables in bank 1 up 16K, giving us a 16K RAM buffer for the @STASH command.  It then loads the ULTRA HIRES ML module, and activates it with SYS 8448.  At this point you now have the wedge active.
   The third program is called PROGRAM BASE, and is intended as a base from which you can start writing your own programs.  It begins by going into FAST mode.  One of the nice features about the 80 column chip is that you can use the FAST command to allow the computer to run at 2 mH instead of 1 mH (in composite mode the screen goes blank during FAST mode).  Next, it issues the poke to set up the 16K buffer for @STASH (see @STASH later in this article for information about increasing or decreasing the buffer).  The new @GRAPHIC command is issued next, going to ULTRA HIRES mode and setting up background and foreground colors.  Line 50 issues the @CLR command with a value of 0, which will clear the 640 X 200 bitmap display.  And line 60 sets up the BASIC 7.0 TRAP command.  This is very important because in case of a syntax error or program crashing it will instruct the computer to go to the line following the TRAP instruction.  Here it goes to line 10010 which gets you out of ULTRA HIRES mode, prints the line that has the problem (with the HELP command) and ends the program  Even pressing the stop key is handled by the TRAP statement.  It is highly recommended that you include it in your programs.
    Next are five short demos that use various forms of the new command set.  The first is an example of the versitility of the @CHAR command, which allows many different sizes of text (and many different styles) all at once.  It even has a special form that will give you 160 columns on one line!  Imagine the possibilities!
    The second demo program is a simple line drawing demo that creates a very interesting graphic effect called a MOIRE pattern.  It looks very good in 640 X 200.
    The third demo is one that uses the 3D bar command.  This command allows you to create 3 dimension bar graphs so easily it will amaze you (and your friends)!
    The fourth demo uses basic to create circles, and the circle routine could very easily be modified for use as a general purpose subroutine.  After the circles are drawn, it uses the @COPY command to duplicate them, and then the @STASH and @FETCH to create a form of animation called BLITTERS.  That's right, the C128 now has blitter graphic capabilities.  (Blitters are a form of high speed bitmap transfers.)
    The last demo is I think an extremely impressive demonstration of the power of the new commands.  It creates a fully animated demonstration of a 3 dimensional cube rotating and changing size in real time.  It uses the @STASH and @FETCH (and a 32K @STASH buffer) to effectively create a small movie.  I think after seeing this you will be highly motivated to begin using these new basic commands on your C128.
    The memory organization of the C128 is a very complex subject, and we cannot go into it in detail in this article.  However, you need some information to use the ULTRA HIRES command set effectively.
    In an unexpanded C128 there are two banks of RAM, bank 0 and bank 1.  Bank 0 is where your basic program resides, and bank 1 is where your variables are stored.  When you enable the normal composite bitmap graphics display with the GRAPHIC 1,1 statement the C128 moves your program in bank 0 up 9K to make room for the graphic screen and its color memory.  That's why the ULTRA HIRES BOOT program issues it as its first statement.  This area can now be used to store the machine language program that gives you ULTRA HIRES mode.  If you were to use it again in a program while in ULTRA HIRES mode it would erase the whole program and crash the computer.  This is true of GRAPHIC multicolor composite bitmap mode also.  You should never use it in your programs while ULTRA HIRES is enabled.  The same thing is true of the command GRAPHIC CLR, which de-allocates the 9K, making it available for basic.  And the command SCNCLR should never be used either for the same reasons as GRAPHIC.
    Bank 1 contains around 64K to be used as variables.  Registers 47 and 48 contain the address for the start of basic variables. The normal value for 47 is 0 and for 48 is 4 (this is the address $0400 in hex and 1024 in decimal).  Everything above that is used for variables.  But by poking a larger value in register 48, followed by the basic CLR command, we can trick the C128 into giving us some RAM we can use in our programs.  The ULTRA HIRES BOOT program automatically sets up a 16K buffer.  You can increase or decrease this by changing the contents of register 48. (Be careful not to make it less than 4!)  If your program will use a lot of variables, and won't be using @STASH and @FETCH you might want that RAM to be used for variables so start off with the line;
   POKE 47,0:POKE48,4:CLR
However, some programs (like the 3D cube demo) require even more RAM in their buffer, so they increase the size by poking to register 47 and 48.
   POKE47,0:POKE48,132:CLR
This gives a 32K buffer for you to store graphics in, but you have now cut your variable RAM in half.  You will have to decide if you need to change it.  In most cases the default of 16K will be sufficient.
   One other thing.  Since the screen resolution is 640 X 200, that calculates out to 128,000 bits, or 16K of RAM.  That's exactly how much RAM is available to the 8563 chip.  That does not leave any RAM left over for 80 column text mode.  If you need to use the text mode and have an important screen in hires, you will have to save it (to disk or in the @STASH buffer), go to text mode with @TEXT, perform your needed function, return to ULTRA HIRES mode with the @GRAPHIC command and restore your screen from the buffer or disk.  When would you need to do this?  One time might be if you need to input some value from the keyboard while the program is running.  As you know, the input command will print a question mark (?) on the text screen.  But in ULTRA HIRES mode there is no RAM left for the 80 column text screen, but the operating system will still put the question mark in the area where the text screen should be.  This results in the corruption of a small part of your ULTRA HIRES screen.  So plan your inputs carefully to be in only text mode, or use the GETKEY command.
                                              DESCRIPTION OF C128 ULTRA HIRES COMMANDS

@FONT,Char Set #,RAM Address
   This command allows you to display (in 80 column text mode) character fonts different then the default character set.
   There is room in the 8563 RAM for two sets, and they are normally the uppercase/graphics set and the     lowercase/uppercase set.  If you have access to other fonts that you wish to use, simply BLOAD them to some area of RAM in bank 0 (in direct or program mode) and issue the @FONT command.  The Char Set # is either 0 or 1, and the RAM address is the location where it was BLOADed to.
   You can change character fonts by pressing the SHIFT/CBM keys or by printing CHR$(14) or CHR$(142).

@GRAPHIC,BC,FC
    This turns on the 640 X 200 bitmap mode.  Bc is background color and FC is foreground color.  When in ULTRA HIREs mode you are limited to 2 colors only, but you can choose which ones with this command.

@TEXT
   This turns off the ULTRA HIRES mode and returns you to the normal 80 column text screen.  You also return to the standard character font, so you will have to issue the @FONT command to re-enable any extra text fonts you want.

@CLR,Value
    This is used to clear the ULTRA HIRES screen.  Use a value of 0 to clear it, 255 to fill it.  Others can be used for special effects.

@DOT,X,Y,Mode
    This is used to plot a dot on the 640 X 200 screen.  X is from 0-639, while Y is from 0-199.  Mode is either 0 (for erase) or 1 (for draw).

@DRAW,X1,Y1,X2,Y2,Mode
     This is the line drawing command.  X is 0-639, and y is  0-199.  Mode is the same as in @DOT.

@BOX,X1,Y1,X2,Y2,Mode
     This will draw a box on the 640 X 200 screen.  X1,Y1 are the coordinates of the upper left corner, and X2,Y2 are  those of the lower right hand corner.  Again X is 0-639 and Y is 0-199.  Mode is as in @DOT.

@BAR,X,Y,dX,dY,Ht,Mode
    @BAR draws a 3D bar of a given Height.  X,Y are the coordinates of the lower left hand side of the bar,  dX and dY are the depth and width you wish.  Ht is the height, and Mode is as in @DOT.  X is 0-639,  Y is 0-199, dX is 1-255, dY is 1-199, Ht is 1-199.
     The sum of Ht and dY cannot exceed 199 or no bar will be drawn.

@SAVE,Type,"filename"
   This will save a screen called 'filename' to disk.  There are two types of save.  A type of 0 will be a normal 16K screen dump, which will give a disk file of 65 blocks.  A type of 1 will be a special compressed form of save, where an intelligent data compression will compress your screen to its smallest possible size.
   In some cases it can cut the 65 disk blocks down to only a couple blocks.  The actual amount of reduction will depend upon whats on the screen.  It will never be bigger than 65 blocks.  In most cases this will be the best way to save your screens.

@LOAD,Type,"filename"
     This loads a screen called 'filename' from disk.  Type is either 0 or 1, depending on how it was saved.

@CHAR,Charset Address,X,Y,Ht,Wd,"string"
  This is the high resolution character driver.  It allows you to print on the 640 X 200 bitmap screen in many sizes and styles.  X is any number 0-639, Y is 0-199, Ht is 1-16, Wd is 0-16 and string is what you want it to print, either  in quotes or as a string variable.  The address is where in RAM you want the character set to be taken from.  You can use the built in sets at 53248 and 55296, or you can BLOAD in others into RAM and use them.  Built into the machine language is a special font that allows 160 characters per  line.  Its address is at 7168, and it requires a width of 0.
    You can use almost any character set made for the C64 or C128, as long as they are binary files.  Chexk your users group library for extra fonts.  Chances are they will have many.  You can also use special control codes inside the string, like reverse on and off.  Control E causes the text to erase anything under it, while Control X will perform an XOR on the screen, leaving anything there still visible.
    You can also underline your text with Control U, and turn  off underlining with Control N.  Color codes have no effect.

@COPY,SX,SY,dX,dY,Destination X,Destination Y
     @COPY will allow you to duplicate any area of the screen to any other area.  SX,SY are the starting coordinates of the upper left hand corner you wish to duplicate.  The dX and dY are the lengths (in pixels) you want to copy from SX,SY.
   The dX is from 1-640, and dY is from 1-200.  Destination X and Y is the X,Y location to move the copy to.

@STASH,Buffer Address,X,Y,dX,dY
   @STASH allows you to store a piece of the screen to a buffer and then recall it when needed.  X and Y are the beginning upper left corner to stash, and dX and dY are the lengths.
   You can store a piece as small as a byte, or as large as a screen. The buffer address is where in the buffer it is to be stored.  The buffer value starts at 0, so the first thing you store should go there.  You will need to know where it ends in the buffer so you can store other stuff after it.
    You can find the next available buffer address with; AD=PEEK(250)+PEEK(251)*256+1
    You must do this immediately after the @STASH command.
     AD now has the address of the next available buffer address.  You must keep these address stored so you can recall them  with the @FETCH command.

@FETCH,Buffer Address,X,Y
   This will recall the stored area at buffer address and put it at X,Y.  No other information is needed, as the @STASH saves the length and depth of the area.
     @STASH and @FETCH are very rapid, fast enough for some types of animation. See the circle demo and 3D cube demo programs.
    There are a lot of things this chip can do that most people are unaware of.  It can scroll, it handles light pens, double pixel modes, interlaced modes and more.  We have only began to explore it, and the wedge is written to make it easily expandable to handle new commands.  Perhaps a hardcopy command, or a fill.  Thats why we left some room for growth in the program.  We have set aside 9K of RAM, but the program only goes from 7168 to 12992.  That leaves us room to add even more commands in the area from 12992 to 16383. You could use that free ram for character set storage for now, but be careful and don't disturb the ram from 7168 to 12992.
    We would like to thank Andy Finkle and Caroyln Sheppner of Commodore for their kind assistance on the technical aspects of the 8563 chip.
   If you have questions about Ultra Hires, you can write to the authors (Louis Wallace and David Darus) at:

6124 B SW 11 PL
Gainesville, FL  32607

     Or, you can leave Q-Link mail to LRW.
-----------------------------------------------------------------------------

C-128 Ultra Hi-Res Graphics, Part II
RUN Magazine, May 1986

By David Darus, Ken French and Louis Wallace

     Increase the flexibility of your existing C-128 Ultra Hi-Res program with this set of powerful and swift graphics commands.

RUN It Right
C-128(in C-128 mode)

Listing 1. UH.DATA program.
Listing 2. MAKE UH V1.1
Listing 3. UH. PIC CONVERT

     Address all author correspondence to Louis Wallace, 6124B SW 11th Place, Gainesville, FL 32607 or David Darus, 2508 NW 65th Terrace, Gainesville, FL 32606.
     In RUN's February 1986 issue, we announced that the C-128 was fully capable of using its 80-column RGB mode for ultra high-resolution (640 by 200 pixels) graphics.  We also introduced you to the C-128 Ultra Hi-Res graphics language.  This month, we will expand on that topic with several new additions to the command set.
    C-128 Ultra Hi-Res is a language that wedges itself into memory so that its commands are executed along with those of the normal Basic 7.0.  Without slowing down normal Basic, it accomplishes this by intercepting the Syntax Error subroutine that issues error messages when you make a typing mistake.
    All Ultra Hi-Res commands are preceded by the @ symbol, which is not used by Basic.  When the C-128 Basic interpreter encounters this in the context of a command, it passes control to the Syntax Error subroutine, which would normally display a syntax error message and stop the program.
    However, we have changed the vector that points to that subroutine. Instead, it points to a machine language subroutine that checks to see if the error is truly an error, or one of our new commands. If the latter, control is passed to the appropriate Ultra Hi-Res module; if not, it jumps to the normal Syntax Error subroutine.
    The advantage of this wedge over others is that it allows Basic to run at top speed and only checks for our routine when they are encountered. If you combine this with the Fast command, which operates at 2MHz, you'll have your C-128 running at full throttle with many new and powerful graphics commands.
    To use Ultra Hi-Res, part 2, you'll need a copy of part 1. You will then combine all the commands to form an enhanced version -- Ultra Hi-Res Version 1.1.

The Ultra Hi-Res 1.1 Programs

    Three programs accompany this article. Before running them, save them to a disk containing both the old machine language version of the Ultra Hi-Res program and its Boot program.
    First, load the program called UH.DATA (Listing 1) and run it in normal C-128 80-column mode, not in Ultra Hi-Res mode. It will create a number of binary files on the disk.
    After running Listing 1, load and run the program called MAKEUH V1.1 (Listing 2). This program will first load into memory the old version of Ultra Hi-Res, then it will add the new modules. It will also rename the original version to Ultra Hi-Res.old and save a new version called Ultra Hi-Res. Ultra Hi-Res 1.1 is now ready for use. To activate it, load and run the Ultra Hi-Res Boot program, as you used it to load the original Ultra Hi-Res program.
    The final program is called UH.PIC CONVERT (Listing 3). We've changed the original picture-file format to allow upward compatibility of Ultra Hi-Res pictures in future applications programs. Listing 3 allows you to change pictures made with version 1.0 to this new format. Place in the drive a disk that contains the pictures you want converted and answer the prompts. Your old Ultra Hi-Res pictures will now be fully compatible with Ultra Hi-Res 1.1.
    Finally, to legally use this program to create applications you wish to give away, you must use the fifth new command, @WALRUS, which creates a logo crediting the program's authors. It is your legal obligation to display this logo for any non-personal use. (If you intend to sell your applications, please contact the authors about licensing.)

The Commands

    Part 2 adds five new commands that give professional-level graphics power to the already-powerful Ultra Hi-Res command set. Combined with the C-128's large memory and 2 MHz clock speed, you will be able to use Basic to write very impressive applications programs.
    The first new command  @CIRCLE is also found in normal 40-column Composite mode and functions in the same way; however, with Ultra Hi-Res 1.1, you can only have two colors on screen at once, rather than the 16 available in 40-column mode. To compensate for this loss of color, you can change your drawing mode from draw to erase. The syntax is:
@CIRCLE,mode,cx,cy,xr,yr<,sa,ea,angle,increment>
    Mode is 0 for erase and 1 for draw; cx is the x coordinate of the center (0-639); cy is the y coordinate of the center (0-199); xr is the x radius (1-319); yr is the y radius (1-100). The parameters within the brackets, <>, are optional. The sa is the starting angle (0-360); ea is the ending angle angle (0-360). These allow you to draw arcs easily. The angle is the number of degrees (0-360) you wish to rotate the circle, ellipse or arc. The increment is the number of degrees used in drawing the circle. By changing the increment, you can use the Circle command to draw polygons.
    The defaults for the optional parameters are: sa=0; ea=360; angle=0; and increment=8. For more information on the circle parameters, see the C-128's system guide.
    The second new command is called @PAINT. Unlike the 40-column Paint command, this one only provides one color at a time. This could be a problem when it comes to graphics and charts. The @Paint command compensates for this paucity of colors by allowing you to fill areas with varieties of different patterns. The syntax of the command is:
@PAINT,x,y,mode<,p1><,p2><,p3,p4><,p5,p6,p7,p8>
    Here x is any value from 0-639; y is any value from 0-199; and mode is  0 (for erase) and 1 (for draw). The p values are numbers from 0-255 and represent the decimal value of the binary pattern used in the fill. For example, if you wanted to generate an interesting patchwork pattern to fill an area, you would use the following values.
01100110  102
11001100  204
00110011   51
10000001  129
10011001  153
01111110  126
00000000    0
10101010  170
    The command format is:
@PAINT,x,y,1,102,204,51,129,153,126,0,170
    This will fill a specified area with that pattern. If you do not enter any specified values, the area will be filled with a solid pattern. By entering only one number, its pattern is repeated eight times; if you enter two numbers, the pattern of the pair is repeated four times; if you enter four numbers, each pattern is repeated once.
    You can clear a solid area (not a pattern) by using a mode of 0. You must make sure the area to be filled is completely enclosed or the pattern will leak out and fill the screen.
    The third command is @HCOPY. This will dump the graphics screen to a printer in any of four different sizes. The syntax is:
@HCOPY,size, secondary address
    The size is from 1-4, and the secondary address is whatever your printer interface requires for Graphics mode with no linefeeds. For example, the Cardco B and PPI with Graphics interfaces require a secondary address of 5. At the moment, only the Epson, Mannesman Tally Spirit 80 and Olivetti PR2300 printers are supported, but additional modules will be added if the demand is there.
    The fourth command is @DRWMOD. This sets up a special form of the Draw mode that performs an XOR on the screen when you use anay of the drawing commands (Dot, Line, Box, Circle or Bar). It reverses lines on the screen. This command allows you to create the illusion of transparency when two points overlap. The syntax is:
@DRWMOD,mode
    The mode is 0 or 1, with 0 indicating no complement and 1 indicating complement.

A Gem of a Program

    You don't often find a graphics utility that enhances the usefulness of a computer for personal and professional applications. Ultra Hi-Res is a rarity that greatly extends the already-powerful features of the C-128. You will most likely discover many ways to use this new graphics power.
    Look forward to more articles on the inner workings of the 8563 video chip. Ultra Hi-Res is only one aspect of what this chip is capable of accomplishing.