           _______                  _______
          |       |.-----.--------.|       |.-----.-----.
          |   -   ||__ --|        ||   -   ||__ --|  -__|
          |_______||_____|__|__|__||_______||_____|_____|
           _______                  __         __
          |    ___|.--------.--.--.|  |.---.-.|  |_.-----.----.
          |    ___||        |  |  ||  ||  _  ||   _|  _  |   _|
          |_______||__|__|__|_____||__||___._||____|_____|__|
       Version 0.9.1 - 13th public release, written by Bruno Vedder.


Osmose means:
-------------

Object      Oriented
       S.m.s.         Emulator.

In brief it's an Sega Master System / Game Gear emulator encapsulated into C++
classes :-)


10 December 2009:  Osmose-0-9-2 14th public release.
--------------------------------------------------

Osmose is another Sega Master System / Gamegear emulator. The emulator is
released as open source project, under GPL license. For more information just
read the file 'license.txt'.

The emulator relies on SDL library and Zlib and Gilles Vollant unzip package and
OpenGL 3D graphic library.

What's new:
-----------
-Fix a bug that prevent 64bits build reading configuration file correctly.
 As side effect, keyboard was unusable in Osmose 64bits.
-Remove unused code (OsmoseConfiguration::findSDLKeySym); 
-Add possibility to change button assignement for Joystick.
-Fix a bug in configuration file parsing.
-Now uses a color terminal for reports:
 Makefile  -DUSE_ISO_IEC_6429 option.
 
Features:
--------

-SMS: Good compatibility. At this stage, the emulator can run* 96% of commercial
 games and public demos, except games that relies on codemaster mapper, which
 work  but does not have proper video mode emulated.
-Game Gear: Good compatibility. At this stage, the emulator can run 98.0%* of
 game gear ROMS.
-SN76489 Sound is supported, but needs more work on noise register.
-support. for .zip .sms  and .gg format.
-Video filters: bilinear or nearest neighbour (default)
-Pad(keyboard or joystick mapped), Sport Paddle (mouse mapped) emulation.
-PAL/NTSC Timing.
-Japanese/Export console.
-In game Screenshots, GFX rip, sound shot.
-Accurate auto-frameskip.
-Configurable keyboard configuration.
-Joystick support, congigurable button assignement.

*Due to the huge number of game gear/sms (around 1300) roms, games have not been
deeply tested.

Usage:
------

./osmose rom_name.zip
./osmose test.sms -nosound -fs
./osmose crazy_game.gg -inifile my_conf.ini
./osmose -fps -nosound asterix.zip

Notes:
ROM name can be everywhere on the commandline.
If you are not easy with command line, maybe should you use 'wxosmose', which
is a graphical frontend for Osmose. It's written by Bertram, thanks to him :-)


Options:
--------

Osmose > 0-8-0 implements embedded database, with game that needs specific
options to turn them on autmatically. User don't need to use -cm, -km -pal
or -jap options. But i don't own all roms, that why these option are still
usable from command line.

    -paddle           Emulates one axis paddle (mapped on mouse).
    -joy              Use joystick as input device, instead of keyboard.
    -tracejoy         Output trace on joystick button press to help with configuration (default off).
    -acceleration x.x Paddle acceleration (0.1 to 5 default 0.5)
    -fs               Run in fullscreen   (default: windowed).
    -bilinear         Bilinear filtering on screen (default: nearest neighbour)
    -nosound          Do not play sounds. (default: sound on).
    -dp               Use dark palette for screen emulation (default: off).
    -inifile xxx      Use xxx as configuration file (default: none).
    -fps              Display fps in title bar (default: off).
    -cm               Use codemaster games mem. mapper (default: off). 
    -km               Use korean games mem. mapper (default: off). 
    -irqhack          Enable irq hack (specific rom option. default: off).
    -pal              Emulates PAL/SECAM video timing (default: NTSC).
    -jap              Run as japanese machine (default: exp).
    -exp              Run as exported machine (already default).


Important notes:

       -You can combine -bilinear and  -fs (fullscreen).
       -If your config file name contains some spaces chars, use -inifile
        like this: -inifile "Name with space.txt" (with double quotes).

Default Keys:
-------------

SOUNDSHOT :  F1 (start/stop audio recording (22050kz 16bits/mono into wav file)
             Be carefull, wave file grows about 2.58 Mo/minute.
PAUSE     :  p
SCREENSHOT:  F2
TILESHOT  :  F3  (this will rip gfx used at this moment).
QUIT      :  ESCAPE
[DEBUGGER : d, if Osmose compiled with builtin debugger]

PAD1 UP   :  UP
PAD1 DOWN :  DOWN
PAD1 LEFT :  LEFT
PAD1 RIGHT:  RIGHT
PAD1 A    :  w
PAD1 B    :  v

PAD2 UP   :  NUMPAD 5
PAD2 DOWN :  NUMPAD 2
PAD2 LEFT :  NUMPAD 1
PAD2 RIGHT:  NUMPAD 3
PAD2 A    :  j
PAD2 B    :  m

JOY1_BUTTON_A		= BUTTON0
JOY1_BUTTON_B		= BUTTON1
JOY1_BUTTON_SELECT	= BUTTON2

ENTER     :  Game Gear start button.

KEYPAD   +:  Increment save state slot.
KEYPAD   -:  Decrement save state slot.
F11       :  Load a state from current slot.
F12       :  Save a state in current slot.

Keyboard configuration:
-----------------------

If you dislike Osmose's keyboard configuration, you can change it,
by providing a file with new configuration. When run, osmose will create
a osmose.ini file with default configuration. Under Linux/Unix this file
is created in .osmose of user directory. You can specify other configuration
file with '-inifile my_config.txt' option

Joystick Button assignement:
----------------------------

A few users request to be able to change joystick buttons assignment.
It's now possible to do it. All You have to to is to remove the file
 .osmose/osmose.ini in your home directory. Restarting Osmose with a working
 rom will recreate the file, with the following items:
 
-JOY1_BUTTON_A     = BUTTON0 	(assign BUTTON0 to SMS Pad button A).
-JOY1_BUTTON_B     = BUTTON1	(assign BUTTON1 to SMS Pad button B).
-JOY1_BUTTON_SELECT = BUTTON2	(assign BUTTON0 to SMS Pad button Start/Select).

This is the default configuration. If your not happy with this, you can change
it by providing a different value : BUTTON0 to BUTTON15. If your joystick has
more than 16 buttons, then it's a keyboard :)

Osmose has no way to guess which value is which button on your joystick. There
are many differents ones, with not coherent values. You can see the value
associated to your buttons, by launching Osmose with a valid ROM and the 
-tracejoy option. Then on each button press event, Osmose will output the
corresponding 'BUTTONxx'. You can then use it to setup your configuration file.
This is a bit boring, but you need to do it only once. 


Sound shots, tiles rip and screenshots, Battery backed ram:
---------------------------------------

Osmose save these files in the corresponding folders under user home directory:
.osmose/snd
.osmose/tiles
.osmose/screen
.osmose/bbr
.osmose/saves

If the emulator doesn't find osmose.ini, it will generate a new one, with
these four folders. Without these folders no save are possible. If Osmose
can't create them do it manually !

To force osmose to create these directory again, simply delete osmose.ini
and launch a ROM.

Building Osmose from sources:
-----------------------------

Assuming your system is correctly configured, with :
SDL, zlib, and OpenGL (header + shared object)

just type: make from the source directory.

Thanks to:
----------
-Enik, for bug reports, beta testing, and sound comments.

-Bertram, for the Osmose's Frontend, based on wxWidgets, and bug reports.

-Alessandro Scotti, for it's Z80 CPU core used in earlier version of Osmose.
 Osmose now uses it's own cpu core. 
 Web site: http://ascotti.org/programming/tickle/tickle.htm

-Charles MacDonald, for his excellent technical documentation on the SMS
 hardware.
 Web site: http://cgfm2.emuviews.com/

-SMS Power dev forum, for help about a lot of SMS parts, and nice resources.
 Web site: http://www.smspower.org/

-Zlib home page for their excellent library.
 Web site: http://www.gzip.org/zlib

-Gilles Vollant for his unzip package based on zlib.

-emu-france.com for free and publicity free web hosting.
 Web site: http://emu-france.com

-Sound beta tester from 6t-web.
 Web site: http://6t-web.com

Feedback for bugs, problems or features requests are obiously welcome.

--------------------------------------------------------------------
|  Contact: osmose_emulator@yahoo.fr                               |
|  Site   : http://bcz.emu-france.com                              |
--------------------------------------------------------------------
