PC World 1999 June/PCWorld_1999-06_cd.bin/software/temacd/atari800/ReadMe.txt

Text File | 1998-12-17 | 27KB | 483 lines

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

      Original Atari800 code by David Firth ([e-mail])
           Win32 version by Richard Lawrence ([e-mail])
                  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.

Files shipped with Atari800Win:

Atari800Win.exe        The windows executable (Win 9X/Win NT)
ZLIB.DLL        Compression DLL (put in same location as Atari800Win)
FAQ.TXT            Frequently Asked Questions
README.TXT        This document
WHATSNEW.TXT        What's new this version, some version history
TODO.TXT        (Sometimes not included). Ruminations on future features.

Contents of this README:
    REQUIREMENTS
    INTRODUCTION
    GETTING STARTED
    KEYBOARD LAYOUT
        KEYBOARD TEMPLATES
    RUNNING UNDER WIN NT
    RUNNING UNDER WIN 9X
        COMPRESSED IMAGES
    LOADING ATARI EXECUTABLES
    SCANLINE MODE

REQUIREMENTS: P75+, Win95 with DirectX or Win NT 4.0, 4MB RAM available, a sound
card supported by Windows (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 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 your hardware through
DirectX. Although the code it emulates is 8-bit, everything here is pure 32bit
Windows (Atari800Win contains C++, C and asm code).

The original emulator code was written by David Firth, along with contributions
by Ron Fries for the sound code. The Win32 specific code and some extensions
are my own. 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, when hacking was just for the
hell of it. 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. A sensible one to
start with is Atari DOS. 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 obtaining these, you can start. 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 screen will appear. You can change the OS
selection/name using the menu "Atari" and submenu "Hardware".

When you configure the OS settings to point to your files, and "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. But you'll probably want to type, so read below.
--------------------------------------------------------------------------------

KEYBOARD LAYOUT: The general philosophy in keyboard layout is to assign the
functionality of the 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.
The reason for this is it can be very confusing to have to hit "Shift-2" to get
a doublequote character when there is sits staring at you from a key on the PC
keyboard. So in general, look for it where it is on the PC keyboard, type that,
and it will appear. However some keys that exist on the PC have no equivalence
on the Atari and will do nothing, such as { and }.

There are some non-obvious key combinations, so read through the list below.

Atari Key    Windows Key
---------------    ---------------
0-9        0-9, keypad 0-9 with numlock (when keyboard joystick not on)
Esc        Esc
Break        Break
Insert        Insert (normal = char, Shift + Insert = line)
Delete        Delete (normal = char, Shift + Delete = line)
Clear key    Home key
Atari key    End key (or the Windows key :) )
Caps Toggle    PageUp key
Help key     PageDown key (works only when Atari is an XL/XE model)
Caps Lock    Caps Lock
Tab        Tab
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.
F1-F4        Shift+F1-F4 (works only when Atari is an XL model)
Up, Down,    Same as Atari up, down, right left arrow keys.
Right, Left

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).

The keypad can do several things: with numlock on it is the 0-9 keys, unless
you can configure it as a keyboard joystick, in which case it's a joystick.
With numlock off it types the equivalent non-numeric key (4 is left, etc).

Keypad as a joystick:
Keypad 0    Joystick trigger (if numlock off and keyboard joystick)
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: Keypad8 + Keypad4 will also work)
Keypad 9    Joystick Up/Right    (or Keypad8 + Keypad6)
Keypad 1    Joystick Down/Left    (or Keypad2 + Keypad4)
Keypad 3    Joystick Down/Right    (or Keypad2 + Keypad6)
Keypad 5    Joystick centered (if auto-centering is off in joystick menu)

Note: The keypad, when working as a keypad, will ignore the status of shift,
ctrl etc. In other words it will always type the atari 0-9 keys and /*-+.
Since no keypad existed on the Atari, this seems fine - to get the effect
of Shift-1, use shift-1 on the keyboard, as you would on an Atari).

Ctrl+F1-F8    Insert disk in drive 1-8 depending on F key

Alt-C           Cartridge dialog
Alt-D           Disk dialog (floppies)
Alt-G           Graphics dialog (screen modes)
Alt-H           Hardware dialog
Alt-J           Joystick dialog
Alt-K           Keyboard dialog
Alt-L           Load Atari executable
Alt-S           Sound dialog
Alt-R           Rotate throw artifacting modes (including off)

F8        Toggle between full/standard speed
F9        Toggle between running/paused
F11        Toggle SIO (fast disk) patch
Ctrl-Space    Activate built-in Atari800 user interface if available


The following keyboard behavior may seem odd, but it is all entirely accurate
to how a real Atari works and was purposefully coded that way:
* If you try strange combinations, like ctrl+shift+a, in many situations (such as
  the BASIC screen) the key will click but nothing will happen.
* With control and shift both held down you cannot type the following
  characters: J K L ; + * Z X C V B F1 F2 F3 F4 and HELP.
* Break will not show up as pressed on keyboard diagnostics, nor will Ctrl+Shift
  plus another key. They are being set internally but the diag program doesn't
  parse them.
* Atari function keys are not available except on XL models.
* When you are holding down a regular key, such as "1", and then press another
  regular key, such as "2", then the second key will not register unless you
  release the first.
* Some exceptions to the above: the console keys such as OPTION and SELECT
  (because they are not really "keys") will always work. Break will not register
  as a keystroke and therefore a break will execute, but the original held-down
  key will continue to repeat.

Your Windows keyboard settings such as repeat and delay make no difference to
the emulated Atari. All that matters is the key going down, then coming up.

When you task-switch away and return to the Atari, all keys will be cleared.
This is so the Atari won't miss a key up message by accident while you are in
another app (which would make the key stuck down in the Atari).
--------------------------------------------------------------------------------

KEYBOARD TEMPLATES: Another way to use the keyboard in Atari800Win is to create
a keyboard template. A keyboard template allows you to pick almost any PC key
(everything except the F1-F12 keys, and Insert/Delete/Home/End/PgUp/PgDwn) and
define it to be an arbitrary Atari key, optional with certain modifiers.

There is a subtle difference between how the regular Atari800Win keyboard works
and how keyboard templates work. The regular keyboard concept is try to match
the FUNCTIONALITY of keys. This was done to avoid confusion from users who are
much more familiar with their windows keyboard than an Atari one, so that the
key they saw hit was the key that got typed. When using a keyboard template, the
behavior is to match PHYSICAL KEYS. Where this comes into play is when using
modifiers like control or shift. The regular method allows for different
keyboard functionality for each modifier key that is held down. With keyboard
templates, the key defined will simply be sent to the Atari along with the fact
that control or shift (or both) were held down as well.

For example, take the 2 key. In regular Atari800Win keyboard behavior, when you
hit 2, you get the Atari 2. When you hit shift + 2, you get the (@) sign,
because that's what you see on your windows keyboard. But on a regular Atari
keyboard, shift + 2 was actually double quote ("). When you hit shift + ' on
your windows keyboard to get ", Atari800Win is actually sending the Atari key
shift + 2! In other words, internally Atari800Win has a different functionality
map for each combination of control, shift, and a key.

Now, with keyboard templates you can only define a physical key to associate
with a windows key, not its functionality. Thus with a keyboard template you
would probably define the windows 2 key as the Atari 2 key, and when you hit
shift + 2 you would actually get ", the result of hitting shift + the Atari 2
key. You need to have a familiarity with the Atari keyboard to know what to
type. Atari keyboard differences from normal PC keyboards are as follows:

Following key positions (using their lowercase forms) do not exist on Atari:
[ ] \ '

Following key positions exist only on the Atari:
+ (shifted is \, control is left arrow)
* (shifted is ^, control is right arrow)
< (control / shifted is Clear)
> (control / shifted is Insert)
Atari key
Help key
Caps toggle (which isn't really the same thing as caps lock)

PC Keyboard positions that differ:
Shift-2 is ", not @
Shift-6 is &, not ^
Shift-8 is @, not *
Shift-7 is ', not &
Shift-= is | (vertical bar), not +
Shift-, is [, not <
Shift-. is ], not >

Control-= is down arrow
Control-- is up arrow

Well, with all that background, and given that they can be confusing, what good
are keyboard templates? Well, they serve two useful purposes: if you are very
familiar with the Atari layout and prefer using that, you can do so easily (the
default keyboard template initially selected is basically the Atari layout).
Templates also allow you to remap keys to completely different locations for
ease of use. Say a game was using the a,s,d, and z keys for movement or some
equally strange combination. You could remap the windows arrow keys to type the
Atari a,s,d and z keys and then movement would make some sense.

Creating a keyboard template is simple. You open up the Options/Keyboard dialog,
and will be presented with two drop down boxes. On the left hand side are PC key
locations. On the right hand side is a box showing what Atari key is typed when
you press that PC key. You can change them around pretty much any way you want.
You can cause a regular PC key to type an Atari key that is already shifted, or
using control, or both with the checkboxes on the Atari side (useful for arrow
keys for instance, assign the atari keys control and - to the PC up arrow key,
and you don't have to type control to get a directional key).

Keep in mind that no matter how you define a particular key with control and
shift, when you hit the key in Atari800win it is sent to the Atari as keycode +
shift state + control state. Put differently, the control and shift modifiers
are ALWAYS sent in keyboard templates, unlike regular mode!

It is ENTIRELY possible to dig yourself deep holes with bad keyboard templates.
You could define every Windows keystroke to type the Atari "A" key. You could
leave Atari keys out. Probably something else I'm not thinking of. There is no
attempt to check the template, because there are too many custom permutations
that a person might find useful but look wrong to a computer (multiple defined
keys to the same Atari value, for instance).

Because of this, DO NOT USE KEYBOARD TEMPLATES UNLESS YOU A) Know the Atari key
layout pretty well and B) have a specific purpose or goal that you understand.
DO NOT SEND ME BUG EMAIL RELATED TO THE KEYBOARD UNTIL YOU HAVE TURNED TEMPLATES
*OFF*!

As an example of what keyboard templates can be used for, I am distributing a
template that is useful for the always troublesome Ultima 3, which uses really
weird movement keys. Use the PC arrow keys with Ultima 3 loaded in the Atari,
and voila, you are moving normally.
--------------------------------------------------------------------------------

RUNNING UNDER WIN 9X: First, get DirectX 6.0 or higher. It is available for
free from www.microsoft.com/directx. I say again, get the latest version of
DirectX. After you have done that come back and continue reading.

Ok, now that you have 6.0 installed (I mentioned you should get 6.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. If you don't have the 320
modes available (they are greyed out) you can use 512x384. 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. AGP will
make a huge difference in your ability to run in 1024x768 mode or in double
size windowed modes.

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. Sound from a
normal Atari is always mono. You can save the sound output to a wave file
from the Options menu.

PLEASE KEEP IN MIND I AM NOT RESPONSIBLE FOR THE BROKEN DIRECTX DRIVERS
THAT MANY MANUFACTURERS DISTRIBUTE. Many many times I am mailed with bug
reports that are due to a) not having DirectX installed correctly or b)
using the latest beta Fraginator 3000 drivers which aren't quite up to snuff.

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 do this, you have to have NT 4.0 and have patched it
to Service Pack 3  or 4 (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, you can run with some catches. The catches are, briefly:
a) no joystick support, b) most often really poor video performance in full
screen modes.

Let me explain before anybody gets religious on me. The NT implementation of
DirectX (with NT 4.0) is *not* designed for performance. Further, most card
manufacturers spend their time creating performance drivers for Win9X, not NT.
It varies a lot by card and manufacturer. One might release very fast drivers,
the other might be slow as a turtle compared to their Win9X performance.

And when I say slow, I mean reeeeeally slow. I've seen identical cards take
5-7 times longer to complete the exact same graphics operation under NT than
the very same card under Win9X. *Many* manufacturers make NT drivers that can
go fullscreen but take absolutely NO advantage of hardware blits. Sad but true.

To correctly emulate an Atari, I need to be able to complete a screen refresh
and make it through all the emulation logic every 17ms to 20ms. Some cards
under NT just can't keep up, but almost all can in windowed non-stretched
mode. Try that first, if it is fast and full screen is not, it's your driver.

There is a test to help you determine your graphics performance - simply
select the graphics mode you want to test, and use the Info/Graphics speed
option. You should be getting values less than 10ms.

The sound system is also stressed by Atari800Win because of the very high mix
rate required for real-time reproduction of the Atari polynomial sound chip
(without interrupts, mind you!). Some drivers have no problem, some can't
keep up regardless of hardware. Again this various widely by card.

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

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.

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

LOADING ATARI EXECUTABLES. If you have files that are individual Atari programs
(often ending in "EXE" or "COM" but not always - there was no enforced naming
convention with Ataris), there is an option in Atari800Win to try to load them
directly. Simply use the Atari/Load EXE menu option. A Windows file selector
will pop up allowing you to locate the file - double click it or click ok to
continue attempting to load it.

What happens next is actually quite a complicated process, but it all happens
behind your back and usually is of no concern at all. Atari800win creates a
temporary disk image on the fly that is specially designed to load the file you
just specified. It copies this into your Windows TEMP directory, inserts it
automatically as the boot disk in your system, and reboots the Atari. You will
see a blue screen as the Atari boots with a little "k" in the upper left hand
corner (part of Ken Siders loader program, which he gave permission to be used
in Atari800Win).

Usually the next thing you will see is the game itself. However, some games
can't be loaded in this manner. They may have seperate data files they need to
read, or they may use a custom loading process that doesn't work like regular
Atari programs. If you run into one of these, you will simply have to create an
Atari DOS disk and copy everything over to that.

It's also possible that Atari800Win will refuse to try to create a boot disk as
described above if it thinks it isn't an Atari executable. There are a few
reasons it might do this: the file is too large to be an Atari executable, the
file does not start with the Atari executable header signature (FF FF), or the
load address is nonsense (00 00).

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

SCANLINE MODE (and why I think it's silly): There is an option in the graphics
dialog of Atari800Win listed as "show scanlines". This will cause the display
to be interlaced with half-bright lines, approximating (poorly) the behavior of
some TV sets. It only works in display resolutions that are at least 2 times
the vertical height of an actual Atari display (for the obvious reason that
there needs to be a place to draw the darker lines).

Now, this is an oft-request feature that I declined to include until quite
late in the development of Atari800Win. There are several reasons I dislike
it: 1) It incurs a substantial overhead to display. It's not worth going into
here, but due to the nature of Windows/DirectX I have to do considerably
*more* work to display this mode. 2) The methods of creating it do not
accurately portray the real world effect. Digital monitors are quite precise
in general and will show an exactly identical aspect half-bright line after a
full color one on the display. The vast majority of TVs, due to the blooming
of a displayed scanline, will actually show something along the lines of a
2:1 aspect. The half-bright approach attempts to correct for this but it will
never be really representative. 3) It is not part of the NTSC system or
inherent in a rasterized display. I've had people tell me this is the "right"
way to show an Atari because "that's the way it was". No. An Atari does not
store the graphics information with black lines interlaced. Nor is it required
in the display of an Atari signal from a real live Atari machine to see
scanlines (anybody with a digital TV can tell you that). This is as opposed to
an effect such as artifacting, which is a real interaction of the Atari with
low resolution composite system (and not on a monitor or separated chroma/lumen
system).

Anyway, enough ranting. There is no sanctity to this mode. Use it if you want,
but I think it's crazy to throw away CPU time to induce error on a digital
display. If you MUST use it, use 1024 mode, which shows 2 doubled original
lines with 1 half-bright line in a triple, and looks more like the actual
aspect most displays would show with a real Atari.