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

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