		***********************************
		* Rockulator++ Programmers Manual *
		***********************************


Introduction.
=============
I have always felt that an Object Oriented framework would work well for an 
arcade emulator, since each component of an arcade machine can be thought of 
as an object (CPU, Sound Chips, Game Controllers, Display, etc.).  In may ways, 
M.A.M.E., the defacto standard for arcade emulators, is object oriented, though 
in the standard C approach, using structs and function pointers to encapsulate 
each game.  Rockulator++ is an attempt to build a truly object oriented framework 
in C++.  Though much of the code is taken from its predecessor (Rock-ulator), 
it is a completely new framework.  I tried to keep two goals in mind:  allow 
new game emulations to be quickly developed, and give the programmer maximum 
control and flexibility over the code.  

What you will need to compile the source code:

- DJGPP v2.01 (including C++ libraries)
- Allegro v2.20 Game Library
- S.E.A.L Audio Library

Links to obtain all of the above can be found at the Arcade Emulation Programming
Repository.


1.  Deriving a New Game Class
=============================
All games are derived from the Game class.  If there are several games that are 
very similar, a parent game class can be derived from the Game class, and each 
individual game can be derived from it.  The following is a minimum class 
declaration for a new game class

class MyGame : public Game
{
private:
   pProcZ80 * pZ80;		// this example uses a Z80 processor
   void Video();		// draw game graphics
   void Audio();		// update game sound
   void Load();			// load a saved game
   void Save();			// save the current game
   void LoadScore();		// load the highscore 
   void SaveScore();		// save the highscore
protected:
public:
   MyGame();			// constructor - create game components
   virtual ~MyGame();		// destructor - destroy game components
   void Reset();		// reset the game
   void Execute();		// begin emulation
   int Interrupt();		// interrupt - redraw the screen
   IOPort * Player0;		// this example has one I/O port
   DipSwitch * Dipswitch;	// and one dipswitch
};

All of the member functions shown in this example MUST be defined in the derived 
game class.  The files SAMPLE.H and SAMPLE.CPP have a more complete template for a 
derived game class.


2.  Component Classes
=====================
While each new game is derived from the Game class, there are a number of 
component classes to simplify the construction of the new game.


2.0  Processor Classes
======================
Currently, Rockulator++ supports 6502, Z80, and 6809 processors, via the
Processor classes.  Each class can define multiple processors At the heart of 
each class is an assembly language based emulation engine to maximize processor 
performance.  At this time, several 68000 emulation engines are being evaluated.

All Processor classes have the following member functions:

ProcXXXX(int num=1)	// constructor - num is number of processors (optional)
~ProcXXXX()		// destructor
void Select(int x=1)	// select CPU emulation - x is processor number (optional)
void Reset(int x=1)	// reset the processor - x is processor number (optional)
void Exec(int x=1)	// execute emulation - x is processor number (optional)
void NMI()		// force a Non-Masked Interrupt
void Load(FILE *fp)	// load saved processor info - fp is file handle
void Save(FILE *fp)	// save processor info - fp is file handle

RAM space for the first CPU is created by the Game base class.  RAM space for each 
additional processor must be created and managed by the derived game class.


2.0.0  Proc6502 - The 6502 Class
================================
Proc6502 is an encapsulation of the Multi-6502 emulation engine, by Neil Bradley.

Additional member functions:

void SetMemoryRW(		// set processor info
   MemoryWrite *pMW, 		//    pMW - pointer to memory write handler table
   MemoryRead *pMR, 		//    pMR - pointer to memory read handler table
   int instructionCount,	//    instructionCount - instructions to execute
   BYTE *pRam, 			//    pRam - pointer to emulation RAM
   int x=1)			//    x - processor number (optional)
void IRQ()			// force a Masked Interrupt

For each 6502 processor to be emulated, the programmer must create a memory read 
handler table and a memory write handler table.  These are passed to the 6502
object via the SetMemoryRW member function.


2.0.1  ProcZ80 - The Z80 Class
==============================
ProcZ80 is an encapsulation of the M.A.Z.E. Z80 emulation engine, by Ishmair.

Additional member functions:

void SetMemoryRW(		// set processor info
   MemoryWrite *pMW, 		//    pMW - pointer to memory write handler table
   MemoryRead *pMR, 		//    pMR - pointer to memory read handler table
   void **ReadWriteTable, 	//    ReadWriteTable - pointer to array of 128K void*
   BYTE (*In)(WORD), 		//    In - IN instruction handler function
   void (*Out)(BYTE, BYTE), 	//    Out - OUT instruction handler function
   int instructionCount,	//    instructionCount - instructions to execute
   BYTE *pRam, 			//    pRam - pointer to emulation RAM
   int x=1)			//    x - processor number (optional)
void EnableInterrupts(		// enable/disable interrupts
   int x=1, 			//    x - processor number (optional)
   int on=0)			//    on - enable flag (optional)

For each Z80 processor to be emulated, the programmer must create a memory read 
handler table, a memory write handler table, a void * array (for 0x20000 elements!),
an IN handler function, and an OUT handler function.  These are passed to the Z80
object via the SetMemoryRW member function.


2.0.2  Proc6809 - The 6809 Class
================================
Proc6809 is an encapsulation of the Multi-6809 emulation engine, by Pat Lawrence.

Additional member functions:

void SetMemoryRW(		// set processor info
   MemoryWrite *pMW, 		//    pMW - pointer to memory write handler table
   MemoryRead *pMR, 		//    pMR - pointer to memory read handler table
   int instructionCount,	//    instructionCount - instructions to execute
   BYTE *pRam, 			//    pRam - pointer to emulation RAM
   int x=1)			//    x - processor number (optional)
void IRQ()			// force a Masked Interrupt

For each 6809 processor to be emulated, the programmer must create a memory read 
handler table and a memory write handler table.  These are passed to the 6502
object via the SetMemoryRW member function.


2.0.2  Proc68000 - The 68000 Class
==================================
Its coming...its coming!


2.1  Display
============


2.2  Audio Classes
==================


2.2.0  AudioDev - Low Level Audio Class
=======================================
The AudioDev class is an encapulation of the S.E.A.L. audio library.  Other
audio classes either derive from this class, or contain it as a member object.


2.2.1  AYPSG - AY8910 Programmable Sound Generator Class
========================================================
The AYPSG class is an encapsulation of the AY8910 functions by Mike Cuddy 
(actually, Mike stole 'em, so I did too).  The AYPSG supports up to 5 AY8910 
chips.


2.3  Keyboard Class
===================
The Keyboard class is currently an encapsulation of the Allegro keyboard
functions.  Since there is only one keyboard (on my computer anyway), The
Game base class contains an object called aKeyboard.  It can be accessed outside
of the class using the KB() member function.

Since most games are I/O mapped, the keyboard should not normally need to be
accessed directly.  Map keyboard controls using the IOPort class.

Keyboard member functions:

int Hit() 		// returns true if keypressed
int ReadKey() 		// waits for input from keyboard buffer and returns it
void Clear() 		// clears the keyboard buffer
char operator[](char x) // returns hit status of key - x is key desired


2.4  Joystick Class
===================
The Joystick class is currently an encapsulation of the Allegro joystick
functions.  Currently, only one joystick is supported.

Since most games are I/O mapped, the joystick should not normally need to be
accessed directly.  Map joystick controls using the IOPort class.

Joystick member functions:

int Left() 		// returns true if joystick is moved left
int Right()		// returns true if joystick is moved right
int Up() 		// returns true if joystick is moved up
int Down() 		// returns true if joystick is moved down
int Button1()		// returns true if button 1 is pressed
int Button2()		// returns true if button 2 is pressed
int Button3()		// returns true if button 3 is pressed
int Button4()		// returns true if button 4 is pressed


2.5  IOPort Class
=================


2.5.1  DipSwitch Class
======================


3.  The Game Class In Detail
============================


4.  Adding the New Class to the Program
=======================================
Once the new class has been developed, there are a few steps to making the
program aware of it.


Final Words.
============
This document is both brief and incomplete (or at least, wildly inaccurate).
The classes themselves will probably be in a state a flux for the next few 
revisions.  Refer to the source code for working examples.  

If all else fails, email me at blevine@mpinet.com.  If you come up with a 
working game class or an enhancement to the framework, please forward it to me, as
I will be posting updates to the program.

You are free to release emulations developed with the emulator.  I only ask that 
disable those games you did not develop, before you release it.

Finally, you didn't pay for this, so don't make others pay it.