Document name: README.TXT
Author:	Tommy Grandefors
Date: 27th of January 1997
Place: Karlshamn/Sweden
e-mail: pt94tgr@student.hk-r.se

Hi!

This document will describe the basic procedure of how to program the SVGA modes on your videocard. I've also included some source code with their corresponding executables and makefiles in two directories whithin this zip-file. The source code is written in C++, and will show you how to set four different SVGA modes. PutPixel() and GetPixel() methods are included, and also a ClearScreen() method is available in the source code. The source code is compiled with Watcom's 32-bit C++ compiler 'wpp386'. The Rational System's dos extender 'dos/4gw' is skipped due to the fact that not all people have the Watcom compiler, but still wants to run the executables. Therefore, the internal linked extender 'pmodew' is used instead.

First, what is the real meaning of this document and do we really need it?
Well, I don't know. But I now for a fact that when I started out to program the SVGA card for a couple of weeks ago, I had major problems to find the correct information on how to handle the card in a simple but still correct manner. In most documents they just talked about it in a very theoretic point of view and did not show much source code at all on how to perform bank switching and calculate new x and y values after bank switching. Very often they tend to refer to books such as "Programmer's Guide to the EGA and VGA Cards - Includes SVGAs, Second Edition" by Richard Ferraro, which is a very good book though, and, of course, to the VESA specification.
I think that this document is ment for you who don't have the patience to go through tons of books of information and specifications, and for you who just want to take a first look at what SVGA may offer you as a programmer. And of course for you who wants to start programming the SVGA card in a simple and quick way.

Enough talk, let's go.

The SVGA modes are characterized by the high resolutions they provides you. They offers a wide range of resolutions, where the most common ones are:
640x480
800x600
1024x768
1024x1024

These resolutions can use a color resolution of 8-,16-,24- and 32-bits (these are most common) depending on your videocard and how much video memory is available .
In this document (and the source code) I will concentrate on the SVGA screen resolutions mentioned above, with an 8-bit color resolution (i.e 256 colors).

Ok, how do we program the videocard to be able to set a SVGA mode?
First I need to explain the difference between the SVGA and VGA.
If you have any earlier experiences with the popular video mode 13h, you will have noticed that this mode is a chained (all four bitplanes are chained together in hardware to facilitate a linear addressing method instead of a planar one), linear, 256 colors VGA mode with the resolution of 320x200 pixels. The linear addressing provides you with an easy access method to program the videocard in a simple and logical way. To draw a horizontal line  from the screen's upper left corner with a lenght of ten pixels with color  value 13, you just do this: memset((unsigned char*)0xA0000,13,10);.
Simple eh?
When you are using the planar addressing method things starts to get worse.

The good news about SVGA is that your are able to use the linear addressing method. The bad news is that SVGA will force you to switch banks when you are  going to put a pixel (address the video memory) in a position greater than the size of the current bank.

Que?

In VGA when using mode 13h, you don't have to switch a bank because there is no need for it. You are able to address the whole screen (320x200) within a single memset() function. 320x200 pixels gives you a total size of 64000 bytes to adress within the 0xA0000 segment. Since a segment has a total size of 65536 bytes, there is no problem to address the whole screen using the resolution of 320x200.
What happens if you are trying to put a pixel in the position x=400 and y=300  in a SVGA mode? Since 400*300 equals 120000, this value will go far beyond the segment limit. So ,you'll have to switch to the next bank to perform this  task in an accurate way.

Since one bank has the size of 65536 bytes, and you are, for example, using the resolution of 640x480 pixels, you will have a total number of 4.69 pages (banks) to switch and address to be able to use the whole screen (640*480/65536=4.69). Since, of course, you can't switch a 0.69 page, this means you will be able to use 4 full pages and 45056 bytes of the last page ((640*480)-(65536*4) = 45056 bytes).
This means that each segment will allow you to draw 102.4 lines (65536/640=102.4), using the screen width of 640 pixels. This also introduce another problem to us: we will have to re-calculate the x and y positions of the pixel to be drawn if we address the pixel beyond the 65536 bytes limit, this due to the fact when we switch a bank the start address of the new bank will still be at 0xA0000, but 65536 bytes further up in video memory. If we put a pixel at 0xA0000 using the first bank, the pixel will be seen in the upper left corner of the screen, but when we switch to the next bank and put another pixel at the address 0xA0000, the pixel will be seen 65536 bytes (on line 102) away from the upper left pixel.

I still think the best way to understand it all is to examine the source code and then do your own changes to the code to see the effects. Learning by doing is the best way to learn!

As mentioned before, the source code is stored in two different directories: 'optimize' and 'nonoptim'. The code in both directories will have the same functionality, but they differ in performance. The optimized source code uses pre-calulated tables to, for example, calculate new x and y values, bit shifting instead of multiplications and divisions, and other optimizations such as only try to use multiplications and divisions during the initiation of required tables. This code is also harder to read and understand for the un-experienced programmer not so familiar with C/C++.
The example programs will do this: ask the user for which screen resolution to use and then fill the whole screen using the PutPixel() method (in vertical lines instead of horizontal ones, this will produce more bank switching). The user will then have to press a key to quit the program. The program will show you the time it took to fill the screen with this method. You will notice that the optimized version is more than twice as fast as the other version.

Ok ,that's all folks!
Good luck and enjoy the SVGA.

By the way, if anyone out there know how to perform page flipping in SVGA, scroll, or  want to share the knowledge of how to best get most performance out of the SVGA card, please send me an e-mail.

Best regards.
/Tommy Grandefors

Oh, I almost forgot.
Since people, mostly from Yankee-land, are used to sue each other from time to time, I'll have to protect myself from hungry lawyers.
It's hardly likely that this document or the other files included in this packet will damage you or/and your computer or/and your monitor.
Just be sure your monitor support the higher resolutions.

But anyway, eat this:
I will take no responsibility for damages caused by files/programs containd within this packet. If you fuck it up, you're on your own and won't find me liable for its consequences.
