X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=docs%2FREADME;h=ae1e595e9f4c094c4c72dda3995b5d34d0339fb7;hb=f548beede257a2252a2639e3fe03c7cda99433ed;hp=7865403b25fa8b77ec36d75e0c963d7643b9a3e2;hpb=86bd0f2592c3cd674239532247276bd2d579a857;p=virtualjaguar diff --git a/docs/README b/docs/README index 7865403..ae1e595 100644 --- a/docs/README +++ b/docs/README @@ -1,106 +1,209 @@ -Virtual Jaguar v1.0.0 GCC/SDL release README +-------------------------------------------- +Virtual Jaguar v2.0.0 GCC/SDL release README -------------------------------------------- +-------------- - DISCLAIMER - - -Ported by SDLEMU (Niels Wagenaar & Caz) and is based upon the original work -from Potato Emulation. For requirements please consult the INSTALL file for -more information about supported OS' and software requirements. - -The use of this software is entirely at your own risk. We can't be held -responsible for damage done to you hard- and/or software. This software -requires the use of the Atari Jaguar (CD) boot ROM and/or Commercial ROM -images. You may only use the ROM images if you own the cartridges itself. -The use of Commercial ROM's without owning the original cartridge is -illegal in most countries and could result in fines and/or legal actions. - -This software is released under the GPL license. For more information I -should direct you to the GPL.TXT. You may hack/change the code anyway you -like. You may not commercially sell this software. - -If you make changes, release the sourcecode to the public and send us the -changes you made to the original authors. - -The products and brands used in these documents and/or sourcecode are owned -but the desired company in question. - -- What is Virtual Jaguar GCC/SDL? - -Virtual Jaguar is software dedicated to emulate the Atari Jaguar hardware -on you standard P.C. The software was originally developed by Potato Emulation -(http://potato.emu-france.com) and was released under the GPL license on -25 June 2003. - -Virtual Jaguar GCC/SDL is a port of the MS Visual C++/SDL sourcecode so that -we can enjoy Atari Jaguar emulation on every platform which uses the GCC -compiler and what can make use of the Simple Directmedia Layer library (SDL). - -Currently Virtual Jaguar GCC/SDL compiles on WIN32, using mingw, and several -UN*X based systems (BeOS, Linux and FreeBSD). It may run on other systems -as well but we can not garantee that. +-------------- + +Or, "O liability, I do disclaim thee!" + +Ported by SDLEMU (Niels Wagenaar & Carwin Jones) and is based upon the +original work by David Raingeard of Potato Emulation. For requirements please +consult the INSTALL file for more information about supported OS's and +software requirements. + +The use of this software is entirely at your own risk. While it won't rape +your dog, it might do other nasty things. We can't be held responsible for +damage done to you hardware and/or software. You have been warned! This +software may require the use of the Atari Jaguar boot ROMs and/or Commercial +ROM images. You may only use the ROM images if you own the cartridges itself. +The use of Commercial ROMs without owning the original cartridge is illegal in +most countries and could result in fines and/or legal actions. + +This software is released under the GPL v3 or later. For more information I +direct you to the GPLv3 file. You may hack/change the code anyway you like. You +may not commercially sell this software. If you make changes, release the +source code to the public and send the changes you made to the original +authors. + +The products, trademarks and/or brands used in these documents and/or +sourcecode are owned by their respective companies and/or successors in +interest. + +---------------------------------------------------------------- +- IMPORTANT NOTE ABOUT JAGUAR FILE FORMATS--READ THIS OR ELSE! - +---------------------------------------------------------------- + +There seems to be a lot of confusion surrounding the various file formats that +Jaguar programs come in, and a lot of this confusion seem to come from +Cowering's GoodJag renaming tool. Note that it simply gets some files wrong, +and it also incorrectly renames cartridge images with an extension that +belongs to an already established extension (.jag is a Jaguar Server +executable--read on). To clarify, there are basically four major types of +Jaguar binary images that are NOT cartridge images: + + .abs + .jag + .rom + .bin + +The first type, the .abs file, is a DRI/Alcyon format absolute location +executable. These come in two different flavors and contain load and run +addresses in their headers. Note that some files which have an .abs extension +are really incorrectly labelled .bin files with no header information +whatsoever. + +The second type, the .jag file, is a Jaguar Server executable. These files +contain header information that tells you where to load and run the file's +executable code. Note that as of this writing (8/5/2005) that the GoodJag ROM +renaming tool by Cowering incorrectly renames Jaguar cartridge ROM dumps to +have a .jag extension (a better choice, and the one supported by Virtual +Jaguar, is .j64)--if you're trying to run a ROM image with a .jag extension on +VJ, it will misinterpret it as a Jaguar Server executable and likely fail to +run. + +The third type, the .rom file, is an Alpine Board/ROM Image file. These files +have no header, but are known to load and run at $802000 in the Jaguar memory +space. Again, these are *different* from cartridge dumps since they load at a +higher address than a Jaguar cartridge. + +The fourth type, the .bin file, is simply a Jaguar executable with no header. +Since these files contain no information about where they load and execute, +Virtual Jaguar does not support this file type. Go bug the author to release +either a file with proper headers or a file in Alpine ROM format. Virtual +Jaguar is not omniscient (yet)! ;) + +There is a fifth type of file that is supported by Virtual Jaguar, the .j64 +file, which is simply a 1, 2, or 4 Meg dump of a Jaguar cartridge ROM which +loads at $800000 in the Jaguar memory space. + +----------------------------------- +- What is Virtual Jaguar GCC/SDL? - +----------------------------------- + +Virtual Jaguar is software dedicated to emulating the Atari Jaguar hardware on +a standard PC. The software was originally developed by David Raingeard of +Potato Emulation [http://potato.emu-france.com] and was released under the GPL +on 25 June 2003. + +Virtual Jaguar GCC/SDL is not just a port of the MS Visual C++/SDL sourcecode +but has also been extended and rewritten so that we can enjoy Atari Jaguar +emulation on every platform that has a GCC compiler and a port of the Simple +Directmedia Layer library (SDL). + +Currently Virtual Jaguar GCC/SDL compiles on WIN32 using mingw, and several +UN*X based systems (BeOS, Linux, FreeBSD and MacOS). It may run on other +systems as well but we can not guarantee that. The port was done by the SDLEMU crew (http://sdlemu.ngemu.com) and especially -by Niels Wagenaar and Caz. You may contact us by e-mail (sdlemu@ngemu.com) or -leave a message on the SDLEMU Official Forum (see the website). +by Niels Wagenaar and Carwin Jones. A major portion of the rewrite was done by +James L. Hammons. You may contact us by e-mail (sdlemu@ngemu.com) or leave a +message on the SDLEMU Official Forum (see the website). Patches and bugfixes +are particularly welcome! :) -More information about SDL can be found at http://www.libsdl.org. +More information about the incredible SDL libraries can be found at +http://www.libsdl.org. Thanks Sam--you rock! :) -- Using Virtual Jaguar GCC/SDL +-------------------------------- +- Using Virtual Jaguar GCC/SDL - +-------------------------------- After compiling the binary (see INSTALL) you can now run original Atari Jaguar -games. These games are distributed on cartridges and can there for not be used -on a P.C. To use these games on Virtual Jaguar GCC/SDL you need to get ROM -images. Besides that ROM imgaes from Commercial games you must also obtain the -Atari Jaguar (CD) boot ROM which you must copy to the BIOS directory. -For legal issues concerning ROM images please consult the DISCLAIMER at the -beginning of this file. - -After obaining the Atari Jaguar (CD) boot ROM and several ROM's you can now -use Virtual Jaguar using the following command : - -./jag_em romfile -switch - -The context of ROMFILE is the filename of the UNCOMPRESSED Atari Jaguar ROM -dump. You can also use switches. By just typing ./jag_em you get an overview -of the options you can use. WIN32 users should look into the stdout.txt for -that information. - -If you succesfully start the emulator with the game you should see a window -(or fullscreen) which shows the game. If the game doesn't comply to a CRC -check the game will display a black screen, this means that the game is -probably a hack or a new game which isn't supported. You may add the CRC -check to the sources yourself (src/crc32.cpp). - -This emulator also emulates the Atari Jaguar Analog gamepads. By using the -following keyboard or joystick settings you can (possibly) play the game : - -Atari Button A : Z or joystick button 1 +games. These games are distributed on cartridges and can therefore cannot be +used on a PC (we're still waiting for that Jaguar-on-a-PCI-card that you plug +into your late model PC, complete with cartridge slot and controller connectors +;-). To use these games on Virtual Jaguar GCC/SDL you need to get ROM images. +Besides the ROM images from commercial games, you may also need to obtain the +Atari Jaguar boot ROM (and/or CD boot ROM) which you must copy to the BIOS +directory. For legal issues concerning ROM images please consult the DISCLAIMER +at the beginning of this file. + +After obtaining the Atari Jaguar boot ROM (and/or CD boot ROM) and several game +ROMs you can now use Virtual Jaguar using the following command: + +./virtualjaguar [romfile] [-switches] + +The context of ROMFILE is the filename of the an Atari Jaguar ROM dump (can be +either compressed or uncompressed). You can also use switches. By just typing +./virtualjaguar -? (or ./virtualjaguar -help) you get an overview of the +options you can use. WIN32 users should look into the stdout.txt in the +directory they ran Virtual Jaguar for that information. Also, WIN32 users +should be aware that if their ROM filenames contain any spaces, you will have +to enclose the ROMFILE in double quotes for Virtual Jaguar to function +properly. + +Note that running Virtual Jaguar this way will cause the emulator to exit +completely upon pressing the ESC key. If this is not what you want, then omit +the ROMFILE and it will bring up a nice GUI instead. + +If you prefer a nice GUI instead of typing in command lines, you can either +type ./virtualjaguar or double click on the Virtual Jaguar executable. If you +have a directory full of ROM files, you can tell Virtual Jaguar where they are +by editing the appropriate line in the vj.cfg file (it assumes a ROMs directory +under the directory where VJ lives) so that they show up when you pick the +"Load" option from the "File" menu. + +This emulator also emulates the Atari Jaguar gamepads. By using the following +keyboard or joystick settings you can (possibly) play a given game: + +Atari Button C : Z or joystick button 3 Atari Button B : X or joystick button 2 -Atari Button C : C or joystick button 3 +Atari Button A : C or joystick button 1 Atari Buttons 1 - 10 : Keypad 0 - 9 (0 = 10) Atari Start/Pause : ENTER -Atari Select : TAB +Atari Select : ' Atari UP : UP or joystick UP Atari DOWN : DOWN or joystick DOWN Atari LEFT : LEFT or joystick LEFT Atari RIGHT : RIGHT or joystick RIGHT +Atari # : Keypad / +Atari * : Keypad * + +With ESC you can easily stop Virtual Jaguar GCC/SDL which will get you back to +the GUI (pressing ESC again will take you back to the game). To exit VJ, you +can either select File|Quit or press the "Q" key on your keyboard. If you want +to change the key layout, simply edit the vj.cfg file and change the keys. :) +NOTE: There are quite a few keys mapped to debugging functions at present. You +have been warned! + +------------------- +- A note on sound - +------------------- + +By default, the Virtual Jaguar's DSP is turned off, since it doesn't work very +well at present (it requires a lot of horsepower to sound decent at this +point!). In order to hear any sound at all, you have to either edit the vj.cfg +file and change the appropriate line or set the DSP on in the GUI (found under +Settings|Misc). One word of caution: Use the old DSP core instead of the new +pipelined version for now--the new pipelined DSP core has not yet been +optimized and runs quite slow at present! Once the DSP issues have been ironed +out, it will be turned on by default and you won't have to deal with it +anymore. ;) + +----------- +- Finally - +----------- + +If you find bugs, enhance the code or simply have questions, drop us an e-mail +at sdlemu AT ngemu DOT com or drop a message on the SDLEMU Official Forum. + +More information about this project (releases/WIP) can be found at the official +Virtual Jaguar website [http://www.icculus.org/virtualjaguar] and on the SDLEMU +website [http://sdlemu.ngemu.com]. + +We hope you enjoy the emulator and will use it wisely! + +Special thanks go to guys over at ngemu.com and #ngemu (EFNET). Thanks also to +David Raingeard of Potato Emulation who originally developed this emulator and +released the sources to the public. We couldn't have done it without you! -With ESC you can easily stop Virtual Jaguar GCC/SDL which will get you back -to you command prompt. If you want to change the key layout, simply hack the -src/joystick.cpp and change the keys :) - -- Finally - -If you find bugs, enhance the code or simply have questions. Drop us an e-mail -at sdlemu AT ngemu DOT com or drop a message on the SDLEMU Official Forum. - -More information about this projects (releases/WIP) can be found at the SDLEMU -website : http://sdlemu.ngemu.com. +SDLEMU -I hope you enjoy the emulator and will use it wisely! -Special thanks go to guys over at ngemu.com and #ngemu (EFNET). Also the author -who originally developed this emulator is thanked for releasing the sources to -the public. +*** Stuff to add in: -SDLEMU + o Documentation needs a rewrite, more or less, as the GUI is now front and + center. Need to update the docs to reflect this change. + o Document the new "solid" zip file archive mechanism which allows putting + artwork into a "ROM".