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