Generator
Generator is a platform independent sega mega drive / genesis
emulator, this is the documentation for the console version (svgalib,
dos) version 0.33 and later.
-
Generator is open source, so the source code is available for you to
download and compile yourself. Unless you are a developer with a need to
do this, or you have a system that doesn't have a pre-compiled binary, I
would advise against this route. There are a number of #defines in the
source that you have to set correctly for your processor/os and lots of
tweaks that can be done in order to get Generator working optimumly.
The source is available at
http://www.squish.net/generator/source.html.
-
These versions of Generator are available:
-
Prerequisites
Generator uses svgalib to run under Linux. You will need to install
svgalib first. If you use debian, you will probably want package
svgalibg1, but don't quote me on that.
For DOS, since it has direct access to SVGA memory anyway, you don't
need anything except the binary release.
Of course, you also need some ROMs. The console does not have any
proprietary BIOS so there is no additional code to find. To get the ROMs
you need to have a legal copy of the cartridge and a cartridge copier. The
copier will then save the ROM from the cartridge to disk.
Setting up svgalib
This is the most difficult bit in getting Generator to work under Linux.
The svgalib configuration file is at /etc/vga/libvga.config, and you will
need to edit it so that svgalib knows about your graphics card.
My advice is to use the VESA driver, I've never had much luck using the
other drivers for a specific card, and most modern video cards have good
VESA support. This means you should load your libvga.config file and
comment-in the line 'chipset VESA' and comment-out all other chipset lines.
Recent svgalibs have mode lines that you can insert, I've never had any
need for these lines, the vesa bios is supposed to do all this for you.
Generator requires 640x480 screen resolution at either 15 or 16 bit.
-
Games are stored as ROM files, so-called because they are copies of the
ROM (read only memory) area of the original cartridge.
Place the ROM name on the command line after any command line parameters.
Generator supports both .rom and .smd (interleaved) formats. It will
automatically detect the format. Although Generator ignores the extension
of the file, if it does not match the detected format a warning is
displayed.
If the ROM identifies itself as for europe and not for usa or japan then
PAL mode will be automatically selected.
Generator will report information on the game it has loaded in this
format:
Loaded 'Sonic The Hedgehog'/'Sonic The Hedgehog' (00001009-00 264A JUE)
The first name is known as the domestic name, and the second is the overseas
name. This is from the perspective of Japan.
The three items in brackets are: version, checksum and country information,
respectively. The checksum is calculated by Generator - if it does not
match with the checksum in the ROM header a warning is emitted. The country
information is a set of letters:
J = Japan
U = USA
E = Europe
It may also be a single hex digit which represents a new-style country
code.
-
- -v <verbose level>
Generator has many levels of logging:
0 - REQUEST (unmaskable)
1 - CRITICAL
2 - NORMAL (default)
3 - VERBOSE
4 - USER
5+ are debugging levels
As well as being able to select the log level at run-time, log levels
can also be compiled out. By default only 0-4 are compiled in.
- -l <sound latency>
As emulation is processor intensive, many systems are not able to
emulate the console at 100%. If an emulator can't keep up, the first
thing you'll notice is breaks in sound and a slow down of the game
speed. Generator has been written to try and avoid breaks in sound
by detecting when it will run out of sound data and cutting corners
in the video output.
The sound latency option is a number indicating how many video fields
worth of sound data it should try and keep buffered in memory. A
video field is 1/50th or 1/60th of a second depending on whether the
game is PAL or NTSC.
When the amount of sound data in the buffer goes above the threshold,
Generator will plot the next video frame. When the amount of sound
data in the buffer goes below the threshold, Generator will not plot
the next video frame, so that it can 'catch up' (plotting involves
talking to your video card, which involves talking on the slow PCI/AGP
bus, so skipping a frame of video saves a lot of time).
The default value is 5, which equates to an 83ms sound latency.
If you have a fast computer and you can notice the delay in sound,
try reducing the amount. Reducing to 0 is a bad idea, it means if your
computer can't keep up for just one frame you will get a sound click.
If you have a slow computer, you can increase this value - try 10
in combination with 20 fragments - i.e. -l 15 -f 20, but remember,
the larger the value of -l the bigger the latency, and you'll start
to notice the time lag.
- -f <sound fragments>
This sets the number of sound buffer fragments. Think of -l as
the minimum number of frames of sound Generator should try and buffer, and
-f as the maximum number of frames of sound Generator can buffer, and
you'll be ok :)
- -s
The -s flag will save the ROM and exit. The saved ROM will have been
converted to linear (as opposed to interleaved .smd) format, and will
be saved with filename '<overseas> (<crc>-<country>)',
e.g.:
Sonic The Hedgehog (264A-JUE)
The save will not overwrite any existing files - that is an error.
- -d <work dir>
The -d option tells Generator where to save or load files that
it uses. Typically this is for save state files, but also affects the
-s option. See the save state section for information on the
files that are saved.
- -i <interlace mode>
Effects how the full-screen mode de-interlaces interlaced screens,
can be one of: bob, weave or weave-filter. See the
section Interlace for more details on this option.
- -j <pad1>,<pad2>
This sets the input devices for each joypad. The default is
key0,none. The options are:
- key0
- Main keyboard (buttons=ASD d-pad=arrows)
- key1
- Left side of keyboard (buttons=ZXC d-pad=DGRF)
- key2
- Right side of keyboard (buttons=,./ d-pad=arrows)
- joy0
- Joystick 0
- joy1
- Joystick 1
- none
- none
-
The keys below are for a single keyboard player, see the -j option
to switch to joypad or left/right side of keyboard.
- D-Pad
- The directional pad is simply the arrow keys.
- Buttons
- The three buttons A, B and C can be accessed using either A, B and C or
A, S and D.
- Quit
- To quit, press ESCAPE.
- Function keys
- F1 - License
- This shows you the license under which you are using Generator.
- F2 - Save/load state
- This allows you to save your position to
disk (aka cheating).
- F4 - Save image
- This allows you to save a raw (3 bytes per pixel, red, green, blue)
image. You can save either a full-screen (640x480) image or just the game
screen (the size varies, it will tell you when it saves).
Use the pnm utils to convert the raw file. e.g.
rawtoppm 640 480 sonic2.ss1 | pnmscale -xscale 0.3
-yscale 0.3 | pnmtopng >sonic2a.png
- F5 - Toggle info
- By default the Generator logo, key bindings, date/time are displayed on
the screen. This will turn them off.
- F6 = Toggle video
- This will toggle between PAL and NTSC emulation. Many games will not
function correctly if you choose the wrong one. When Generator loads
a ROM for the first time it will automatically select PAL if the ROM
identified itself as for Europe. Since this option changes the framerate,
number of clocks in different parts of the display, etc. you should generally
reset the cartridge (F12) after changing this.
- F7 - Toggle country
- The ROM can ask the system what country the console was built for. This
allows you to change the option Generator will report to the ROM. By
default this is set to Overseas (USA/Europe) rather than Domestic (Japan).
Some games will change their language or title depending on this option.
Generally you should reset the cartridge (F12) after changing this.
- F8 - Toggle plotter
- Generator has two video plotters. The first is a fully-fledged line
based plotter which supports all the features of the console's video
processor. The second is a cell-based plotter which only supports the
abilities of the video processor that can be done on a cell-by-cell
basis (a cell is an 8x8 pixel block). The cell-based plotter is much
faster - you should use this plotter if your machine isn't quite fast
enough or if the ROM doesn't appear to need the line-based plotter's
features. There are some things that Generator can't emulate without being
in the line-based plotter mode, but these things are rarely used, so
typically you do not need to worry about upsetting a game by changing this
option as on the whole this is just changing your display.
- F9 - Toggle vsync
- Generator can synchronise itself to the video card's refresh signal if
you desire. This is effectively introducing a wait state into Generator's
emulation and wastes time. On the other hand, without the vsync the
video card could be displaying a mixture of the previous video frame and
the next, causing shearing on the screen. Also, some video cards do not
take kindly to omitting the vsync and actually pause or corrupt the
display, seemingly for no reason, every few seconds or so. If your
video card exhibits this behavior then you will want to turn vsyncs
on (some S3 cards do this).
- F10 - Full screen
- Turning on full screen means Generator has to plot 4 times as much data
as it had to before - this will be slower as this has to be transferred
over your PCI/AGP bus.
If full screen is on then 'Toggle info' (F5) can be used to display the
clock/fps at the bottom of the screen.
Full screen mode is the only way interlace can
be done properly.
- F12 - Hard/soft reset
- This performs a hard or soft reset. A hard reset is the same as
turning off the console and turning it back on again (useful if you change
the country or video type using F6 or F7). It will also reset your sound
system. A soft reset is the same as pressing the reset button on the
console. Technically this means the 68000 processor is reset but no other
sub-systems are.
-
Newer versions of Generator have the ability to save state to disk
in order to let you load and save your position during play. During game
you can press F2 followed by 1 to load and 2 to save. You will be
presented with 9 slots to save your game into.
These slots are per-game, so you can save up to 9 states for each
ROM in your collection. The save games are stored with the same
leafname but with the extension .gt<n> where n is the
slot number.
-
- I test generator on my P200 DOS machine and games are quite playable, so
if your machine is this sort of speed or faster, you shouldn't be having a
problem with speed. Machines that are P350 or higher will generally get
around 50-60fps.
- Sound is choppy
- This is unusual as Generator will dynamically drop frames until the
sound is not choppy. Try adding -l 15 -f 20 to the command line,
if it is still choppy, send me an email, I'd love to investigate.
- Half-second pauses every few seconds
- This happens on my built-in S3 graphics card on my laptop - it doesn't
like Generator not using vsyncs - turn them on (F9) and perhaps this will
solve the problem for you.
- Screen flickers every now and again
- Sometimes your monitor will look like it has lost sync every now and
again (perhaps every 10 seconds or so) - this is caused by Generator not
using vsyncs and is a problem with your video card not liking the page
flip occuring at a particular time. You will need to turn on vsyncs to
fix this (my GeForce MX card does this).
- Everything ok, just sooo slow
- Turn off the slow plotter in favour of the cell-based plotter. Make
sure you keep the defaults of vsyncs turned off and don't use full-screen
mode. If you feel Generator is still running too slow for you, send me an
email telling what you're experiencing.
- Generator exits for no reason
- Try turning up the verbosity in logging with -v 4. If that
still doesn't explain a mystery quit, please drop me an email with
details so that I can investigate (it's probably the cpu core
aborting, although I haven't seen this in a long time).
- Switching to and from X corrupts display
- svgalib and X do not work well together - recent versions of svgalib
will automatically switch out of X to run and switch back in to X when
completed (console output can be seen with CTRL-SHIFT-F8). However, under
no circumstance should you switch into X whilst Generator is running, this
will corrupt the screen. There is nothing that can be done about this.
My advice is always move to a text console before running Generator by
doing CTRL-SHIFT-F1 and move back to X when you have finished with
CTRL-SHIFT-F7 (the exact F key may be different on your machine).
-
Some games switch into interlace mode in order to have more
resolution. The best example of this is Sonic 2 two-player split-screen
mode. Generator supports this mode but needs to de-interlace the screen,
which is actually more complicated than it sounds.
An interlaced screen is one where the resolution is doubled, but
only half the screen is present in each field of video. There are
two methods of fixing this: bob and weave.
The bob de-interlacing technique is to interpolate the lines of
each field that don't exist, which basically involves doubling up the pixels
in the vertical direction of each field in order to make a frame. This
has the side-affect that the screen appears to bob up and down (hence
the name). When Generator is not in full-screen mode, and therefore
doesn't have the resolution to do anything else, it is basically using a
form of bobbing without the actual interpolating.
When in full-screen mode, Generator can use the weave
technique by combining the even and odd fields together to form a
complete frame. Unfortunately because each field is seperated in time
by a 60th of a second, this causes an effect known as combing where
there is motion.
To reduce combing Generator can use vertical filtering to smooth
out the combing effect, but this has the side effect of introducing a
perceived double image effect. This is normally a lot less
noticable than the combing, and is therefore the default.
Generator can't do this due to lack of computational time, but the
next step would be to do motion-adaptive de-interlacing which
switches between bob, weave and filtering depending on whether objects
are stationary or moving. This is what good DVD players do when
playing to non-interlacing devices (CRTs, plasma, projector, etc).
See the command line option -i to change the interlace
style.
-
There are already three ports of Generator to the Amiga, Mac and
Windows. If you would like to port Generator then, as it is open source,
you are of course free to do so; but, I will go beyond that and say I will
help you out. I'm always available at the end of an email. The other
porters are friendly guys too, so there's lots of help available from
people who have experience with endian issues, performance issues, etc.
-
If you have a bug report, either emulation wise or because Generator
doesn't work on your platform, send me an
email!
-
I have a to-do list (in my head) but if you don't tell me what you'd
like to see from Generator, then I won't know what is important to you. Please
drop me an email telling me what you miss from Generator.
-
Open source only works if you either contribute code or communicate your
support to the author. This documentation is being written because someone
told me they didn't think there was enough for Generator. So, if there's
something you don't like or could be better, don't sit there - tell me
about it!
|
