
                       SVGATextMode
                       ============

INTRODUCTION
------------

This program is designed to greatly improve the normal (EGA-based) textmodes
on your Linux machine. It uses an Xconfig-like configuration file to set up
better looking textmodes. (=higher resolution, larger font size, higher
display refresh...) This is already a big boon on normal 14" displays, and
it is an immense difference on larger and better (15" and up) screens.

It stems from the idea that it is a real waste of hardware to use EGA
textmodes on an SVGA-card, which was designed to do much better than that.

Even the cheapest state-of-the-art VGA cards are capable of running at well
over 60 MHz pixel clocks. But most of the time they are used in text-only
mode, and at 80x25 chars (that looks RIDICULOUS on a 20" screen!), using a
mere 25 MHz clock? At best, they use 132x43 textmode, which is still only a
40 MHz clock.

Even the cheapest SVGA monitors can take at least 38 kHz of line-frequency,
and if you go for a 15" or higher, 56 kHz and up are no longer the
exception. But most of the time they are used only at 32 kHz for either
80x25 or 132x43 modes. ALL VGA textmodes use just the standard VGA 32 kHz
horizontal refresh. If you are the owner of such a monitor, don't you think
it's a shame you only use one fifth of the available resolution in text
mode? Especially if you see what that monitor/SVGA-card combination can do
under Windows or X-Windows.

If you own a VGA card that is NOT detected properly by the kernel (e.g. a
Diamond card), you normally can use only 80x25, 80x28 and 80x50 modes. If
you want to use any other mode (which might or might not be available
through the BIOS) you had only one option: patch the kernel to force
detection of your card. And then you can still only use what your VGA BIOS
manufacturer put into the BIOS. Now you can use this program to get ANY text
mode, independently of BIOSses and detection by the kernel! Only limited by
what your SVGA-card and your monitor can take.

People doing lots of programming, and who don't want to sacrifice speed
(text modes scroll extremely fast) and memory (Xwindows is a real memory
hog) for a nice-looking display will really benefit from this: you get the
graphic detail and high refresh rates of X-windows, with the speed and
ease-of-use of normal text modes. It doesn't take up any more memory than
normal text modes, and it doesn't slow down your machine!

Even if you want to stick with what you had (e.g. 132x43), this program can
help you improve that, too! The so-called "high-res" 132x43 is not that nice
to look at. It uses an 8x8 (sometimes 8x11) pixel font, which shows up as
characters made up of stacked lines. Makes your screen look like in the old
days, when monochrome 80x25 was the standard, and you could actually count
on-screen how many lines your character was made up of. Now you could use
the same text mode, but with a 16-pixel high font, resulting in MUCH crisper
characters, and, if you want, higher refresh (less flicker).


With this program, you could do the following things (providing your video
card is supported, and providing your monitor can handle it, and providing
your video card still works at the higher dot-clock rates):

   50x15 text mode, for those with a visual impairment?
   80x25 text mode with a 32-line character cell (VGA = 16 line)
   80x25 at 100 Hz, or even 150 Hz instead of "just" 70 Hz (= VGA)
   80x25 at 16 kHz interlaced, so you can show your text mode
         on a TV monitor, or tape it on a VCR... (interlacing not supported
         YET. If anyone needs it, let me know)
   100x37 text mode. My favourite for 14" screens. Not available on
          most VGA cards as a standard (some Cirrus Logic cards have it).
          Now everybody can have it. Looks real neat!
   132x43 improved over VGA default: 8x16 character cell instead of 8x8.
          looks MUCH better, especially on 15" (and up) screens.
   110x42 why not? everything is possible...
   160x100 !!! We've tried this on an ET4000 and it's a screamer. On very
           large screens (>17"), this is REAL cool.

And since it uses the same kind of configuration file as the XFree X-server,
it can do everything the X-server can, but in textmode instead of graphics
mode. With a little bit of imagination and clever thinking, you can get
almost any resolution at almost any refresh rate. 

Another possible application: do you have some (old ?) workstation monitor
somewhere, which you would LOVE to use under Linux, but it is a
fixed-frequency one (= only works at ONE, mostly high, horizontal frequency,
say 56 kHz), which does't support standard VGA modes, and thus doesn't
support normal text modes? You would have to start up in X-windows
immediately (xdm) and do all your work from X-windows. But that eats too
much memory, and you have only a Trident card, which is MUCH too slow for X.
Enter "SVGATextMode": now you can be in textmode, at the same 56 kHz
frequency (1024x768 at 70 Hz) as you would in X-windows, on that big 19"
SparcStation monitor you bought for virtually nothing (keep on dreaming ;-)


How to go about and create your own text mode
---------------------------------------------

First of all: if you are not familiar with configuring the X-server, you'd
better start off there, as it is MUCH more stable, MUCH less buggy, and MUCH
better documented. You will also learn how to use several tools (vgaset(*),
SuperProbe, ConfigXF86, ...) which can aid you to design your own custom
X-Windows mode. The same tools can then be used here.

For people less familiar with monitor timing stuff, and unwilling or unable
to consult the XFree86 documentation, read the "general notes on monitor
timings" section below. It's a small (and incomplete) introduction on how
monitors work, and what you need to send it to get some sort of a picture
on it.

You will probably need the X-server (e.g. to do 'X -probeonly') to determine
your available pixel clocks, and maybe even to determine what chipset you
have.

    (*)NOTE on vgaset: vgaset has this really weird tendency to "change"
    vertical timing parameters before showing them to you. As an example, look
    at this line of output from vgaset:

    kmg> vgaset
    1056 1072 1232 1280     960 978 982 1042

    It was executed on a TVGA8900CL card, in textmode, at 132x60 character
    mode (NOT changed with this program: this is the standard BIOS text
    mode). If you calculate frequencies from those numbers, you get a
    Horizontal frequency of 40.00/1280 = 31.250 kHz (OK!), and a vertical
    frequency of just 31250/1042 = 30 Hz. Now that is LOW. In fact, I KNOW
    it is 60 Hz, like most textmodes (some are 70 Hz, but NONE are 30 Hz. 
    Nobody would settle for that). I have my own program to read VGA
    registers, and THEY show all vertical timigs to be HALF of the ones
    shown by vgaset. So it REALLY is:

    1056 1072 1232 1280     480 489 491 521
 
    I have NO idea why vgaset does this. I checked the code, and there
    actually is a routine in there that doubles all vertical timings (before
    printing them) repeatedly, until the total vertical size is AT LEAST
    half as much as the total horizontal size. In our case, 521*2 is less
    than 1280, so it doubles the vertical timings ONCE, since then 960*2 IS
    greater than 1280...
    
    The timings that vgaset actually uses to program the VGA chip are the
    REAL ones (before that doubling process). So if you run vgaset on a
    132x60 character text display, and use THOSE timings, you might run into
    a real surprise, because if you type the timing-line from vgaset into
    the TextConfig file for this program, it will give you a 132x120
    character display at 30 Hz !!! 
    
    I know of NO way to find out if vgaset is lying to you, except by
    pulling the register contents from the chips with another program, or
    using your common sense, and do some calculations before blindly copying
    vgaset timings!


The TextConfig file
-------------------

The "REPORT" file in this distribution should contain an up-to-date list of
all supported chipsets, and on which specific boards it has worked at least
once ;-)

General guidelines:

  * The TextConfig file MUST be in your /etc directory. If you don't like
    that, change the appropriate line in the Makefile and recompile. It
    should be straightforward.

  * remarks can be inserted after a '#' (hash) sign. Everything after the 
    hash sign will be disregarded.
    
  * You may (or may not) enclose certain strings in double quotes (") if you
    like, but they are NOT used in any way. They are only of "cosmetic
    importance".
    
  * empty lines are allowed.
  
  * Read the comments in the TextConfig file as well. They explain some
    modes as they come along.


CHIPSET  

First of all, you have to define which chipset is on your VGA card:

   ChipSet "ET4000"
   
To see what other chipsets are available, type "SVGATextMode -h" or see the
"REPORT" file.


OPTION

Special option flags:

  until now, only the ET4000 needs one extra flag: 
  
  Option "hibit_high"
       or
  Option "hibit_low"
  
  See the XFree86 documentation for more information. The file README.Tseng
  from the XFree86 package, included in this archive, should be able to help
  you define the correct "hibit" flag.
  
  
CLOCKS

Then, you need to define what clocks you have. Again, you can get those from
your X-server by typing "X -probeonly" (without the quotes). 

    Note: Cirrus Logic cards DO NOT NEED A "Clocks" LINE (if you select the
    "CLGD542x" chipset, any "clocks" line will be disregared).

 Clocks 25.3 28.175 ....
 
The order of the clocks in this line MUST be the same as on the card: the
first one will be programmed as clock number 0, the second as number 1, etc.
Again, if you are familiar with configuring The X-server, this should be all
too obvious to you.
 
WARNING: define only the clocks you have, since this program justs assumes
they are correct. Even if your card has only 8 clocks, and you define 16 of
them, it will still try to program one out of 16 clocks. Without warning.
This should change in the future...

And also: the program assumes the clock VALUES are correct. All timing
parameters that you are given at the end of the program are based on those
numbers! So if you say that clock number 3 is 40 MHz while its REAL value is
75 Mhz, the Horizontal and vertical frequencies given at the end will be
incorrect by the same ratio!

NEW: support for external clock program! Still experimental though, but it
made the thing work for an S3-based Diamond Stealth 64, which used that
ICD2061 programmable clock chip. Use

  Clocks external <path>
  
to call the program, instead of putting clock values on that line. This
interface will change in the future, but at least it works. The program MUST
take JUST ONE argument: the clock frequency in kHz. The path must be a FULLY
SPECIFIED PATH. No environment variables will be used. If your clock
selection program uses another interface, use a script that calls that one.
There is an example in the Diamond directory (a full copy of the
speedstar-fix.tar.gz file from somewhere on the Internet. Thanks). I added a
script that calls "freq" with the correct parameters "SVGATextMode_freq". It
worked for me...


TEXT MODE LINES

Let's analyse a new text mode:

  "100x37"  50   800 848 880 1032    600 600 606 630   -hsync -vsync font 8x16

  <---1-->  <2>  <------3------->    <-------4----->   <-----5-----> <---6--->
  
  (1) This is the identification string for this text mode. If you the type
      "SVGATextMode 100x37" the program will try to program this one. 

  (2) The pixel clock frequency. Since all VGA cards can also use every
      clock divided by two, a clock of 50 MHz can also be called upon as 25
      MHz. The program will automagically make the VGA card divide it by
      two.

  (3) Horizontal timing parameters (active video size, start H-sync, stop
      H-sync, end video-line). See the XFree documentation for a thorough
      understanding of these, or try the section om monitor timins below.
      See also the TextConfig file for some explanation on the effect of
      selecting an 9-pixel font on these timings!  Your textmode will have
      one eighth the number of characters per line as in the active video
      size (the first number of the horizontal timing parameters) REGARDLESS
      of the font size specified.  So in this case : 800/8 = 100 characters
      per line.

  (4) Vertical Timings. Equivalent to the horizontal ones. The number of
      textlines (rows) in your textmode will depend on the font size
      selected: number_of_textlines = number_of_active_lines / font_height. 
      Here we have 600 active lines, and a font of 16 pixels high (see
      below), so there will be 600/16 = 37 textlines.
      
  (5) Hsync and Vsync polarity (positive (+) or negative (-)). Most modern
      monitors don't care about sync polarities, BUT most USE them.
      
      Simple fixed-frequency or dual frequency monitors (so non-multisync,
      e.g.  only 32 and 48 kHz, instead of the entire range from 32 to 48),
      and some non-digital-control ones use the polarities to change their
      vertical screen size.
      
      Cheap monitors have the habit of not having a constant vertical image
      size, independent of the vertical refresh frequency. So your monitor
      might use the entire screen at a normal 60 Hz frequency, but the image
      is larger at lower frequencies, and smaller at higher ones. These VGA
      monitors use the sync polarities to distinguish between several
      vertical refresh frequencies, and to adapt their vertical size. I have
      a MAG PMV1448, and it is a fine example of that. At 800x600@70Hz, the
      screen is either only half the vertical size, or the entire screen,
      depending on sync polarity. So some experimenting with polarities
      might give you a full screen, even with >70 Hz refresh rates. (The
      same applies to the XF86Config as well)
      
      More expensive monitors, mostly with "digital control", use the sync
      polarities COMBINED with the incoming horizontal and vertical
      frequencies to determine whether they will take their screen
      parameters (amongst which the vertical screen size) from a database of
      standard resolutions, or from the (scarce!) user-settable modes. If
      you succeed in using one of those default modes, that saves you one
      more free user-settable mode. Taxan 875 monitors for example have only
      4 programmable modes, and when you've just tweaked X-windows into some
      weird modes, you might run out of user-settable modes. It might be a
      good idea to try to create standard SVGA timings for your textmodes
      (including the correct sync polarities), so your monitor recognises
      them.

  (6) Font size: "font HxV" selects the horizontal size (character width =
      H) and vertical size (character heigth = V) of the textmode font. The
      possible ranges are:
      
        H = 8 or 9,
        V = 1 to 32 inclusive. Don't be surprised if you cannot
                               read text of only 1 pixel high!
        
      The VGA chip must know these values in order to render the font
      correctly. The font size together with the H- and V-timings from (2)
      and (3) determine the number of characters per line, and the number of
      lines per screen. 
      
*******************************************************************************      
*IMPORTANT: if you want to test a new mode, you'd better do:                  *
*                                                                             *
*              SVGATextMode -n <MyNewMode>          (note the '-n' option)    *
*                                                                             *
*           before doing the real thing (=without '-n'). This way the program *
*           will show you what the new mode will look like, WITHOUT really    *
*           changing anything.                                                *
*                                                                             *
*******************************************************************************

      And don't forget: no more than 16K (16384) characters on one screen!   
        

Font loading
------------

Once you selected a textmode, You might have to change the font in the VGA
card. If you started off from a standard 80x25 VGA resolution, then the VGA
card was loaded with an 8x16 font. But if your new resolution uses an 8x8
font, the characters will be cut off in the middle, and things will be hard
to read.

It might then be a wise idea to load another font into the VGA card. A
standard linux utility called "setfont" Is just what you need. If you do not
have it on your system, I have included a SMALL amount of fonts, and the
"setfont" program, just in case. The "Cyr_a8x##" (where ## is a font height)
files are some font files for setfont. The program and the fonts are
available in the "keytbls" package in the Slackware distribution, and of
course "on your favourite FTP site"...


Letting Linux know what you've done: stty
-----------------------------------------

When you change your textmode resolution on the fly, your (virtual) consoles
have to be made aware of the changes, or they'll continue to think you're
still in the OLD mode (whatever that was). All applications sensitive to
screen width and height will be affected by this (i.e. almost ALL of them).

You have to do AT LEAST an "stty cols xxx rows yyy" (where xxx= number of
chars per line in the new textmode, and yyy= number of text lines ) on EACH
virtual terminal you have (mostly 6). You could embed the call to
"SVGATextMode" in a shell script like this (to be run as root):

   #!/bin/bash
   #
   # This (minimalistic) script changes VGA textmode and terminal settings 
   # for 6 virtual consoles. This example is for a 100x37 character mode.
   echo "Changing to 100x37 character console"
   SVGATextMode 100x37
   setfont /usr/lib/kbd/consolefonts/Cyr_a8x16
   for NUM in 1 2 3 4 5 6 
   do
     stty rows 37 </dev/tty$NUM
     stty columns 100 </dev/tty$NUM
   done
   
If you are running any program that also depends on your terminal settings
(like "selection"), you will have to restart it.

Another thing to consider is the /etc/termcap file, or the terminfo
database. Some applications depend on one of these to perform text-screen
operations. If you define your own fancy text mode, you might have to add an
entry in the termcap file for it. An extra entry is fairly easy to create:
just copy an axisting termcap entry, and change all the appropriate numbers
in it to the ones you just created. For terminfo, you're on your own. I
don't know s..t about that.


Some general notes on monitor timings ("Monitor primer for the faint of heart")
-------------------------------------

All that fiddling with so-called "timings" might look a little dazzling to
you at first. That is because it IS weird. But even weird things can become
easy, once you understand them. Some more information might help you get
started. The following explanation is FAR from complete, and probably
oversimplified, but is might get some people going, and that's what it is
intended for.

1. introduction: a monitor

All picture-tube based monitors (=the heavy kind ;-) use the same principle:
a beam of light (or three for colour screens) scans the entire screen region
from left to right, and with every horizontal line, it moves a little bit
from top to bottom. It illuminates the screen on those places where the
driver (the graphic card in our case) tells it to. It does this so fast that
the eye cannot actually "see" the beam passing by. They eye is fooled by the
speed of the beam into believing that it sees an stable image on the screen.

Why do we need "timings"?

That beam of light has to "know" how fast it has to go from left to right,
and how many times it has to do that before starting at the top again. It
has to know when to move, and where to move to. So if you want it to move
repeatedly from left to right, you'll have to tell it when it must return to
the left again, to start another pass from left to right, just below the
line it has just drawn (because in that time, it will have moved a little
bit downwards, under control of the VERTICAL timing signals).

The same beam also has to know when to show a spot of light with a certain
intensity, and when to shut up because it will soon travel quickly back to
the left again, and you don't want to see THAT. What intensity it will have,
is defined by the data in the memory on your graphic card. HOW that's done,
is not your concern (at least not for THIS program).

In order to know WHEN it has to start on the left edge again, you need a
SYNCHRONIZATION signal ("sync" for short). When the horizontal sync shows
up, the beam has to move back to the left edge, so it can draw a new line.
Ideally, the beam would return to the left in no time, so it can start
drawing a new line right away. Alas, as with most things in nature, the
faster you want to move something, the more energy you'll have to put in.

And you don't want to pay a MegaWatt power-bill just because your monitor is
VERY fast at returning its beam to a new starting position, do you?

You will have to allow some time for the beam to hurry back to the left.
Some appropriately call it "flyback" time. That is why you need "BLANKING"
time. During that time, you cannot use the beam to show usefull information.
It must be allowed to "fly" back to the left, without you seeing it. i.e.:
it must be "blanked away" during that time. The better the monitor,the
faster the beam can be moved back.


2. The timing specification

And all those things are what you define in that 8-number string in the
TextConfig file (or the XF86Config file for X-windows). Look at this example
for out 100x37 text mode:

  "100x37"  50.00   800 848 880 1032    600 600 606 630   -hsync -vsync font 8x16
                    -----------------------------------
                 
This section will deal with the underlined part in more detail than in the
section explaining the entire line (somewhere before this one).

But first: the pixel clock. That is the second number in the entire
description line (50.00). 50 MHz = 50 MegaHertz = 50 million clock pulses
per second. A new pixel (dot) will be pulled out of the memory on your
graphics card, and sent to the monitor beam every clock cycle. Your video
card will essentially get a new dot and send it to the monitor 50 Million
times per second.

There are 2 groups of timings, with almost exactly the same meaning: the
first group of 4 is for the horizontal movement of the beam (left to right,
the "horizontal timing parameters"), while the second group of 4 controls
the vertical movement of the beam (top to bottom, the "vertical timing
parameters").

The first group of numbers (horizontal parameters) are in units of pixel
clocks: the clock in this case is 50 MHz, which means that each clock pulse
lasts 20 billionths of a second (1 / 50 million).

The second group of numbers (vertical parameters) are in units of HORIZONTAL
sync signals: this means that for each vertical counter increment, the
HORIZONTAL counter will count an entire cycle from 1 to 1032 (in this case)
clocks of 50 MHz. You'll need this knowledge to determine H- and
V-frequencies.

But what do all the numbers mean ?

Let's look at the horizontal timings: 800 848 880 1032

The first number (800) tells the VGA chip (and the monitor) how many "active"
pixels there are in each line. Those are the pixels you will be able to use,
those will contain the graphics or text on the screen. 

The last of the four numbers says when the ENTIRE video line is finished,
including syncs and blanking. In this case, the entire video line, including
the time for the beam to travel back to the left, must be finished in 1032
pixel clock periods. The time BETWEEN 800 and 1032 will be used by the
monitor to hide the fact that he is busy sweeping the beam back.

The second number (848) tells the monitor WHEN it must START sweeping back
the beam (= the start of the horizontal sync pulse). The third number (880)
merely states the end of that sync pulse. Monitors need a certain time to be
able to detect the presence of a sync pulse. Normally a minimum of around
1/2 micro-second (=25 clock pulses at 50 MHz) but that depends heavily on
the monitor. That is why there are TWO numbers for the sync. The difference
between the middle two numbers determines how long the sync pulse will be
active, so the monitor can detect it. A small summary:

   800  =  number of pixel clocks for active (=visible) part of the line.
   848  =  start of horizontal sync pulse
   880  =  end of horizontal sync pulse
   1032 =  end of entire line. This is when the NEXT line will begin.
   
At this point, we will be able to determine the horizontal frequency of the
signal going to the monitor. Since there are 50 Million clock pulses per
second, and since the entire line, including flyback, needs 1032 of those
clock pulses, there will be 50,000,000 / 1032 = 48449 lines drawn per
second. Bingo! We got the "horizontal refresh period" or the "horizontal
frequency" of the signal going to the monitor: 48.449 kHz (kilo-Hertz = 1000
Hz).

Of course, your monitor must be able to handle that. Can it sweep that beam
almost 50000 times per second from side to side and back? Some can, some
cannot. The more expensive your monitor is, the faster it will probably be
able to do that (price is not the only criterion, of course...).

It is time to dive into your monitor manual and see what it can handle. Look
up the "Technical Specifications" section, and look for something like
"scanning frequency", or "vertical range" and "horizontal range" or
whatever. Any numbers ending in "kHz" will probably relate to the horizontal
range of the monitor. All VGA monitors can handle 30 kHz and up. Where "up"
ends, depends on the monitor. Cheap SVGA monitors stop at 36 kHz, some at 39
kHz, some at 48 kHz, some at 56 kHz, and some go on to 64 kHz. REALLY
expensive things (I know at least ONE company who has them ;-) can even take
upto 128 kHz. If you're into 29 inch 128 kHz monitors, and you have some
bucks to spare, I can get you one...

If the 48 kHz is in the range of your monitor, then you'll be able to use
that. Otherwise, lower the pixel clock until you come up with something it
CAN handle.

BUT. There is also the vertical part of the story. It is almost identical to
the horizontal part, except that this time we use the result of the
horizontal calculations to determine vertical parameters. 

Since the configuration line states a total of 630 lines, including the
VERTICAL flyback and sync time, we will get a VERTICAL frequency of 48449 /
630 = 76 Hertz. The VGA card (and the monitor) will draw a new screen 76
times per second. The vertical "refresh" is 76 Hz. This is SO fast, that
normal people will NOT see any flickering at all. Save those eyes!

If your monitor couldn't handle a horizontal frequency of 48 kHz, and you
lowered the pixel clock to 40 Mhz, so it would only be 38.759 kHz, the
vertical frequency would ALSO drop, because it depends on the horizontal
one: 38759 / 630 = 61. Now we have 61 Hz instead of 76. Still acceptable to
most of us (but not as good...).


3. blanking : what's that for?

"Blanking", or the unused area of the signal sent to the monitor, is used to
allow the monitor beam to return to the left (horizontal blanking) or back
to the top (vertical blanking).

If you would attempt to lose the blanking time completely (you could...),
you would still get some sort of an image. BUT...

Any monitor NEEDS some blanking. It uses it to determine what it will show
as "black" ("black-level clamping", in the techie mumbo-jumbo). The reason
for that lies in the fact that the monitor cannot determine what voltage of
the incoming video signal is meant to mean "black". The generally agreed
remedy for this is to put some "black" data close to the sync signal, so the
monitor can sense this, and use that as a reference for the rest of the
video signal.

If you would decide to put real video in there, the monitor will say at the
end of each line: "hey, the black level I sense here has changed to
<anything that you are trying to display in that place>". And it will change
it's interpretation of "black" to that new value. Anything BELOW that level
will be made even blacker, and anything above that will be made whiter. If
the blanking area was, say 70% white instead of black (0% white), then
anything below 70% white would be shown "blacker than black", while anything
above it would be shown 70% less white than intended. So full (100%) white
would then show up as 30% white... And that's not what you intended. 

That is the reason for those black stripes on the screen (or even a
completely black screen, worst case) if you define a blanking area that is
too small.

There's still another reason for blanking. The hideous "flyback" mentionned
earlier is not instantaneous, and the transition from a nice and slow linear
move from left to right into a fast sweep back is not all that nice and
sharp. Once the sync pulse is detected at the end of the screen, the beam
starts to slow down, stops, and then moves faster and faster to the left.
Once there, it slows down, and then starts moving to the right again. And
after a certain while, it moves from left to right again in that very
stable, linear movement, so that every pixel has the same width, and every
line the same distance from the adjacent lines. The same goes for the
vertical movement of the beam.

WHERE your monitor actually samples the "black" value, depends on the brand.
All you know is that it's somewhere near the sync. 

If you define too little blanking, but still enough for that "black-level
detection" to work all right, you will actually "see" (that is: you'll see
the result of it) the beam slowing down and speeding up, because now it is
not blanked away enough. The effect on the picture on screen will be that it
is "compressed" on the edges.


4. sync: being in control

The sync pulses' first and most important use is to tell the monitor beam
when to start "flying back", be it horizontally or vertically. That should
be clear by now.

Another thing to note is that the sync "reference" is the FIRST edge of the
sync (in most cases). The second one is just there (I am repeating myself
here) to allow the monitor to "see" it. It will be the relative position of
that FIRST edge that will determine the image position, and the amount of
blanking before and after the sync. 

If the horizontal timing is defined as "800 848 880 1032", then the blank
area BEFORE the sync (= at the right edge of the screen) will be 848-800
pixels, and the blanking DURING and AFTER the flyback is 1032-848 pixels.
How much blank pixels there are on the LEFT of the screen depends on how
fast your monitor can sweep back. If your monitor would need 2 microseconds
(= 100 clock pulses at 50 MHz) for flyback, then there are 132-848-100 black
pixels on the LEFT side of the picture. The only catch is that you don't
know how much time YOUR monitor needs for flyback... So some experimentation
will be needed. 

Due to blanking, syncs have a more subtle influence on the picture. The
relative position of the sync pulse in the blanked area of both horizontal
and vertical timing parameters determines the position of the image on your
monitor.

Any monitor always restarts drawing a new line (or a new picture) at exactly
the same leftmost position. That should be independent of all other timings.
After it has detected the sync signal, it needs a certain amount of
"flyback" time, and then it starts at the same position on the left (for a
horizontal sync) or at the top (vertical sync).

If you defined much "blank" space at the END of the line (=before the sync),
and little blanking AFTER the sync, then the image will be positionned
closer to the left, because after re-starting from that fixed position on
the left, the picture data starts relatively "soon". If you leave too little
room after the sync, the beam will still be busy "flying back" when the
picture data is already restarting to show up. You'll see a "folding" effect
on the left of the screen.

An example of this would be to define the following horizontal timings:

	"800 1000 1032 1032"
	
As you can see, the LENGTH of the horizontal sync is still 32 pixels, but it
has moved to the extreme right in the timing definition. Try it out! Now
there is lots of blank space BEFORE the sync (=at the right of the screen,
before the beam is instructed to move back to the left by the "start sync"
number), and no space at all AFTER the sync. Probably not enough time for
the beam to travel back. You will wittness the famous folding effect! come
and see!

The other extreme ("800 800 832 1032") will NOT always result in the same
effect. Now you instruct the beam to start travelling back IMMEDIATELY after
it has ended showing "active" video data. There will be virtually NO blank
data at the rightmost edge of the screen, and MUCH of it at the left edge
(=after the beam travelled back).

BUT since the beam cannot possibly know it will have to travel back so soon,
until it is actually told to do so, there will be NO folding effect. It will
only start to travell back at the start of the sync, and by then the blank
area has JUST started...

Theoretically, yes. In practice, sometimes not. You might WANT to show data
on the rightmost edge of your screen, but it could very well be that your
monitor cannot reach out that far to the right. The beam might "bump into
the right edge" way before the sync comes around to tell it to go back... So
you WILL sometimes wittness something much like the folding effect, but then
due to limitations in the monitor, not due to your akward timings specs.

Again: all this also applies to VERTICAL timings. In fact, you'll see a lot
of vertical timing specs where the vertical sync comes right after the end
of the active video data.

And that's all folks...


-----------------------------------------------------------------------------

Hacking a bit yourself
----------------------

If you feel like hacking some VGA registers yourself, a small utility is
included that was used to test many VGA features. It is undocumented, and
should be considered "not suitable for normal use". It helped me test VGA
stuff without needing to recompile all the time.

It is far from complete, but usefull for THIS application. 

You can make it by typing "make hack". You'll get "setVGAreg" and
"getVGAreg" (a link to setVGAreg). Enjoy.

-----------------------------------------------------------------------------

Changing the code
-----------------

Since the author (=me) is NOT an experienced C-programmer at all, it is very
possible that the code can be optimised, enhanced, robustified, etc. in may
ways. Any usefull remarks on that will be very welcome and probably
instructive... And if the code looks like SOLDERED together rather than
PROGRAMMED, you'll know what my REAL roots are...

Adding support for other chipsets SHOULD be fairly easy. The most important
things are chipset-specific pixel-clock selection routines, and
chipset-specific register unlocking routines.

If anyone feels temped to do so, or if you don't feel tempted, but have the
piece of code at hand, or (even better) you have data sheets on that
chipset, please let me know.

If you change the code to improve the program (there is no use in changing
the code to make it WORSE, except if you work for Bill ;-), please send
patches, so I can include the changes in future versions.


Author:
-------

Koen Gadeyne (kmg@barco.be)

*******************************************************************************
* NOTE: If you use this program succesfully (or not), please let me know, and *
* state your VGA card type as well, so I can make up some list of which cards *
* SHOULD work and which ones not.                                             *
*******************************************************************************
But don't send MegaBytes of debugging data... It's a slow modem link...


Credits:
--------

The entire Linux Developers' community:
    Without them, this program would be useless, since there would be no
    Linux... 

Original idea: Wouter Gadeyne (Wouter.Gadeyne@p24.f1906.n291.z2.fidonet.org
    and gadeynew@sebb.bel.alcatel.be), who wrote the first program for the
    Cirrus Logic card, and it made me so jealous that I changed it to
    support S3 as well. He is also responsible for many tips on how to make
    the code more "C-like". And for constantly nagging about me not going to
    finish it up into something distributable. So I REALLY wanted to prove
    him wrong.

First Beta testers: (for ET4000 support and general features):
    Kris Coryn (Kris.Coryn@p13.f1906.n291.z2.fidonet.org) and Lieven
    Gesquiere (gesquiel@sebb.bel.alcatel.be). Seeing it run on my S3 made
    THEM so jealous that they wanted it for their ET4000 as well. They also
    allowed me to test it on their machines, with all the accompanying
    system shutdowns, reboots, filesystem checks, etc.).

