-Virtual Jaguar v1.0.6 GCC/SDL release README
+--------------------------------------------
+Virtual Jaguar v2.0.0 GCC/SDL release README
--------------------------------------------
+--------------
- DISCLAIMER -
+--------------
Or, "O liability, I do disclaim thee!"
-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's 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 hardware 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 source code 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
-by the desired company in question.
-
-- What is Virtual Jaguar GCC/SDL?
-
-Virtual Jaguar is software dedicated to emulate the Atari Jaguar hardware
-on a standard P.C. The software was originally developed by Potato Emulation
-(http://potato.emu-france.com) by Cal2 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 that can make use of the Simple Directmedia Layer library (SDL).
+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 and FreeBSD). It may run on other systems
-as well but we can not guarantee that.
+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 cannot be
-used on a P.C. To use these games on Virtual Jaguar GCC/SDL you need to get ROM
-images. Besides the ROM images 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.
+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 (CD) boot ROM and several ROMs you can now
-use Virtual Jaguar using the following command:
+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:
-./vj [romfile] [-switches]
+./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
-./vj -? (or ./vj -help) you get an overview of the options you can use. WIN32
-users should look into the stdout.txt for that information. If you have a
-directory full of ROM files, you can type
-
-./vj [directory with ROM files] [-switches]
-
-and Virtual Jaguar will pull up a simple file selector to allow you to choose
-which ROM file you want to use.
+./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 # : Keypad /
Atari * : Keypad *
-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 edit the
-vj.cfg file and change the keys :)
+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
+-----------
+- 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.
+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.
+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].
-I hope you enjoy the emulator and will use it wisely!
+We hope you enjoy the emulator and will use it wisely!
-Special thanks go to guys over at ngemu.com and #ngemu (EFNET). Also Cal2 of
-Potato Emulation who originally developed this emulator is thanked for
-releasing the sources to the public.
+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!
SDLEMU
+
+
+*** Stuff to add in:
+
+ 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".
projects / virtualjaguar / blobdiff