]> Shamusworld >> Repos - virtualjaguar/blobdiff - docs/README
Removed files no longer needed, fixed build system to be more sane.
[virtualjaguar] / docs / README
index e3574daaa1b1db1535df88283a878eaf55832222..ae1e595e9f4c094c4c72dda3995b5d34d0339fb7 100644 (file)
-Virtual Jaguar v1.0.7 GCC/SDL release README
+--------------------------------------------
+Virtual Jaguar v2.0.0 GCC/SDL release README
 --------------------------------------------
 
 --------------------------------------------
 
+--------------
 - DISCLAIMER -
 - DISCLAIMER -
+--------------
 
 Or, "O liability, I do disclaim thee!"
 
 Ported by SDLEMU (Niels Wagenaar & Carwin Jones) and is based upon the
 
 Or, "O liability, I do disclaim thee!"
 
 Ported by SDLEMU (Niels Wagenaar & Carwin Jones) 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 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 license. For more information I 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
-their respective companies.
-
-- What is Virtual Jaguar GCC/SDL?
+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
 
 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
-license on 25 June 2003. 
+on 25 June 2003.
 
 
-Virtual Jaguar GCC/SDL is not only a port of the MS Visual C++/SDL sourcecode
+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
 but has also been extended and rewritten 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).
+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
 
 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 Carwin Jones. A major portion of the rewrite was done by
 
 The port was done by the SDLEMU crew (http://sdlemu.ngemu.com) and especially
 by Niels Wagenaar and Carwin Jones. A major portion of the rewrite was done by
@@ -49,32 +102,45 @@ 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! :)
 
 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
 
 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 PC. 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
 
 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.
+./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
 
 If you prefer a nice GUI instead of typing in command lines, you can either
-type ./vj 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
+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.
 
 under the directory where VJ lives) so that they show up when you pick the
 "Load" option from the "File" menu.
 
@@ -101,19 +167,43 @@ 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!
 
 NOTE: There are quite a few keys mapped to debugging functions at present. You
 have been warned!
 
-- Finally
+-------------------
+- 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
 
 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. 
+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].
 
 
 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). 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
 
 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".