                                  Atari800Win
              An Atari 800/800XL/130XL/5200 emulator for Win32

      Original Atari800 code by David Firth (david@signus.demon.co.uk)
           Win32 version by Richard Lawrence (rich@kesmai.com)
                  http://www.cris.com/~Twist/atari800win/

***YOU MUST READ THIS ENTIRE DOCUMENT AND THE FAQ BEFORE MAILING ME WITH 
QUESTIONS***

DO NOT UNDER ANY CIRCUMSTANCES E-MAIL ME ASKING FOR EITHER SYSTEM ROMS OR DISK
IMAGES. I WILL IMMEDIATELY DELETE ANY SUCH E-MAIL. START FROM THE WEB PAGE ABOVE
AND YOU WILL BE ABLE TO FIND WHAT YOU NEED.

Contents:
	REQUIREMENTS
	INTRODUCTION
	GETTING STARTED
	KEYBOARD LAYOUT
	RUNNING UNDER WIN NT
	RUNNING UNDER WIN 9X
        COMPRESSED IMAGES     <---New in version 2.3
		
REQUIREMENTS: P75+, Win95 with DirectX or Win NT 4.0, 4MB RAM available, a sound
card supported by DirectSound (optional) and a joystick supported by DirectInput
(optional). PLEASE SEE THE OS-SPECIFIC SECTION OF THIS DOCUMENT FOR WIN95 OR NT
PARTICULARS. THEY ARE IMPORTANT.


INTRODUCTION: Atari800Win will allow you to emulate an Atari 8-bit computer
system on your Win32 based PC. It emulates all hardware aspects of the original
Atari 8-bit (video, audio, and I/O devices), and can be configured to behave
like of any of several Atari models (the 800, 800XL, 130XE, 320 (modified 130)
XE, or 5200 game console). It features a familiar Windows user interface for 
configurable options and takes full advantage of whatever available video/audio
hardware is on your machine. Although the code it emulates is 8-bit, everything
here is pure 32bit Windows.

The underlying emulator code was written by David Firth, who did an excellent
job, along with contributions by Ron Fries for the sound code (which is also
quite cool). The Win32 specific code is all my own, so blame me. Several 
additions have been made by other members of a loose team that is now working
to improve the emulator. The current up-to-date source and home base of the 
team is at http://cas3.zlin.vutbr.cz/~stehlik/a800.htm.

This product is free, but copyrighted (actually copylefted, in the GNU General
Public License sense). I do not want money for this emulator, I consider it 
payment enough that many, like I do, will be able to enjoy their classic 8-bit
stuff again without having to pay money for it. If you feel motivated, you can
drop me an e-mail just telling me you're getting a kick out of your 8-bit 
again. Also, I am always on the lookout for original Infocom games (as in the
boxes with the stuff in them) and would appreciate donations of those, or of
Atari 8-bit/ST software on CD-ROM.

This port is dedicated to the Nybbler Maniacs. Mike, Galen, Steve and I are all
still around and hopefully will get some use out of this. In the _old school_
tradition of hacks when just doing it for yourself was the point, here's a 
salute to them and to Glen, who hopefully hung on to some of that ultra-rare
5200 stuff that "never made it out of Atari" :-). Anybody remember BLOC and
Arcadium? Mike and Galen between them did some of the best AMS tunes made, too.

Also check out http://www.cris.com/~Twist/WinFrotz/ if you are interested in
playing the Infocom or other interactive fiction adventures on a modern Win32
interpreter.

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

GETTING STARTED: The very first thing to do is obtain a set of Atari OS ROMs and
a disk image to boot with. The ROMs are _not_ distributed with Atari800Win, and
you may _not_ put Atari800Win in an archive with them included and re-post it.
We all know the drill, right? You will find pointers on how to obtain the ROMs
on the Atari800Win home page at http://www.cris.com/~Twist/atari800win/
At a minimum you will need one machine ROM (either OS rev A, OS rev B, XL, XE,
or 5200) to boot Atari800Win. Probably you should have OS rev B (required for
most picky games), XE (the later generation machine with more memory), and 5200.

You will also need a disk image, as mentioned previously. The most prevalent 
Atari DOS versions are 2.0S, and 2.5. There are plenty of later versions from
Atari, and also several versions from other manufacturers. Take your pick, but
keep in mind maximum compatibility is an Atari 800 OS rev B running 2.0S DOS for
most games and the like.

After you have your OS and a disk image, you can start up Atari800Win. The
default configuration will look for an Atari XL OS named atarixl.rom in the
same directory as Atari800Win itself. If you boot without this image present
a dialog box will appear telling you it couldn't be loaded, then the emulator
itself will appear. You can change the OS selection/name using the menu "Atari"
and submenu "Hardware".

When you correctly configure the OS settings, if you have changed nothing else,
when you "OK" that dialog Atari800Win will switch into a full-screen 800x600
256 color DirectDraw display. This mode is ideal because it displays the full
area of the Atari screen, including overscan. You may however select a different
mode at lower resolution if you are willing to sacrifice some of the overscan
area. The actual display resolution of the Atari is 384x240, and for most PC
resolutions this is doubled to 768x480. You can also select to run Atari800Win
in a window, which works fine if a little slow. I do not recommend 768x480 in
a window. It will be very slow no matter how fast your machine is. Talk to Bill
Gates about it. SOME DirectX machines may handle it. SOME AGP cards will do it
with no problems (do not assume AGP=performance, it is not so).

From here you can configure your disk drives using the "Atari/Disk Drives" menu,
change cartridges via the Atari/Cartridges menu, and select directories on your
PC hard disk to act as Atari virtual "Hard Disks", accessed via the H1:, H2:,
etc device names. The regular PC keys should act like their Atari equivalents
(i.e. break is break, escape is escape, letters/numbers are the same, etc). See
the section KEYBOARD LAYOUT for specifics. One important key is the F5 key - it
will either warmstart the Atari, or with Shift-F5 will "Cold"start it.

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

KEYBOARD LAYOUT: The general philosophy in keyboard layout is to assign the 
functionality of the original Atari key to the equivalent PC keyboard key. This
differs from some other emulators - I am not aiming for the original key in the
_same location_ as on the Atari keyboard, just trying to match the same
functionality. Some keys that exist on the PC have no equivalence on the Atari
and will do nothing, such as { and }.

Atari Key	Windows Key
---------------	---------------
A-Z		A-Z
a-z		a-z
0-9		0-9 also 0-9 for 5200
Esc		Esc
Break		Break
Atari key	Delete key (sorry, couldn't find a better one)
Help key	`
Select		F2
Option		F3
Start		F4 
Restart		F5 (shift-F5 is a Coldstart, same as turning on/off Atari)
                This is also Reset/Coldstart for the 5200.
--		F8 Run Atari as fast as possible (toggle)
--		F9 (pauses the Atari emulation code, F9 restarts)
Ctrl-a to z	Ctrl-a to z (yes, no windows accelerator keys)
", *, -, etc	Equivalent Windows keys

Special 5200 notes: the * key functions as the 5200 * key (either keypad
or regular keyboard position), the - key functions as the 5200 # key (either
keypad or regular keyboard).

Up, Down,	Same as Atari up, down, right left arrow keys. 
Right, Left	

(When emulating the joystick, the keypad keys will act as if they are 
continously pressed after pressed the first time, until another key is pressed.
So pressing "4" once will pull the joystick left continually until you press
"5" to cancel it. Turn numlock OFF to use the keypad as a joystick. To override
the held-down behavoir turn on the checkbox in the Atari/Joystick menu to
release automatically)

Keypad 0	Joystick trigger (if numlock off and no joystick selected)
Keypad 8	Joystick Up      (same as above)
Keypad 4	Joystick Left    (same, etc.)
Keypad 6	Joystick Right
Keypad 2	Joystick Down
Keypad 7	Joystick Up/Left (note: _NOT_ Keypad8 + Keypad4! )
Keypad 9	Joystick Up/Right
Keypad 1	Joystick Down/Left
Keypad 3	Joystick Down/Right
Keypad 5	Joystick centered

(none)		Ctrl-F1		Insert disk in drive 1
(none)		Ctrl-F2		Insert disk in drive 2
(none)		Ctrl-F3		Insert disk in drive 3
(none)		Ctrl-F4		Insert disk in drive 4
(none)		Ctrl-F5		Insert disk in drive 5
(none)		Ctrl-F6		Insert disk in drive 6
(none)		Ctrl-F7		Insert disk in drive 7
(none)		Ctrl-F8		Insert disk in drive 8

(none)		F8		Toggle between full/standard speed
(none)		F9		Toggle between running/stopped
(none)		F11		Toggle SIO (fast disk) patch
(none)		Ctrl-Space	Activate built-in Atari800 user interface
				Atari800 interface not available in all versions
--------------------------------------------------------------------------------

RUNNING UNDER WIN 9X: First, get DirectX 5.0. It is available for free from 
www.microsoft.com. It has considerably better performance in many cases, many
bug fixes, and DirectInput actually works under it. I say again, get DirectX
5.0. After you have done that come back and continue reading.

Ok, now that you have 5.0 installed (I mentioned you should get 5.0, right?)
you're basically In Like Flint. On slow machines you might want to try the 
low res (320xXXX) drivers for speed improvements. Even on a P100 I was able 
to run full speed with 44Khz sound at 320x240. I'm not supporting ModeX modes
anymore, just linear low-res modes. Not all cards will have these. If you're 
not sure about your performance use the Info/Graphics test and Info/Sound 
tests. You should be getting <10ms for graphics and <2ms for sound. 

For this release all sound is implemented using the standard WaveOut functions.
Not only are these more compatible with a wide range of hardware than Dsound,
they work under NT and show no significant performance difference (and just
plain sound better on many machines). Sound frequencies are supported up to 
48Khz. There are MANY sound cards that will not work at 48Khz, so you should
select 44.1Khz for those.

PLEASE KEEP IN MIND I AM NOT RESPONSIBLE FOR THE DISFUNCTIONAL DIRECTX DRIVERS
THAT SOME MANUFACTURERS DISTRIBUTE. If anybody believes DirectX means universal
compatibility they are sadly mistaken. Emulating another computer in real time
is a VERY demanding task and Atari800Win tries to take advantage of several key
DirectX features because of this. Some drivers (both video and sound) don't
support these - that's why there are so many options available, so you can
always get it to work.

And as a final note on this issue: there is _no such thing_ as a "100% Sound 
Blaster Compatible" card, other than a SoundBlaster. And even some of those 
are pretty questionable.
--------------------------------------------------------------------------------

RUNNING UNDER WIN NT: To even think about doing this, you have to have NT 4.0
and have patched it to Service Pack 3 (besides a humongous list of bug fixes, 
service pack 3 has DirectX 3.0 in it). Go to www.microsoft.com for the service
pack. You really want it, trust me.

Now, if you have that, there is good news and there is bad news. The good news
is that Atari800Win was developed under NT and therefore of course works under
it. The bad news is Win NT really sucks for playing games or running emulators.

Let me explain before anybody gets religious on me. Under NT, DirectX might as
well be called "inDirectX", for completely valid system integrity and security
reasons. You wouldn't want someone to crash a corporate web server because they
happened to be playing Rally Speedway in Atari800Win on it. This means DirectX
performance under NT, generally, is really bad. There are also some things
missing from 95 DirectX, most notably having even the concept of a joystick.
Until NT 5.0 is out (and stable) with DirectX 6, things look pretty bleak.

In my tests during development I found NT to be incredibly slow in DirectDraw
blits. This is not a mistake in Atari800Win, the Microsoft DirectX sample code
does the same thing. As an example, on a P100 test machine running 95 I could
blit an 800x600 area from the Atari source surface in about 6-7ms on average,
using a shoddy Diamond DRAM 2000. Doing the same test on a P200 machine with
a Millenium card resulting in blits that took almost 40ms, over 5 times slower
than the P100! This is actually too slow to correctly emulate an Atari, as the
emulator needs to be able to complete an update cycle to the point of a screen
blit in under 20ms. You can start to see the problem. Not all modes are like
this - they vary considerably by card, driver, and machine. So I put a test 
in Atari800Win for you, which can be accessed via the Info/Graphics Speed menu.
I suggest trying low res modes if they are available (320x200 or 320x240). On 
the same machine above a ModeX 320x200 display took on average less than a
millisecond to draw. Of course, not all cards support low res. If you can't
find a mode try running in a 384x240 window not even using DirectDraw. On a
decent machine this will actually be reasonably fast, about 6ms for a P166,
which is plenty fast enough. And of course it's as compatible as possible that
way.

The news is also mixed on the sound front. The original Atari hardware had what
amounted to a tone generator for sound. It was very advanced for the time and 
allowed for a complex range of effects. Since you don't have this type of
hardware in a PC, Ron Fries wrote an excellent set of routines that imitate the
behavoir of this chip in software. But to work correctly it requires a high 
mix rate - in fact, the sound buffers have to be regenerated every 20ms (there's
that number again) to keep pace with the Atari. Even with typical double-buffer
mixing, NT falls apart completely on this. So, I added a period of latency to 
sound generation - several frames are combined together in one burst - and I 
started using LOTS of sound buffers (8), the combination of which ALMOST allows
for really good sound under NT using the standard WaveOut functions. I say
almost, because there is just no such thing as real-time servicing in NT. I
don't have interrupts like the DOS guys. So, it is quite possible, even on a 
whiz-bang machine, that your computer will be busy when the magic update point
rolls by for a sound refresh. If this happens, your sound will "pop". I spent
a very very long time experimenting with what I feel is the most stable and
reasonably high performance solution to this problem, so right now we're about
as far as we're going to go with NT sound. It sounds REALLY good compared to
early versions, which is the good news. It can still pop at times, which is 
the bad news.

As for DirectInput, well, there is no joystick device. 'Nuff said. In short it
pretty much rots running Atari800Win under NT. The best mode is often windowed,
sound can be a problem, and you have no joystick (you can use the keypad as a
joystick though). Much as I hate to say it I have to recommend Win9X for running
this emulator. I develop with NT and use it day in and out as my OS of choice,
but it clearly is not yet real-time enough to allow this type of code to run
effectively.

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

COMPRESSED IMAGES. There are three types of compressed images that Atari800Win
can read - DCM files, and gzip compressed ATR or XFD files. All of these formats
are handled in the same way: the original file is opened in read-only format,
and a temporary file is created that has its decompressed contents, which is
then opened in place of the original file. Note that this means what where ever
your TMP directory in Windows points, there will be a file the size of the
original disk image in it (which will be deleted as the disk is unmounted, or 
Atari800Win is closed). This is significant if you are reading in very large
"mega-disk" ATR images, which can sometimes be 1MB+ in size. These images can
take several seconds to decompress, and keep in mind they will end up chewing
up that much drive space on your disk, albeit temporarily.

DCM is a fairly primitive compression format that originated on the Atari 
itself and will reduce entire disks to various degrees. It is recommended you
convert any DCM files you have to ATR (Atari800Win can do this for you, using
the File/DCM->ATR command), and if you want to keep them compressed, use gzip
on the resulting ATR file, which will be much more efficient.

XFD is disk image as used originally by XFormer (another 8-bit emulator). It
contains an entire disk, but is missing a header that ATR uses to avoid some
potential read confusion. ATR is the more recent format and is generally used
nowadays. Either XFD or ATR disks can be compressed with gzip and then read in
to Atar800Win in the their compressed forms. The only easy way Atari800Win has
to differentiate the various formats is file extensions, and it is therefore a
strict rule that gzip compressed images MUST be named .atr.gz or .xfd.gz, or 
alternately .ATZ or .XFZ. For instance "mule.atr.gz" without the quotes would
be right (Windows has no problem with a file that has 'two extensions' as it
appears here). The ATZ and XFZ extensions are mainly in case the DOS versions
of Atari800 start supporting compression - it is NOT recommended you use them,
but the more descriptive .atr.gz instead.

You can get the current version of GZIP built specifically for Win32 at
http://www.winimage.com/zLibDll/gzip124xN.zip as of this writing. It is also
available a variety of other places; try www.winfiles.com or just search for 
"gzip" and "Windows". To compress a file with gzip you just type "gzip foo.atr"
from the command prompt and "foo.atr" will be replaced with "foo.atr.gz"

Note that DCM files cannot ALSO be compressed with gzip; there is not support for
".dcm.gz" files. If you want to do this, convert the DCM to ATR with Atari800Win
and then compress the resulting ATR with gzip.