           _______                  _______              
          |       |.-----.--------.|       |.-----.-----.
          |   -   ||__ --|        ||   -   ||__ --|  -__|
          |_______||_____|__|__|__||_______||_____|_____|
           _______                  __         __              
          |    ___|.--------.--.--.|  |.---.-.|  |_.-----.----.
          |    ___||        |  |  ||  ||  _  ||   _|  _  |   _|
          |_______||__|__|__|_____||__||___._||____|_____|__|  
          Version 0.6.30 - Final release.                                                     



06 July 2005: Osmose 0.6.30 6th public and final release.
--------------------------------------------------------

Osmose is another Sega Master System 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, zlib, and uses Alessandro Scotti z80 
cpu core. Alessandro, is the author of the nice multi machine emulator 'Tickle'.
Rom decompression relies on Zlib and Gilles Vollant unzip package. Scale2x 
video Filter is based on Andrea Mazzoleni's algorithm.


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

Object      Oriented 
       S.m.s.         Emulator.
      
In brief it's an sms emulator encapsulated into C++ classes :-)

Status:
-------

The emulator development is now stopped. I'll be absent for at least one year 
starting from October 2005, with no possibilities to write a line of code (*cough*).
Writting this emu was really funny, especially with help of smspower guys. Osmose
is not perfect but it's a really decent Linux/Windows open source SMS emulator. 
I think Osmose's source code could help other emu coder or curious.

Features:
--------

-Good compatibility. At this stage, the emulator can run almost* all commercial 
 games and public demos, except games that relies on codemaster mapper, which work
 but does not have proper video mode emulated.
-SN76489 Sound is supported, but needs more work due to my bad knowledge in sound 
 coding :-)
-Zip or .SMS format support.
-Graphics filters: monochrom, tv, scale2x, bilinear (fullscreen option always available).
-Pad, Paddle emulation.
-PAL/NTSC Timing.
-Japanese/Export console.
-In game Screenshots, GFX rip, sound shot.
-Accurate auto-frameskip.
-Configurable keyboard configuration.

*Due to the great number of sms roms, games have not been deeply tested.


Usage:
------

./osmose rom_name.zip -tv
./osmose test.sms -nosound -fs -tv
./osmose crazy_game.zip -inifile my_conf.ini

Notes:
ROM name MUST be the first parameter.
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:
--------

    -paddle           emulates one axis paddle (mapped on mouse).
    -acceleration x.x paddle acceleration (0.1 to 5 default 0.5)
    -fs               run in fullscreen   (default: windowed).
    -jap              run as japanese sms (default: export).
    -exp              run as exported sms (default).
    -nosound          do not play sounds. (default: sound on).
    -cm               codemaster games mem. mapper (default: off). 
    -dp               use dark palette for screen emulation (default: off).
    -inifile          xxx use xxx as configuration file. 
    -fps              display fps in title bar.
    -pal              emulates PAL/SECAM video timing (default: NTSC).
    -monochrom        emulates B&W tv (default: off).
    -tv               emulates TV interleaves (default: off).
    -scale2x          scale2x filter implementation (default: off).
    -bilinear         bilinear filter (default: off).


Important notes: 

       -You can combine -tv/-monochrom/-scale2x with -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    :  LEFT ALT
PAD1 B    :  LEFT CONTROL
 
PAD2 UP   :  NUMPAD 5
PAD2 DOWN :  NUMPAD 2
PAD2 LEFT :  NUMPAD 1
PAD2 RIGHT:  NUMPAD 3
PAD2 A    :  n
PAD2 B    :  b

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

Important note concerning frame rate:
-------------------------------------

HUGE differences can be observed depending on your display options.

16bits display without special filter:
 - gives +- 502 fps on a 2Ghz Athlon running BlackBox window manager.
 - gives +- 450 fps on a 2Ghz Athlon running KDE window manager. 

16bits display with -scale2x option:
 - gives +- 228 fps on a 2Ghz Athlon running Black box window manager.
 - gives +- 210 fps on a 2Ghz Athlon running KDE window manager. 

24bits display without special filter:
 - gives +- 234 fps on a 2Ghz Athlon running BlackBox window manager.
 - gives +- 210 fps on a 2Ghz Athlon running KDE window manager. 
 
24bits display with -scale2x option:
 - gives +- 50 fps on a 2Ghz Athlon running BlackBox window manager.
 - gives +- 49 fps on a 2Ghz Athlon running KDE window manager. 

8 bits modes are slower than 16bits, but faster than 24bits.
15 bits mode does render wrong color (due to SDL unsupported pixel format?).
Fullscreen mode are quicker than windowed mode.
 
Building Osmose from sources:
-----------------------------

Assuming your system is correctly configured, with SDL library,
just type: make

Important note concerning some ROMS:
-------------------------------------

Back to the Future 3 (UE) [!].zip ->  option -pal required.
Impossible Mission (UE) [!].zip	  ->  option -pal required.
Predator 2 (UE) [!].zip	          ->  option -pal required.
Woody Pop (J) [!].zip		  ->  option -paddle -jap required.
Megumi Rescue (J) [!].zip         ->  option -paddle -jap required.
AlexKid Bmx Trial		  ->  option -paddle -jap required.


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 CPU core, and nice information about it.
 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 it's unzip package based on zlib.

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

-Andrea Mazzoleni, for providing scale2x video filter algorithm.
 Web site: http://scale2x.sourceforge.net/
 
-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                              |
--------------------------------------------------------------------
