Shamusworld >> Repos - virtualjaguar/blob - docs/README

   1 --------------------------------------------
   2 Virtual Jaguar v2.0.0 GCC/SDL release README
   3 --------------------------------------------
   4
   5 --------------
   6 - DISCLAIMER -
   7 --------------
   8
   9 Or, "O liability, I do disclaim thee!"
  10
  11 Ported by SDLEMU (Niels Wagenaar & Carwin Jones) and is based upon the
  12 original work by David Raingeard of Potato Emulation. For requirements please
  13 consult the INSTALL file for more information about supported OS's and
  14 software requirements.
  15
  16 The use of this software is entirely at your own risk. While it won't rape
  17 your dog, it might do other nasty things. We can't be held responsible for
  18 damage done to you hardware and/or software. You have been warned! This
  19 software may require the use of the Atari Jaguar boot ROMs and/or Commercial
  20 ROM images. You may only use the ROM images if you own the cartridges itself.
  21 The use of Commercial ROMs without owning the original cartridge is illegal in
  22 most countries and could result in fines and/or legal actions.
  23
  24 This software is released under the GPL v2 or later. For more information I
  25 direct you to the GPL.TXT. You may hack/change the code anyway you like. You
  26 may not commercially sell this software. If you make changes, release the
  27 source code to the public and send the changes you made to the original
  28 authors.
  29
  30 The products, trademarks and/or brands used in these documents and/or
  31 sourcecode are owned by their respective companies and/or successors in
  32 interest.
  33
  34 ----------------------------------------------------------------
  35 - IMPORTANT NOTE ABOUT JAGUAR FILE FORMATS--READ THIS OR ELSE! -
  36 ----------------------------------------------------------------
  37
  38 There seems to be a lot of confusion surrounding the various file formats that
  39 Jaguar programs come in, and a lot of this confusion seem to come from
  40 Cowering's GoodJag renaming tool. Note that it simply gets some files wrong,
  41 and it also incorrectly renames cartridge images with an extension that
  42 belongs to an already established extension (.jag is a Jaguar Server
  43 executable--read on). To clarify, there are basically four major types of
  44 Jaguar binary images that are NOT cartridge images:
  45
  46     .abs
  47     .jag
  48     .rom
  49     .bin
  50
  51 The first type, the .abs file, is a DRI/Alcyon format absolute location
  52 executable. These come in two different flavors and contain load and run
  53 addresses in their headers. Note that some files which have an .abs extension
  54 are really incorrectly labelled .bin files with no header information
  55 whatsoever.
  56
  57 The second type, the .jag file, is a Jaguar Server executable. These files
  58 contain header information that tells you where to load and run the file's
  59 executable code. Note that as of this writing (8/5/2005) that the GoodJag ROM
  60 renaming tool by Cowering incorrectly renames Jaguar cartridge ROM dumps to
  61 have a .jag extension (a better choice, and the one supported by Virtual
  62 Jaguar, is .j64)--if you're trying to run a ROM image with a .jag extension on
  63 VJ, it will misinterpret it as a Jaguar Server executable and likely fail to
  64 run.
  65
  66 The third type, the .rom file, is an Alpine Board/ROM Image file. These files
  67 have no header, but are known to load and run at $802000 in the Jaguar memory
  68 space. Again, these are *different* from cartridge dumps since they load at a
  69 higher address than a Jaguar cartridge.
  70
  71 The fourth type, the .bin file, is simply a Jaguar executable with no header.
  72 Since these files contain no information about where they load and execute,
  73 Virtual Jaguar does not support this file type. Go bug the author to release
  74 either a file with proper headers or a file in Alpine ROM format. Virtual
  75 Jaguar is not omniscient (yet)! ;)
  76
  77 There is a fifth type of file that is supported by Virtual Jaguar, the .j64
  78 file, which is simply a 1, 2, or 4 Meg dump of a Jaguar cartridge ROM which
  79 loads at $800000 in the Jaguar memory space.
  80
  81 -----------------------------------
  82 - What is Virtual Jaguar GCC/SDL? -
  83 -----------------------------------
  84
  85 Virtual Jaguar is software dedicated to emulating the Atari Jaguar hardware on
  86 a standard PC. The software was originally developed by David Raingeard of
  87 Potato Emulation [http://potato.emu-france.com] and was released under the GPL
  88 on 25 June 2003.
  89
  90 Virtual Jaguar GCC/SDL is not just a port of the MS Visual C++/SDL sourcecode
  91 but has also been extended and rewritten so that we can enjoy Atari Jaguar
  92 emulation on every platform that has a GCC compiler and a port of the Simple
  93 Directmedia Layer library (SDL).
  94
  95 Currently Virtual Jaguar GCC/SDL compiles on WIN32 using mingw, and several
  96 UN*X based systems (BeOS, Linux, FreeBSD and MacOS). It may run on other
  97 systems as well but we can not guarantee that.
  98
  99 The port was done by the SDLEMU crew (http://sdlemu.ngemu.com) and especially
 100 by Niels Wagenaar and Carwin Jones. A major portion of the rewrite was done by
 101 James L. Hammons. You may contact us by e-mail (sdlemu@ngemu.com) or leave a
 102 message on the SDLEMU Official Forum (see the website). Patches and bugfixes
 103 are particularly welcome! :)
 104
 105 More information about the incredible SDL libraries can be found at
 106 http://www.libsdl.org. Thanks Sam--you rock! :)
 107
 108 --------------------------------
 109 - Using Virtual Jaguar GCC/SDL -
 110 --------------------------------
 111
 112 After compiling the binary (see INSTALL) you can now run original Atari Jaguar
 113 games. These games are distributed on cartridges and can therefore cannot be
 114 used on a PC (we're still waiting for that Jaguar-on-a-PCI-card that you plug
 115 into your late model PC, complete with cartridge slot and controller connectors
 116 ;-). To use these games on Virtual Jaguar GCC/SDL you need to get ROM images.
 117 Besides the ROM images from commercial games, you may also need to obtain the
 118 Atari Jaguar boot ROM (and/or CD boot ROM) which you must copy to the BIOS
 119 directory. For legal issues concerning ROM images please consult the DISCLAIMER
 120 at the beginning of this file.
 121
 122 After obtaining the Atari Jaguar boot ROM (and/or CD boot ROM) and several game
 123 ROMs you can now use Virtual Jaguar using the following command:
 124
 125 ./vj [romfile] [-switches]
 126
 127 The context of ROMFILE is the filename of the an Atari Jaguar ROM dump (can be
 128 either compressed or uncompressed). You can also use switches. By just typing
 129 ./vj -? (or ./vj -help) you get an overview of the options you can use. WIN32
 130 users should look into the stdout.txt in the directory they ran Virtual Jaguar
 131 for that information.
 132
 133 If you prefer a nice GUI instead of typing in command lines, you can either
 134 type ./vj or double click on the Virtual Jaguar executable. If you have a
 135 directory full of ROM files, you can tell Virtual Jaguar where they are by
 136 editing the appropriate line in the vj.cfg file (it assumes a ROMs directory
 137 under the directory where VJ lives) so that they show up when you pick the
 138 "Load" option from the "File" menu.
 139
 140 This emulator also emulates the Atari Jaguar gamepads. By using the following
 141 keyboard or joystick settings you can (possibly) play a given game:
 142
 143 Atari Button C       : Z or joystick button 3
 144 Atari Button B       : X or joystick button 2
 145 Atari Button A       : C or joystick button 1
 146 Atari Buttons 1 - 10 : Keypad 0 - 9 (0 = 10)
 147 Atari Start/Pause    : ENTER
 148 Atari Select         : '
 149 Atari UP             : UP    or joystick UP
 150 Atari DOWN           : DOWN  or joystick DOWN
 151 Atari LEFT           : LEFT  or joystick LEFT
 152 Atari RIGHT          : RIGHT or joystick RIGHT
 153 Atari #              : Keypad /
 154 Atari *              : Keypad *
 155
 156 With ESC you can easily stop Virtual Jaguar GCC/SDL which will get you back to
 157 the GUI (pressing ESC again will take you back to the game). To exit VJ, you
 158 can either select File|Quit or press the "Q" key on your keyboard. If you want
 159 to change the key layout, simply edit the vj.cfg file and change the keys. :)
 160 NOTE: There are quite a few keys mapped to debugging functions at present. You
 161 have been warned!
 162
 163 -------------------
 164 - A note on sound -
 165 -------------------
 166
 167 By default, the Virtual Jaguar's DSP is turned off, since it doesn't work very
 168 well at present (it requires a lot of horsepower to sound decent at this
 169 point!). In order to hear any sound at all, you have to either edit the vj.cfg
 170 file and change the appropriate line or set the DSP on in the GUI (found under
 171 Settings|Misc). One word of caution: Use the old DSP core instead of the new
 172 pipelined version for now--the new pipelined DSP core has not yet been
 173 optimized and runs quite slow at present! Once the DSP issues have been ironed
 174 out, it will be turned on by default and you won't have to deal with it
 175 anymore. ;)
 176
 177 -----------
 178 - Finally -
 179 -----------
 180
 181 If you find bugs, enhance the code or simply have questions, drop us an e-mail
 182 at sdlemu AT ngemu DOT com or drop a message on the SDLEMU Official Forum.
 183
 184 More information about this project (releases/WIP) can be found at the official
 185 Virtual Jaguar website [http://www.icculus.org/virtualjaguar] and on the SDLEMU
 186 website [http://sdlemu.ngemu.com].
 187
 188 We hope you enjoy the emulator and will use it wisely!
 189
 190 Special thanks go to guys over at ngemu.com and #ngemu (EFNET). Thanks also to
 191 David Raingeard of Potato Emulation who originally developed this emulator and
 192 released the sources to the public. We couldn't have done it without you!
 193
 194 SDLEMU
 195
 196 Stuff to add in:
 197
 198  - How to run ROMs from the command line with spaces in the names (quoting)
 199  - The behavior of the emulator when running from the command line (passed in ROM
 200    vs. non)