DGen/SDL version 1.18 by Joe Groff <ognir@humboldt1.com>
original code by Dave <dave@dtmnt.com>
much additional code by Phil <webmaster@pknet.com>

CREDITS/CONTRIBUTORS:

As with any other open-source project, DGen/SDL wouldn't be where it is now 
without the contributions of many people. I'd be crazy to say I did this all
myself. :) Feel free to provide your own additions and get your name here!

Dave <dave@dtmnt.com>:
  - Of course, he wrote the original emulator ;)
  - Provided invaluable help while I was coding the sound.
Phillip K. Hornung [PKH] <redx@pknet.com>:
  - Scanline craptv filter
  - Joystick support for Linux
  - So many other little things I've lost track!
Andrew Bazan <abazan@mailbag.com>:
  - Got DGen/SDL to run under i386 BeOS R4.5! Woo-hoo!
Steve Snake <snake@toodarkpark.freeserve.co.uk>
  - The author of the best DOS emulator KGen, was also very patient with my
    stupid questions about the Genesis, thus allowing me to fix little
    emulation quirks. ;)
Amy Lear <Amikins@operamail.net>
  - Helped add 8-bit sound support. :)
Daniel Wislocki <wislocki@math.grin.edu>
  - Improved the sound engine to be nicer to higher-end systems.
John Stiles <stiles@emulation.net>
  - He works on the Mac port of DGen, and what a job he does! He wrote the
    original raster engine, and also has sped things up enormously.

--------------------------------------------------------------------------------
WHAT'S NEW?
--------------------------------------------------------------------------------

v1.18 <- v1.17
 * Enormous speed increase, thanks to the hard work of John Stiles, who also
   has put all interrupt bugs to rest, finally.
 * DGen works in FreeBSD! The included Makefile.config.FreeBSD should work
   without modifications. You need the GNU make and EGCS ports, though.
 * Demo record/play! You can record a demo of yourself playing a game with the
   '-d DEMONAME' switch, i.e. "dgen -d foo.demo my_rom.smd". Then play it back
   later with "dgen -D foo.demo my_rom.smd". Also, no verifaction checks are
   done on the demos, so you can feed it arbitrary files and see what happens,
   if you like. :)

v1.17 <- v1.16
 * Save RAM implementation has been overhauled, so now games with overlapping
   ROM and save RAM (like Phantasy Star IV and Sonic 3 + Knuckles) can save
   games correctly. Many thanks to Steve Snake for helping me make this work
   right.
 * Crude PAL mode support, give the '-P' option to use it. Doesn't work very
   well yet.
 - I made some changes that should (hopefully) make DGen run properly on
   big-endian platforms, but I don't have any way of testing it. If you have
   a PowerPC, SPARC, or other big-endian system, give it a try and help me
   iron out the wrinkles. :)
 * Window is now emulated properly, so Herzog Zwei split-screen and other
   little bugs should be fixed. Thanks again to Steve.
 - A little bug that caused SDL to complain about not being able to
   initialize sound, even if bool_sound was false in dgenrc, was fixed. This
   should help all you folks without sound cards.
 * Assembler tile rendering is now in place for the new raster effect engine.
   A small but noticeable speed increase. :) [PKH]
 * All the SDL-dependent stuff has been separated into the sdl/ directory,
   and I wrote a little platform-dependent (pd) API so you can attach an
   interface for your favorite Unix-like operating system and toolkit. :)
   If you want to do a port to BeOS, MacOS X, QNX, etc. this should make your
   life easier. I also hope to have raw Xlib and SVGAlib interfaces to replace
   SDL, and thus require one less thing to download. :)
 - Improved sound writing method, by Daniel Wislocki <wislocki@math.grin.edu>.
   He says this improves flaky sound in 44kHz, and also fixes the problem of
   the emulator being too fast. I have a very slow computer, so I have to take
   his word for it. ;)
 - I also removed most of the messages dgen makes (except for errors), so that
   it is quieter. If you liked having all those messages, tell me and I'll put
   them back in. ;)
 
v1.16 <- v1.15
 * New '-R' switch sets dgen to realtime priority (-20). Nice if you can make
   dgen setuidroot, and you want NOTHING interrupting your Genesis experience ;)
   This is only advantageous if you have a joystick and run fullscreen,
   otherwise the realtime priority shuts out the X server so that keypresses
   are extremely lagged. Not very good, it was just an experiment ;)
 - Fixed the little problem with static sound in some games.
 * Brand new rendering engine, so now raster effects work! :D John Stiles
   wrote a pretty good one, which I stole and rewrote, adding little
   enhancements he forgot (like support for other bitdepths, blank tile
   checking, etc.) ;)
 * Now there is on-the-fly decompression available for bzip2 and zip compressed
   ROMs. The zip decompression uses gzip, so will only work if the rom file is
   the _first_ file in the zip. bzip2 decompression requires that you have
   bzip2 on your PATH.
 - Added a CPU pause feature. By pressing the key_stop key (default 'z') the
   CPU loop stops, in a CPU-friendly manner. Press any key to start again.
 * Little assembler (with/without MMX) functions for memory copying, thanks to
   Phil.
 * ROM checksum fixing, thanks to Dave :). If you have a ROM which stalls
   on a red screen, hit F1 (or whatever you have mapped to key_fix_checksum ;)
   and try resetting. This may be a problem when using Game Genie codes.
 * 8-bit sound support. Now all of you who don't have (or don't want ;) new
   sound cards can enjoy the old soundtracks. :)
 * An egregrious bug in the way horizontal and vertical interrupts are handled
   has been fixed! Now Sonic games, Road Rash 2, Ecco etc. all work properly :D

v1.15 <- v1.14
 * Added a CPU hot swap using the F11 key, this can be changed in the RC file
   as usual.  :)  Compile both CPU cores in, and hot swap them on the fly,
   simple as that!  (For those of you who have 1GHz computers and need a
   speed downer, use Musashi (it's more accurate an emulator, and written in
   a high level language.)  :) [PKH]
 - Minor Makefile changes to allow both CPU cores compiled in. [PKH]
 - Hacked a save RAM problem that affected certain games that had the start
   and end bytes == in the ROM header.  This would cause an emulator lockup
   in most cases, and create a bogus file in ~/.dgen/ram/ [PKH]
 - Modified the sound skipping (framerate skip based on sound) routine
   slightly, increased speed noticeably on slow computers. [PKH]
 - Moved the bulky events polling and increased calling frequency.  Resulted
   in better control in many games, especially fighting games and shooters!
   :) [PKH]
 * Joystick mapping is now configurable from dgenrc. Look at sample.dgenrc.1
   for all the new options.  Comment out the joystick lines if you don't
   compile support in for the joystick or DGen will nag, and we all hate
   nagging don't we?  ;)  [PKH]
 - Made the SMD magic a little less strict. More SMDs should be recognized now
   hopefully.
 - The `-r' option now loads RC files in _addition_ to $HOME/.dgen/dgenrc, as
   opposed to the original behavior to load an rc file _instead_ of dgenrc.
 * Thanks to Andrew Bazan <abazan@mailbag.com>, DGen/SDL is now known to work
   under i386 BeOS! Check out http://www.sitebe.com/abazan/DGen.html for a
   precompiled binary. With some help from him, I made some BeOS-friendly
   adjustments with his help.
 - Changed default value of int_nice to 0. There are a lot of people who don't
   mind 99% CPU usage... ;)
 - Sound segments are now configurable from dgenrc. Higher values yield more
   latency, but are faster; lower values stay in sync with the graphics much
   better. 8 is a good compromise; use 4 on really fast systems or 16 for
   slower machines.
 - Now there is a 5-second printout of info off the ROM header when you start
   DGen, if you set "bool_show_carthead" on in dgenrc. It's off by default;
   turn it on if you're interested in the info.

--------------------------------------------------------------------------------
SUPPORTED PLATFORMS
--------------------------------------------------------------------------------
I guess "supported" should say "known to compile under." :) I've heard
of people compiling DGen/SDL under:
  - BeOS R4.5 Intel
  - Linux Intel

Come on, people, this list is pathetic! Be adventurous, and try compiling on
other diverse platforms! If it doesn't work, fix it and give me a patch! Let's
give great Genesis emulation to every platform under the sun :)

--------------------------------------------------------------------------------
WHAT IS THIS?
--------------------------------------------------------------------------------
This is the SDL version of the DGen Sega Genesis emulator, originally by
Dave <dave@dtmnt.com>. The DGen webpages are at http://www.dtmnt.com/ . If you
don't know what a Sega Genesis or an emulator are, then you have the wrong
archive. :)
Anyway, since is was the only decent open-source Genesis emulator in existence
that I could find, I decided to take a few weekends and port it to the SDL
library. Note that DGen is by no means perfect (far from it, actually), and
this port is far less perfect, but many games are still
very playable. But if you've been spoiled by the likes of KGen and Genecyst,
you may miss them before long. Still, give DGen a chance!

SDL is an open-source library for Linux, BeOS, and other various Unices
that takes advantage of the various native graphics and sound systems of the
operating systems, by Sam Latinga <slouken@devolution.com> The SDL webpages
are available at http://www.devolution.com/~slouken/SDL/, where you can get
source and precompiled binaries of SDL itself, and all sorts of programs
developed with it, from DOOM and Hexen to Asteroids and more.

--------------------------------------------------------------------------------
HOW DO I COMPILE IT?
--------------------------------------------------------------------------------

Unpack this source archive to a convenient location (I guess you already did
that ;). If you haven't gotten SDL set up yet, you'll want to take care of that
before playing with this source code.

Look over Makefile.config, and adjust things as you see fit. I hope it is
fairly well self-documented; I won't repeat myself here.  See the section
"USING STARSCREAM AND MZ80 EMULATORS" for info on using these assembler CPU
cores. Perl and NASM are recommended if you have an Intel CPU.

Well, if you got the Makefile squared away, run make! If you got no errors,
then you'll have a wonderful dgen executable. If you want to use fullscreen
support for most X servers, su to root and make setuidroot to give DGen
superuser priviledges.

--------------------------------------------------------------------------------
@%#$*! THE STUPID THING WON'T COMPILE!
--------------------------------------------------------------------------------

Umm... sorry! :( I know it compiles and runs on Linux/i386, but I don't have
the means or the money to test it on BeOS, Solaris, IRIX, or whatever system
you have. Try to fix it, and send me a patch! However, if you are having
extreme unstoppable problems, then definitely tell me, because I'll hopefully
be able to help. Send me whatever error messages make gives, your Makefile,
and some info about your system (like CPU, Operating System, SDL version, etc)

--------------------------------------------------------------------------------
HOW DO I USE IT?
--------------------------------------------------------------------------------

Good question. ;) Anyway, you'll want to create a ".dgen" directory in your
home directory. This is where the RC file and save states are kept. Look over
the file "sample.dgenrc.1" in the source directory. This is a sample dgenrc
file (like the name says), which sets all values to their defaults. This 
should give you an idea of the keys DGen uses to control the Genesis. If
you don't like this default layout, edit it and save it to ".dgen/dgenrc" in
your home directory. Then from whatever directory the dgen executable is in,
run:

	./dgen [-r RCFILE] [-l SLOT] [-n USEC] [-f] [-p PATCHES]
	       [-s SOUNDRATE] [-j] [-P] ROMNAME

to  start DGen with the cartridge rom image in the file ROMNAME.

The "-r RCFILE" option will tell dgen to read in RCFILE in addition to
the default "$HOME/.dgen/dgenrc". Multiple -r options can be given, to load
many rc files.

"-l SLOT" will cause DGen to load the save state in slot
SLOT (a number from 0 to 9). If this option is unspecified and "bool_autoload"
is true in your dgenrc, DGen will automatically load the savestate in slot 0
on startup.

"-p PATCHES" activates the Game Genie. It takes a comma-delimited
list of Game Genie (ABCD-EFGH) and Hex (123456:ABCD) patches to alter the ROM.
For example '-p ATBT-AA32,AY3T-AACL,SCRA-BAX0' loads the Sonic 1 cheats to start
with 5 extra lives and make each ring worth 8.

"-s SOUNDRATE" changes the sound rate DGen will attempt to set. The default if
no `-s' is given is 22050Hz.

"-n USEC" causes DGen to sleep for USEC microseconds every frame. The "int_nice"
field in dgenrc has the same effect.

"-f" will cause DGen to try to run fullscreen. This requires root
priviledges on X servers using the XFree86 DGA extension. For best results, your
X configuration should have a modeline for 320x240 mode.

"-j" activates the Linux joystick support.

"-P" starts the emulator in PAL mode, which many European games use.

Compiled using assembler tiles, StarScream 68000 and MZ80 CPU emulators,
running DGen in a fullscreen 256-color mode, on my 300MHz AMD K6-2 using
Linux 2.2.9 and XFree86 3.3.2.3, DGen hits almost every frame!

If you get DGen/SDL working and like it, be sure to send a nice e-mail to me
and/or Dave. Nice messages from satisfied users is what keeps me going ;)

--------------------------------------------------------------------------------
IT'S TOO SLOW!
--------------------------------------------------------------------------------
Well, sorry. Here are some ideas to help accelerate it:

 - Lower the value of "int_nice" in your dgenrc. 0 is good for short tempers ;)
 - Turn off sound.
 - Run fullscreen, if possible.
 - If you have an Intel processor, try compiling with assembler tiles and 
   the StarScream/MZ80 CPU cores, if you didn't already.
 - Increase int_soundsegs to 16 or (if you're desperate) 32.
 - Buy a faster computer. (sorry, had to say it ;)

--------------------------------------------------------------------------------
IT'S TOO FAST!
--------------------------------------------------------------------------------
I couldn't believe it either, but someone asked me this. If you happen to find
yourself in this UNFORTUNATE predicament :), here's how to slow it down:

 - Raise the sound rate to 44100Hz. It sounds a LOT better, and is a LOT slower.   ;)
 - Compile with the Musashi 68000 CPU core, instead of StarScream. Musashi
   is a little more accurate than StarScream, so if you can spare the speed
   decrease, use it!
 - Increase the value of int_nice in your dgenrc. This is the best way to slow
   things down, since it makes dgen much more CPU friendly.

--------------------------------------------------------------------------------
GETTING/USING STARSCREAM AND MZ80 EMULATORS
--------------------------------------------------------------------------------

1: Get the MZ80 and/or StarScream distribution.
   MZ80, by Neil Bradley <neil@synthcom.com> is available at
     ftp://ftp.synthcom.com/pub/emulators/cpu/makez80.zip
   StarScream, by Neil Corlett <corlett@elwha.nrrc.ncsu.edu> is available at 
     http://www4.ncsu.edu/~nscorlet/star/
   Or you can get them from the DGen/SDL page, 
   http://www.humboldt1.com/~ognir/dgen-sdl.html, already setup to be easily
   inserted into the DGen/SDL source tree. :)

2: Put the source files from the MZ80 dist in the mz80/ directory.
   Put the source files from the StarScream dist in the star/ directory.
   Make sure when you unpack them the names are all lowercase. The ZIP
   files may have the names stored in DOS-style uppercase.

3: IMPORTANT! Make sure the source text files are in Unix format, not DOS
   format! If you have the dos2unix utility, this is easy:
     dos2unix mz80/*.{c,h}
     dos2unix star/*.{c,h}

5: Edit Makefile.config as directed to use StarScream and mz80.

6: Make clean and compile! Enjoy the newfound speed!

--------------------------------------------------------------------------------
BUGS
--------------------------------------------------------------------------------
Of course the chances of finding a bug are unlikely ;), but if you do, tell me
about it. Send me a patch too, if possible ;)

