Handy V0.40 - Atari Lynx Emulator for Windows 95/NT --------------------------------------------------- Author: Keith Wilkins (kwilkins@nectech.co.uk) <-------------------HANDY HOMEPAGE--------------------> http://www.geocities.com/SiliconValley/Heights/1148 <-----------------------------------------------------> ********************************************************************* DO NOT ASK ME FOR LYNX CARTRIDGE IMAGES. (I WILL NOT REPLY TO ANY EMAIL ON THIS SUBJECT) ********************************************************************* V0.40 Highlights ---------------- * Sound support (Needs P133 or higher) * Screen snapshots in BMP & RAW formats * Handy now remembers last screen mode, position etc. * LNX cart format now supports auto screen rotation detect * ROTATE.EXE file patcher for adding rotate flag to existing files ********************************************************************* Handy is Copyright(c) 1996, 1997 by Keith Wilkins This licence grants you the following: Permission to use, copy, and distribute Handy in its entirety, for non-commercial purposes, is hereby granted without fee, provided that this license information and copyright notice appear in all copies. If you redistribute Handy, the entire contents of this distribution must be distributed. The software may be modified for your own purposes, but modified versions may NOT be distributed without prior consent from Keith Wilkins. This software is provided 'as-is', without any expressed or implied warranty. In no event will the author be held liable for any damages arising from the use of this software. If you would like to do something with Handy that this copyright prohibits (such as distributing it with a commercial product, using portions of the source in some other program, etc.), please contact the author. The author can be contacted via email at: kwilkins@nectech.co.uk ********************************************************************* Index ----- 1.0 Installation 1.1 Game Images 1.2 System Requirements 2.0 Using Handy 3.0 Emulator Development status 4.0 Converting cartridges to LNX format with MAKE_LNX.EXE 5.0 Patching files with ROTATE.EXE 6.0 With thanks to 7.0 Revision history 1.0 Installation ---------------- Unpack all of the files into the directory of your choice. md c:\emu\handy cd c:\emu\handy pkunzip handyXXX.zip del handyXXX.zip This release is only for Pentium machines and will run at about 60%-100% of the speed of the original Lynx on a P133. To those out there complaining that Handy is too slow. Considering the Lynx CPU runs at 16MHz and there is a lot of hardware acceleration I don't think Handy is too bad for a C++ implementation, no assembler here (yet!). You may disagree, if so dont bother emailing me with your opinion, I dont wish to know it. If you still think Handy is too slow you have three choices: a) Buy a faster machine (>P133) b) Dont use Handy (Its not as if you paid for it) c) Write your own lynx emulator in assembler (Hi Ben!) 1.1 Game images --------------- DO NOT ASK ME FOR LYNX CARTRIDGE IMAGES, I WILL NOT REPLY TO ANY EMAIL ON THIS SUBJECT. NOTE: Handy will NOT run .LYX images, you need to convert to .LNX format using the supplied 'make_lnx' utility, see section 4.0. You will need a proper lynxboot.img to play carts, this has to be extracted from the lynx itself to run cartridges, Handy will warn you if you do not have a correct boot image. I'm sure some unscrupulous person will publish it somewhere along with game images, just don't ask me for them. The one included in this release is a fake and is non functional. There are a numer of "homebrew" images floating around in homebrew.zip these are all copyright Bastian Schick and are from his homepage. He deserves some real high praise for the work he has done. <--------------------------------------------------> http://www.gp.fht-esslingen.de/students/mt/elw5basc/ <--------------------------------------------------> 1.2 System Requirements ----------------------- * PC running WindowsNT or Windows95. * 16MB or more system memory. * Pentium class processor or better (Recommended P133 or higher). * Minimum 1MB Hard Disk space + whatever images you require/own. I would not recommend enabling sound if you have anything less than a P133 as its only just acceptable on that class of machine. Seeing as my own machine is a P133 it might spur me on to do some further optimisations for 0.5. This program performs best under 65536(16bit) colour mode, but also works in 256 colour mode. It will NOT work in 16 colour mode or less. 2.0 Using Handy --------------- Just click on the Handy icon and away you go. Select your file from the browser. The keys are mapped to: Option 1 : 1 Option 2 : 2 Pause : Q Inside Fire : Z Outside Fire : X Joypad : Arrow keys Reset Lynx : F3 Run/Pause : F5 Sound on/off : Ctrl-S Load cart : Ctrl-0 BMP Snapshot : Ctrl-Alt-B RAW Snapshot : Ctrl-Alt-R Exit : Alt-F4 Joysticks are supported under W95 by selecting the Joystick label under the options menu. I've only checked with a gravis gamepad but it works OK for me: Pad - Direction Keys Button 1 - Lynx Button B (Gravis Gamepad - Red Button) Button 2 - Lynx Button A (Gravis Gamepad - Blue Button) Button 3 - Lynx Option 1 (Gravis Gamepad - Yellow Button) Button 4 - Lynx Option 2 (Gravis Gamepad - Green Button) Note: Enabling the joystick will slow the emulator slightly, hence the joystick defaults to off. 3.0 Status ---------- Handy is writtin using MSVC 5.0 in C++ using MFC in the windows areas. The underlying lynx emulation is written entirely in C++ and should be reasonably easy to port to any other architecture. Please do not ask for source code at the moment. I will not consider releasing Handy code until I reach V1.0. The documents are not the most fun things to work with, the abiguities within them mean that often my interpretation of them is incorrect and hence the large amount of bug fixing to be done, especially in Suzy's sprite engine as the sprite docs are vague in the extreme in places. Below are the list of know problems: General Problems (affecting some carts) ---------------- . Flickering sprites . Flickering backgrounds/colour changes (e.g Shadow of the Beast, Awseome Golf) this relates to IRQ timing which is unstable due to some of my optimisations. Specific Cartridges ------------------- SlimeWorld - Missing sprites i.e the Player ?? Tetris - Cart calls power down. BattleZone - Missing ships, maybe a math related problem. Warbirds - Dodgy horizon, maybe a math related problem. Blue Lightning - Corruption of lanscape when flying at low level. EuroSoccer - Illegal Opcode error, on starting game. Dirty Larry - Hangs program after game start I have tried over 79 cartridges and the only problems I've found are listed above. If you have a cartridge image that hangs at the blank screen (colour is random) what you'll find is that you have a corrupted cartridge image. I know for a fact that there are a whole batch of corrupted images floating around on the net. Todo list --------- . Implement everon register bit . Improve integral debugger features . Improve sound synchronisation. . Mod c6502 so that +100 is included in SP usage. . Proper fix for the +1,+1 sprite problem. . Further optimisation targetting 100% on all games with sound on a P133. 4.0 Converting cartridges to LNX format with MAKE_LNX.EXE --------------------------------------------------------- Handy only reads .LNX formats files, any will not read raw (.LYX) cartridge images. To convert from raw (.LYX/.040) to LNX format use the make_lnx utility included in with the release. make_lnx [options] Optional arguments ------------------ -o Output filename (Default=.lnx) -m Manufacturer (Default=Atari) -g Game name (Default=.lnx) -r Left/Right (Default=no screen image rotation) -b0 Bank0 size (Default=Automatic, options 0K,64K,128K,256K,512K) -b1 Bank1 size (Default=0K, options 0K,64K,128K,256K,512K) The default action (no optional params) is to convert the input filename from raw format to LNX format with the default options given above. Options can be mixed and placed in any order on the command line. Example: make_lnx cgames.lyx (Converts cgames.lyx to cgames.lnx) make_lnx cgames.lyx -o calgames.lnx (Converts cgames.lyx to calgames.lnx) Part of the LNX header contains game and manufacturer information that may be used in later versions of Handy, you can add this into the header using the -g and -m options. Example: make_lnx cgames.lyx -g "California Games" -m Atari (Converts cgames.lyx to cgames.lnx and sets the internal game/manufacturer fields within the LNX header. The quotes are important only if your game name has spaces within it.) 5.0 Patching files with ROTATE.EXE ---------------------------------- Handy now supports automatic rotation of images on startup via a flag in the LNX header of the cartridge. This new addition is completely compatible with any existing files. One of the spare bytes in the header is now used to indicate whether which way the screen image should be rotated. A utility has been provided (ROTATE.EXE) to allow you to patch any existing files you may have. This facility has also bee added to the MAKE_LNX.EXE utility. Example: ROTATE LEFT GAUNTLET.LNX This will cause the gaunlet cart header to be modified so that it will be displayed correctly when starting handy. You can undo the change with ROTATE DEFAULT GAUNTLET.LNX Gauntlet will then revert back to the landscape style display. 6.0 With Thanks --------------- Lee Witek - All round mate and windows guru. Bastian Schick - Your HTML lynx docs make my paper copy redundant, thanks. Also a big thanks for all of your lynx development work. Harry Dodgson - Insights into timer related pernicousness... Help with test code for sprite engine bugs. RTOONist - Beta testing & suggestions. Riddler - Beta testing. Thanks to all those who've emailed their support. 7.0 Revision History -------------------- V0.40 20th July 1997 * Implemented sound code * Implemented support for .com files * Implemented hidden mikie register $FD97 returns 0x42 (life'n all that) * Implemented snapshots for BMP & RAW format * Implemented registry support for persistant parameters. * Fixed a bug in the sprite engine on literal sprites with 3 bits/pixel * Bug fix for multi-quadrant sprite offset error (+1,+1 problem). (I'm a little unhappy with this fix, its a bodge and has caused) (streaking of sprites in some games (California Games, Raiden...)) * 2 Bug fixes for absolute literal sprites. * Implemented cartridge detail boxes into the about box * Added dialog box whilst Handy object constructor is running as this is a little slower than 0.31 due to the sound initialisation. * Speeded up cartridge reloading. * Implemented screen rotation via LNX cart header * Wrote ROTATE.EXE and added to the distribution notes & readme * Fixed the sound problems on the early Atari/Epyx games. * Fixed the 0x80000000 rollback bug causing sound output to stop. * Commented out code for +1,+1 multiquadrant sprite fix. V0.31 21st June 1997 * Fixed error with cycle counting & emulation speed calculations * Fixed throttling code and improved accuracy * Implemented spin control for setting emulation max % * Fixed bug with CPU Stack pointer initialising to wrong value. V0.30 17th June 1997 * Reworked make_lnx.exe, all command line options now work. * Added double buffering logic into core code. * Added additional image modes, hooks for direct-x * Re-organised screen mode selection code new CLynxWindow::VideoModeSet() * Implemented screen rotate * Modified line drawing code so that image reversal is done at source and not with Bit/StrechBlt - Nice speed improvement. * Some optimisation of CSusie::PaintSprites() to improve speed. * Added fps & efficiency calculations plus display window. * Re-wrote sprite painting/cpu interleave. (Some improvement in IRQ flicker) * Added joystick support. V0.20 25th May 1997 * Fixed a few minor bugs in the cart class, no affect on Handy though!! * Implemented early bailout in CSusie::PaintSprites() when offscreen * Implemented he pause key on 'Q' * Restructured source code so that the CPU emulation is entirely inline. * Changed sprite/timer interleave back original concept - separate updates with no interleaving, faster, causes IRQ (HBL) stability problems. * Speed improvements to CSusie::PaintSprites() & CMikie::Update(). * Small speed improvements to the CPU model. * Moved a number of common vars to global status. * Further optimised the CMikie::Update & CSystem::Update() functions, I can now get approx 50% performance on my P133 with 1x screen. (16 bit colour) * Implemented screen flipping * Finally fixed the superclipping algorithm, forgot to flip the quadrants around when hflip & vlfip are used !! * Split distribution into two separate archives - Dev & Std. * Implemented 1st attempt at hardware sprite collison, documentation is a little scarce. * Seemed nobody except me noticed that the screen was always 4 pixels too small. * Fixed nasty bug in UART emulation, caused by a misunderstanding of comlynx hardware implementation, Rx & Tx are looped, doh! (Homebrew:T_TRIS.O now works) * Fixed a bug in the timer implementation relating to timer done. * Fixed the other timer bug, that was stopping serial irq's being processed, even though handy doesn't support serial operations it must support UART emulation due to the loopback issue above. * Found and fixed another sprite engine bug relating to the screen origin being negative and the end positive, error in signed/unsigned handling. V0.10 23rd April 1997 * Rewrote entire CPU class to increase speed! * Modified CMikie::Update to stop timer slippage * Numerous mods to CMikie:Update to implement my new understanding of the way that Mikey IRQ's operate. * Fixed IODAT so that comlynx is NOT connected. * Implemented comlynx serial registers & IRQ structure (Not sure its correct though!!). * Corrected timer mode for non-reload, timers should stop after expiry. * Finally fixed the mother of all bugs in my my system class, not so much a bug but a misunderstanding of the documentation.... doh! V0.06 16th April 1997 (Beta-Tester only release) * Renamed the project to Handy from LWE to make it less windows specific * Fixed annoying message about fake rom after every cart load/reset, it should only happen on the first occurance now. * Fixed a bugette with negative tilt values, forgot to cast to a signed word. * Fixed a typo bug in the superclipper h & v swapped. * Rewrote CSusie::UpdateSprites() due to an implementation bug. Tilt is now possible once more... * Monster bug bashing session in CSusie::UpdateSprites() tilt/stretch is now working correctly. Still one issue with jitter on trailing edge. * Implemented PBKUP counter in Mikey to be a pseudo line hold-off before starting line DMA, hope this is right, there is no documentation to say exactl what this counter does. * Fixed bug with CPU Zero Page references being able to to beyond the zero page boundary, forgot to and with 0xff, Doh! (Many things now work!!!) * Fixed bug where by the current video page address was being picked up before the pseudo VBL resulting in frame being flipped in the wrong order. * Unfortunatly I've had to remove one of the optimisations as it was stopping some games (California Games in particular) working. Handy was doing 2 CPU instructions for each mikey/suzy update, I've now had to reduce that back to 1 with a resulting speed loss 8-( * Rewrote CMikie::Update() to improve the speed of operation. * Repartitioned & removed CSusie::Update to move functions under system::poke() handlers to speed up the system. V0.05 12th April 1997 * Command line filename support added * Homepage added to documentation, document tidyup. * Fixed CSusie::UpdateSprites() unpack bugs, vague documents are always such fun to interpret. * Implemented superclipping algorithm in CSusie:UpdateSprites() * Fixed sign bug in signed multiply function in CSusie::UpdateMath() due to incorrect casting. (apfel_2a.o looks like its working correctly now.) * Found and fixed the bug in CMikie::Update() that was stopping some cartridges loading, it took a long time to find as I was looking in the wrong place... * Reversed joystick axis, the documents seem to be wrong ?? V0.04 10th April 1997 * Repartitioned CLynxWindow::CLynxWindow() so that the lynx system creation is now outside in LynxInit() which returns a pointer to a lynx. * Added code to allow cartridge load from the file menu using LynxInit() * Added code so that LWE will remember the last cart type loaded and use that for the next cart to save the default to .o each time. * Added support for 16bit colour mode under windows. (Much prettier) * Optimised CMikie::Update() screen accesses. * Added code to pause the emulator when it loses focus to another window. * Implemented sprite h/v flip in CSusie:UpdateSprites() * Corrected quadrant initialisation error in CSusie:UpdateSprites() * Implemented signed maths in CSusie::UpdateMath() * Started implementation of sprite collision logic in CSusie::Update() V0.03 9th April 1997 * Repartitioned CSusie:Update() into UpdateSprites() & UpdateMath() * Implemented CSusie::UpdateMath(), signed arithmetic still needs doing. * Fixed 2 bugs in CSusue:UpdateSprites() * Update & implement cpu, mikey & suzy cycle counters V0.02 8th April 1997 * Its amazing what an evening with a source code profiler can do, LoadRunner is now almost playable on my P133. There's still scope for a number of speedups that will take a little more time than an evening. * Minor bugfix in CLynxWindow::OnKeyUp() left/right reversed. * Minor bugfix in CSusie::Update() Error in pixel calc on absolute literals fixed absolute literal sprites now seem to be working correctly. * Some cartridges now work. The boot screen of Gauntlet is recognisable !!! V0.01 7th April 1997 * First functional release of the emulator. All of the lynx hardware is now emulated except for the MATH & AUDIO functions. V0.00 ?? Oct 1996 * Started writing the debugging kernel & windows --- END OF FILE ---