======================
Calypso Beta Build 011
31-10-1999
======================

----------------------
 What is Calypso?
----------------------

Calypso is a Sega Master System II emulator.
It executes ROMs in a PC as if they it were in the console itself, this
way you can play SMS programs in your PC.

Calypso has been developed by Jose Manual Delgado Mendinueta.  During
the development I've had help from the Master Gear, Massage and Darcnes
source codes, as from diverse Z80 engines as Marat Fayzullin's, Marcel
De Koegel's and Neil Bradley's.  I've used DJGPP 2.02 with Allegro 3.11.

Calypso isn't only an emulator.  It includes a powerful graphic debugger,
that lets us execute the SMS software one instruction at a time.

----------------------
 News
----------------------

Hello again. Here we are with another version, full of newness.

First, and for people suggestions, the emulator includes support to read
ZIP archives (finally). All was extracted from ZLIB library.

In order to save some space, the debugger now uses the Raze's engine, so Marat's
engine won't be included in the .EXE. However, I still use Marat's disassembler.

Another suggestion from users was translating Calypso to English and Portuguese.
I have added MultiMamelang tool. With this tool you will be able to translate
the emulator to any language without programming knowledge. The parameter
-res was included for users suggestions also. Thanks to Vicente Aguilar.

I am still working in the sound. I have addedd Richard Mitton's engine, but
I am afraid it doesn't work alright with recent soundcards because it is
based on Adlib. It has the same problems as my old Adlib engine, but Mitton's
is better because it emulates the noise.

The render has now a new technique, -scanlines. Thanks to Charles Mac Donald
for the idea of how to do it. Now only available in the version without GUI.

The emulator won't be updated since February because of the exams. I hope
you will enjoy this version.

THIS IS A PROOF VERSION. IT INCLUDES A LOT OF THINGS THAT AREN'T FULLY
IMPLEMENTED SO SOME RARE THINGS MAY HAPPEN.

NOTE: MAMELANG SUPPORT IS IN PROOF. IN THE NEXT VERSION I WILL RELEASE A
FILE TO MAKE IT USEFULL.

THE SOURCE OF GENESIS EMULATION IS A PROOF TOO. IF YOU LOAD A ROM,
NOTHING SHOULD HAPPEN BUT THE COMPUTER MAY HANG OCASIONALLY.

----------------------
 Revisions
----------------------

Build 011:
 -Now you can load ROMs directly from .ZIP archives.
 -Now you can translate Calypso to any language with MameLANG. Thanks
  to Vicente Aguilar.
 -Parameter -res added. You can use the resolution you want.
 -A Megadrive/Genesis debugger added. You can enter with -d, the same as the
  other one. All the keys are compatible. ---- It doesn't work perfectly at
  this moment. !!!
 -Parameter -snd added. Thanks to Richard Mitton.
 -Added a little osciloscope. It doesn't work perfectly. Key Y.
 -Parameter -scanlines added. At the moment only in the version without GUI.
 -GUI: A lot of changes. Look them out by yourself.
 -GUI: Fixed a bug of windows priority.
 -GUI: Now the text of the windows has colours. The colour of the windows
  has changed too.
 -Debugger: Now uses Raze Z80's engine. Bye to Marat's Fauzullin's one.

Build 010:
 -It now has digital sound synthesis.  Thanks to Nyef and SMS Dev.
 -Programmed a voice skipper for Adlib sound.
 -Incorporated a small scheduler.  Now you can see what the emulator spends
  its time on.  Key G
 -Added a left column crop (leftmask) for Game Gear.  This is ideal to play
  BigGameGear games like Sonic and the like.  Key K.
 -Corrected a small bug with the GameGear BigGameGear crop.
 -Debugger: Enhanced some options, like watching the tile numbers on screen.
  (key I)
 -Debugger: Breakpoints support.  Up to 16 breakpoints.  Key Y
 -Debugger: A new option lets you advance one scanline. Key H
 -A GUI.  Read the news section.
 -Render: corrected a BUG related to Verticla Interrupt generation.

Build 009:
 -Now if the emulator doesn't find an Adlib sound card lets you run the ROM
  (but with no sound, of course), skipping the error. Silly bug.
 -Fixed a small bug in Gamma
 -Now the slots are viewed as in Nesticle.
 -New message font, looks like Nesticle's.
 -Support for gamegear games (but with BUGS) and debugger.  Dedicated to
  Charles Doty, so he can debug his demos correctly.
 -The Save games format has changed, to support Game Gear.
  Easy, you won't need to trash your old save games, because the new format
  is compatible with the older (or at least ir should be).
 -Added some keys that do cool things.
 -Render: corrected the bug that didn't let you see characters greater than
  448.  Now all VRAM goes in cache.  A bit of speed is lost.
 -Render: sprite render accelerated.  Now, the color 0 is used as transparent.
  This might not be right.
 -Render: At last a ZBuffer has been incorporated per cache so that the tiles
  are seen in front of the sprites.  A bit of speed is lost.
 -Debugger: new option to see the screen at a bigger size.
 -New keyboard handler

Build 008:
 -Added configuration file and command line options.  Now the changes will
  be saved inside the configuration file CALYPSO.INI which is also editable.
 -Added VSync support.
 -Several cosmetic changes and of minor importance in the code.
 -Added automatic frameskip.  At last.
 -Added a YM2413 skipper.  Now a lot more games work.
 -Added international support.  You can emulate a Japanese or European console.
 -The saved games bug was corrected.  There were pointers pointing not where
  they should, producing unexpected results.  I'm sorry, but you'll have to
  trash your old saved games, because the format is incompatible.
 -Added on screen messages.  What decent emulator doesn't have them?  :)
 -Added pause button emulator.
 -Added slots for saved games.  Now you can save up to 10 games per rom.
  Besides, the emulator doesn't give you an error when you try to load an
  nonexistent saved game.
 -Added a small debugger option.  Discover it for yourself.

Build 007:
 -Rewrote the VDP Engine from scratch.  It now uses methods like Tile Cache
  and other optimizations.  Right now it's entirely in C, but faster.  I'll
  write it in ASM later.  BUGS: it doesn't take in account if sprites are
  under characters (sprite priority), nor scroll in the first lines.
 -The emulator now uses the RAZE Z80 Engine, written in ASM, a lot faster
  than Marat's.
 -The old VDP engine is still used in the debugger.  I corrected a flaw that
  made the last column not to be viewed.

Build 006:
 -Corrected a small BUG in the VDP, relating to ScreenON.  Thanks to Zoop
 -Added frameskip support
 -Now the games are saved to a .pgc file with the same name as the ROM file,
  allowing one game per ROM, like in BrSMS.  DOES NOT WORK WELL SOMETIMES.
 -Partial sound emulation.  White noise is missing.  Besides, it's pretty
  bad and it may not work on all systems.
 -Although the emulator has not changed a lot on the outside, internally it
  has.  Now it no longer uses the LoopZ80() instruction, I'm now executing
  frame by frame, like in modern emulators.

Build 005:
 -Initial Version

----------------------
 Working on...
----------------------

 -Making it sound better (even more).
 -Enhance the VDP emulation.
 -FM synthesis, available in some consoles.
 -Other peripheral support, like the LightGun.
 -Joystick
 -Start 32X development.
 -Calypso for Windows95/98/NT.
 -Play on the Net.
 -Improve the docs.

----------------------
 How it works
----------------------

Run Calypso followed by the ROM you want to emulate.  Nothing harder than that.
GUI version is better. If you know how to use Callus, then you know using Calypso.

----------------------
 Emulator
----------------------


During the emulation, the monitor resolution is set to 320*200.
(you can change it with -res) 

The keys are:
cursors   ->      Pad control
Control   ->      Button A
Alt       ->      Button B
P         ->      Pause button
S         ->      Exit the emulator
R         ->      Reset
Q         ->      Increases gamma correction
A         ->      Decreases gamma correction
Z         ->      Saves the game on a file named x.pgc, x = ROM name    c = slot
X         ->      Loads the game from a file named x.pgc, x = ROM name  c = slot
E         ->      Increases frameskip
D         ->      Decreases frameskip
U         ->      Increases sound volume
J         ->      Decreases sound volume
T         ->      (Show : Hides) emulation data
V         ->      (Activates : Deactivates) VSync
0...9     ->      Changes the slot the saved games will be put.
I         ->      (Activates : Deactivates) sprite rendering
O         ->      (Activates : Deactivates) tiles (background) rendering
L         ->      (Activates : Deactivates) GameGear screen crop
K         ->      (Activates : Deactivates) left column crop
H         ->      Shows copyright info
G         ->      Scheduler: Shows how the processor spends its time
F         ->      (Show : Hide) Frames per second display
V         ->      (Activates : Deactivates) sound channel 1
B         ->      (Activates : Deactivates) sound channel 2
N         ->      (Activates : Deactivates) sound channel 3
M         ->      (Activates : Deactivates) sound channel 4 (white noise)
Y         ->      Osciloscope  

Gamma corrections is to adjust the color intensity. By default, the emulator
runs in auto frameskip mode.  In theory, in any computer you should get
50 vfps, and if the computer is fast enough, you should get 50 fps algo.  The
system is totally dinamic, that's the reason of the number dancing.  If you
have any problem, send me an email.

VSync means that the emulator waits until the beam from your monitor is 
off (returning to the beginning) to draw the screen.  With this you can
avoid those glitches that sometimes happen in the screen.  On the other hand,
you may lose some speed.


As you may know, the Game Gear is nothing but a SMS with a smaller screen (and
other small differences).  Calypso renders the GameGear screen as if it were
a SMS.  In most games this is ok, but in other games there are some graphic
glitches.  If you want to see the GameGear games as they were meant to,
activate the crop.  Cropping does nothing else than paint black the areas
that aren't seen in a real GameGear. The left column crop is necessary because
most of the horizontal scroll type games (Sonic and the like) use it. It's
present on the SMS, and as in the GG not, we have to emulate as an external
thing to the emulator.  The best thing is to experiment with it to see what
it does :).

The scheduler shows how does the emulator spends its time.  In my old Pentium
60 It's the same for Z80 and render, and a bit less BLIT and Sound (in the no
GUI version).  In my pentium III 450, 100% of the time it's in wait state :).
This means that it needs less than 1% to work, it's not that the scheduler is
Done wrong :).  In other computers it may vary.  It's updated every 2 seconds.

The digital sound includes white noise emulation, but for now it's not well
developed.  This is why it's turned off by default.  To turn it on, press M.
It's channel 4.


----------------------
 Debugger
----------------------

The debugger has information such as deassembly, Z80 registers, etc... that
won't be explained here.  If you want to find out more, grab the excellent
Richard Talbot documentation, available from SMS Power.

To access the debugger, you need to use -d as a parameter.

During debugging, the available keys are the following:

B         ->     Executes 1 instruction
G         ->     Executes 10 instructions
F         ->     Executes 100 instructions
V         ->     Executes 1,000 instructions
C         ->     Executes 10,000 instructions
X         ->     Executes 100,000 instructions
Z         ->     Executes 1,000,000 instructions
S         ->     Exits the integrated debugger
M xxxx    ->     Shows the Z80 RAM contents starting at address xxxx (hex)
N xxxx    ->     Shows the VRAM contents.
P xxxx    ->     Shows the PRAM contents.
D xxxx    ->     Disassembles starting at address xxxx
J xxxx    ->     Jumps to address xxxx
A         ->     Shows tiles
R xxxx    ->     Executes until address xxxx (useful for skipping LDIRs)
W         ->     Executes indefinitely until pressing E.  This is to play
                 up to a specific part and stop.
F1        ->     Resets the system (W)
U         ->     See the screen at a larger size
I         ->     See the tiles and their number in VRAM.  No Scroll.
Y         ->     Open the breakpoints window.
H         ->     Advances one scanline.

(W) means that it only works when in continuous execution mode (this means,
having pressed the W key).  The Caps Lock must be deactivated.  There are
commands that are activated upon key pressing, for others, you have to type
them down and press ENTER. In future versions I'll explain more deeply how the 
debugger works. Until then, the most interesting thing is to press W.  The 
controls do work, and remember that you can stop at any time with E to see the 
tiles, for example.

To see the breakpoints window press Y.  The active breakpoint appears in 
white. If you want to edit it, we use the arrows and type the hex address.  We
can move the value with the arrows.  To end, we press the left key until we
return to the first column.  To erase a breakpoint, press Q.  To exit, press S.
Once the breakpoints are set, the emulator stops when we press W (continuous 
mode) or if we choose to run a certain number of instructions.  To exit the 
breakpoints window, press S (as in all places).


---------------------------
 Command line parameters
---------------------------


-d          : Starts the integrated debugger instead of the emulator

-vsync      : Use vertical synchronization

-vol <nn>   : Sound volume to use

-gamma <nn> : Gamma to use in emulation

-jap        : Emulates a japanese console (it's european by default)

-euro       : Emulates an european console

-ntsc       : Emulates a NTSC console

-oldvdp     : Uses the old VDP engine.  Slow, but better.  If you care
              about the newer one BUGs (but faster), use this

-ds         : Uses digital sound synthesis instead of Adlib

-adlib      : Uses Adlib to emulate sound

-nosound    : Disables sound. Increases speed

-sndrate [22050-44100] : Specifying one of the two parameters, the sound
              samples frequency is chosen.  The more the frequency, better
              the quality, but it uses more CPU time

-scanlines  : Emulates the scanlines of the TV. Only in the version without
              GUI.

-snd        : Uses Richard Mitton's sound engine. Adlib. It doesn't work
              perfectly with games that include voices.

-res nnn nnn: Indicates the resolution. Ex: -res 640 480


All these parameters can be modified in the calypso.ini file.  In theory
you should never edit it, because all the changes you make will be saved
by Calypso automatically, and this way you don't need to retype all the 
options each time you run the emulator.  You type an option once and Calypso
keeps it until you change it.


----------------------
 Acknowledgements
----------------------



Marat Fayzullin        For Master Gear and the Z80 engine used by the program.
James McKay            For Massage and some very useful technical docs.
Richard Talbot         For his EXCELLENT technical doc, and his help.
Ricardo Bittencourt    For his help.
Zoop                   For discovering BUGs and offering his help
Richard Mitton         For the best Z80 assembly engine, RAZE
Lester Knight Chakyn   For his help with english :)
Magnus Ljung           For the best windowing system, JAWS
Nyef	               For his help with digital synthesis and Darcnes

Marcel De Koegel, Neil Bradley, and the Snes9x team for several things.
To the Snese author, for his code.  Sardu, for developing the world's best
emulators.

To the people that write me mails with comments about the emulator

----------------------
 Send me an email
----------------------

For any question, suggestion, comment or BUG REPORT, send me an email to:

jdelmen@ribera.tel.uva.es

All mails asking for ROM's will be sent to lamer pages automatically.  But, 
you can (must) send me an e-mail if a game works or not on the emulator.


----------------------
 Disclaimer
----------------------


Calypso is not a part of SEGA, nor it has anything to do with SEGA.

Calypso is a free distributed program.  But, it's strictly forbidden to
distribute it with ROMS.

I don't take any responsibility AT ALL for ANY DAMAGE or benefit that
running this program may cause.

