

               ##### ####### ##   ## #### ######   ###   ####
              ##   #  ##   # ###  ##  ##  # ## #  ## ##   ##
             ##       ##     #### ##  ##    ##   ##   ##  ##
             ##       ####   #######  ##    ##   ##   ##  ##
             ##  ###  ##     ## ####  ##    ##   #######  ##
              ##  ##  ##   # ##  ###  ##    ##   ##   ##  ##  ##
               ##### ####### ##   ## ####  ####  ##   ## #######

                             [ Genital Readme ]
                             Bart Trzynadlowski
 

This is the documentation for Genital Version 0.3, read it. You should view it
with MS-DOS Editor. Genital is public domain software, I claim absolutely no
responsibility for it. See changes.txt for the change history.
        Feedback is appreciated provided that it is useful. I trust that you
know what is considered appropriate and what isn't. Please read this document
before emailing me, your question will most likely be answered here.
Email: trzy@powernet.net. 


[ Table of Contents ]

        0. About
        1. What You Will Need
        2. Installing and Building
        3. How to Work It
        4. Frequently Asked Questions
        5. Features
        6. Command Line
        7. Special Thanks
        8. Conclusion


[ 0. About ]

Genital is a Sega Genesis/MegaDrive game console emulator for use on Pentium-
equipped DOS PCs. Understand right now that it is not very good, it is still
in a very early stage of development. 
        The Starscream 68000 emulator is courtesy of Neill Corlett. The RAZE
Z80 emulator is courtesy of Richard Mitton. The rest was written by me in C
and assembly using DJGPP and NASM. Thanks go out to everyone who helped make
Genital a reality (see section 7)!


[ 1. What You Will Need ]

You need a Pentium-based PC, DOS, and about 8MB of RAM to run the binary. Mode
0x13 is used by default, any VGA can handle this. A mouse is required for
emulating the Menacer, the Microsoft Mouse Driver must also be installed.
        To compile it, get DJGPP v2, NASM v0.98, Starscream v0.26a or newer,
and RAZE v1.02 or better.

        DJGPP:          http://www.delorie.com/djgpp
        NASM:           http://www.web-sites.co.uk/nasm
        Starscream:     http://www4.ncsu.edu/~nscorlet
        RAZE:           http://www.rainemu.com/raze

If you cannot find the required components at the URLs I have listed, there is
nothing I can do about it.


[ 2. Installing and Building ]

Assuming Genital came in a ZIP archive, simply unzip it. You should have a
genital.exe and you can run it right away.

The source code is in the source.zip file.

If you want to build Genital yourself, make sure you have all the required
tools installed. Make sure that Starscream is in the STAR subdirectory and
RAZE is in the RAZE subdirectory.
        Then, simply run make. It should build without any errors. The only
targets are "dos" which makes Genital, and "clean" which removes the object
files.

By default, Genital does not include the Starscream debugger. If you want to
build a version with debugger support, place cpudebug.c and cpudebug.h in
the STAR subdirectory, #define STARSCREAM_DEBUG in 68k.c, modify the Makefile
appropriately, and build it.


[ 3. How to Work It ]

Simply run Genital to get a list of options; see the "Command Line" section
for more information on the different options.
        The ROM path may be specified anywhere on the command line. Genital
will take the first unrecognized or unprocessed argument as the ROM. The only
exceptions are video mode options or country options (-modex, -usa, etc.) --
these must be specified after the ROM. SMD and BIN ROMs are acceptable.
Options can be specified in any order but some have priority over others,
check genital.c's main() to see how this works.

For those of you that find Genital too fast, you should use the -vsync option
to sync Genital to the VGA refresh rate, it usually ends up running like a
real Genesis.
        If your computer is too slow, you will want to avoid -vsync and use
frameskipping.

The controls are not redefinable, they are as follows:

        Key:                    Action:
        Up arrow                Up
        Down arrow              Down 
        Left arrow              Left 
        Right arrow             Right 
        A                       A
        S                       B
        D                       C
        Enter                   Start
        Tab                     Reset 68000 CPU
        Caps Lock               Reset Z80
        + (numpad)              Increment frameskip value (can't go above 20)
        - (numpad)              Decrement frameskip (can't go below 0)
        F1                      Toggle vsync
        F2                      Toggle priority emulation
        F3                      Toggle horizontal interrupts
        F4                      Toggle sprite limiting
        F5                      Save state (Genecyst format)
        F6                      Toggle Z80 emulation
        F7                      Load state
        F11                     320x200 Mode 0x13 resolution
        F12                     320x240 ModeX resolution
        0-9                     Select save slot (.gs0-.gs9)        
        Escape                  Quit
        `                       Debugger (if compiled w/ debugger support)

Save state recovery is pretty bad sometimes, graphics can become distorted.
I'm pretty sure this is because the locations of some important info (status
register, etc.) in GST files is still unknown. Sound does not recover properly
either in other emulators.
        The debugger is simply the Starscream interactive debugger. Once in
it, type ? for help or q to quit. It is only useful for looking at 68K code,
it doesn't support Genesis-specific features. I'll be sure to include a useful
debugger if I write my own 68K emulator someday. 

Try fiddling with the command line options if a game doesn't work or freezes
at some point. Usually a -z80 will fix many games that don't run otherwise,
such as Flashback. Please read the FAQ! 

If you do not force a certain Sega Genesis model to be emulated (USA, Europe,
or Japan) then Genital will attempt to auto-detect which model should be used.
        The auto-detect code will first look to see if the game will work on
US systems, if it does then Genital emulates a US Genesis. Otherwise it checks
for European compatibility, and finally for Japan. If none are found, then US
is the default. If auto-detect fails, you may force a model of your choice.


[ 4. Frequently Asked Questions ]

Q: Why doesn't my favorite game work?
A: Genital is still an early emulator and lacks many features that make other
   emulators as good as they are. If you want something emulated, send me info
   on how to do it or do it yourself and send me the changes.
        Try enabling Z80 emulation with -z80 to see if it helps. Often times
   it does -- Mortal Kombat 2, Bubsy, Flashback, etc. Horizontal interrupts
   are also a big cause of compatibility issues. Try using the -hint command
   line option and see if things work better. Chuck Rock 2 and Michael
   Jackson's Moonwalker are examples of games that require h-ints.

Q: Why do some games freeze?
A: Again, it could be a feature Genital lacks. In my experimentation, I have
   found that the most likely cause is the Z80 emulation or horizontal
   interrupts. Try enabling the Z80 or h-ints and see what happens.

Q: Loading save states screws up the graphics and sound, what gives?
A: Save state recovery is not perfect for some reason. An example of this
   would be in Sonic and Sonic 2, where the little Sonic icon in the bottom
   left gets screwed up for no apparent reason. This is most likely because
   the locations of certain information (VDP status register, etc.) within the
   GST save state file is unknown.
        When loading save states in Genecyst or DGen that were created with
   Genital you will notice that sound recovery is very bad. This is mainly
   because no sound-related information (aside from Z80 registers and RAM) is
   saved.

Q: I thought you added Interlace 2 support... why doesn't Sonic 2's 2-player
   mode work?
A: I'm fairly certain it is a non-VDP-related bug. Try the censor_3.bin demo
   to see Interlace 2 in action. Compare it running on Genital with it running
   on Genecyst.

Q: Why is the screen cut off?
A: You are running in 320x200 resolution. The Genesis uses a 320x224 display,
   try using 320x240 (-modex option.)

Q: Why is 320x240 so slow?
A: The ModeX blitter isn't me at my finest. ModeX is planar and slow by nature
   since it is more complex than a linear mode like Mode 0x13.

Q: Why are there only 2 video modes? Where's the EAGLE filter? Interpolation?
   Sixteen-bit color depth? Palette raster effects?
A: Gimme a break! I don't have the time nor the dedication to add all this
   stuff. You are welcome to submit code though.

Q: What does the future hold in store for Genital? Will we see SegaCD, 32X,
   or SVP emulation?
A: I hope to rewrite Genital and have ports for several different OSes (DOS,
   Win32 and possibly UNIX/X, BeOS) in the same source tree. As for emulation
   of the SegaCD, 32X, and SVP... maybe. No promises.

Q: Where did you get all the information required to write Genital?
A: Try EPR: http://www.classicgaming.com/epr
   Eidolon's Inn: http://eidolon.psp.net (check Eidolon's Tavern too!)
   Also, much of it was thanks to Dave (of DGen -- www.dtmnt.com), Joe Groff
   (DGen/SDL), Charles Mac Donald (MekaDrive), Flavio (Sega hacking legend),
   ATani (SegaEMU, Generator32, Genital32, MCHE32), and other sources.


[ 5. Features ]

Genital is not far along in development, so the features list isn't that
exciting.

        CPU: 68000
                - Starscream 680x0 emulation library by Neill Corlett
                  (corlett@elwha.nrrc.ncsu.edu)
                - 64KB RAM
                - 4MB ROM
                - Nifty CPU abstraction layer
        VDP: VDP 315-5313
                - VRAM writes and reads
                - CRAM word (and longword) writes and reads
                - VSRAM word (and longword) writes and reads
                - Data port, control port, status port
                - Registers
                - DMA (partially, buggy)
                - HV counter (inaccurate)
                - Vertical interrupts
                - Horizontal scrolling (full, cell, line)
                - Vertical scrolling (full, each 2 cell)
                - Scroll A, Scroll B, Window (buggy)
                - Sprites
                - Sprite limiting (wrong and buggy)
                - H40 and H32 cell modes
                - Non-Interlace and Interlace video modes
        I/O:
                - Version port 
                - Control pad #1
                - Menacer (partially)
        Z80:
                - RAZE Z80 core by Richard Mitton (richard.mitton@bigfoot.com)
                - Z80 RAM
                - Bank register
                - Z80 reset, BUSREQ
        Sound: FM, PSG, DAC
                - Not emulated
        Misc:
                - Supports US, European, or Japanese systems

Some things I still want to do are:

        CPU:
                - Write my own 68K core
                - Add more CPU cores
        VDP:
                - Fix the DMA
                - Fix the Window layer
                - Fix the sprite limiting
                - Implement raster effects (especially palette based)
        I/O:
                - Add control pad 2
                - Add redefinable keys
                - Allow for joystick/gamepad support
        Z80:
                - Very buggy and inaccurate
        Sound:
                - Emulate it
        Misc:               
                - Add more options
                - Port to Win32 and/or UNIX/X11
                - Add support for 32X/Sega CD or SVP (maybe)

I realize the structure of my code is ugly. I will rewrite Genital sometime
in the near future -- probably with multiple-OS support.


[ 6. Command Line ]

The command line options are as follows:

        -?              Show help text
        -h              Show help text
        -info           Show information from the cartridge header of the ROM
                        that was specified
        -dump           Dumps the RAM, VRAM, CRAM, and VSRAM to RAM.OUT,
                        VRAM.OUT, CRAM.OUT, and VSRAM.OUT. These are images of
                        the given memory areas at the moment you quit Genital.
                        All data is in Motorola (big endian) format. The CRAM
                        dump is in big endian format also, unlike Genecyst's.
        -gen68k         Use Genital's 68000 emulator. It doesn't really do
                        anything yet, so don't use it                       
        -star           Use the Starscream CPU emulator (default)
        -raze           Use the RAZE Z80 emulator (default, only choice)
        -fskip #        Skip # of frames before drawing. Sacrifices smoothness
                        for speed. Values less than 0 are ignored and the
                        setting becomes 0
        -vsync          Waits for vsync period, this can be used to throttle
                        the speed on fast systems
        -mode13         Use the Mode 0x13 resolution: 320x200 linear. Part of
                        the bottom extremity of the screen is not visible, but
                        this is by far the fastest video mode
        -modex          Use the ModeX 320x240 planar resolution. Now the whole
                        screen is visible but at the expense of performance.
                        Try to avoid this, it is very slow
        -usa            Emulates an American Sega Genesis system 
        -europe         Emulates a European Sega MegaDrive system
        -japan          Emulates a Japanese Sega MegaDrive system
        -z80            Emulate the Z80. By default this is off since it is
                        still buggy and many games freeze because of it. Games
                        like Flashback require this option.
        -hint           Allow horizontal interrupts. Games use these for
                        raster effects. It is a bit inaccurate, and an hblank
                        kludge that prevented some games (Vectorman) from
                        running has been moved to the h-interrupt code; thus
                        it is off by default because it does more harm than
                        good for a few titles
        -menacer        Emulates the Menacer via the mouse. If you aren't
                        planning on using Menacer support, leave this option
                        out, it does cause a slight speed hit.
        -mrbtn #        Specify the hexadecimal value to return to the Genesis
                        whenever a mouse button is clicked during Menacer
                        emulation. The default is 8 which is the Pause button.
                        Do not use 0x, h, or $ markers
        -nopri          No priorities between the Scroll layers and sprites.
                        This will cause a minor speed increase on slower
                        machines while sacrificing graphics accuracy
        -nosprlimit     Disables sprite limiting. Although sprite limiting is
                        still imperfect, I feel it is good enough to leave on
                        by default. For sprite-intensive games such as Contra
                        or Gunstar Heroes, you will want to use this option to
                        turn it off. This option also turns off sprite masking


[ 7. Special Thanks ]

Many people have contributed in one way or another to this project, without
their help, Genital would never have become a reality. Here they are, in no
particular order:
        
        - Dave: Tons of tech info, and for DGen.
        - Joe Groff: Tech info, DGen/SDL.
        - Charles Mac Donald: Loads more information, especially on scrolling,
          sprite masking, the Window layer, the Menacer, and much, much more!
        - Flavio, ATani: Z80 information, and other stuff
        - Delta: For the enthusiasm and encouragement. Get Pretendo, a great
          NES emulator, now at http://www.pretendo.org
        - Stephane Dallongeville: Info on sprite limiting and 68K timing.
        - Christian Schiller (Eidolon): Go visit http://www.eidolons-inn.de
          and be sure to stop by Eidolon's Tavern!
        - Contributors to the Genesis Programming FAQ
        - Sega: For creating the Genesis and being the best video game company
          out there! Nintendo and Sony suck!      
        - You and everyone else I forgot: Thanks a lot!


[ 8. Conclusion ]

Contributions in any useful manifestation are more than welcome. Get in touch
with me, but please ask before sending files.

        Email:  trzy@powernet.net
        URL:    http://www.powernet.net/~trzy

I try my best to keep this project open. Hopefully people will benefit from
this :) See you next time!                                


