Pacman machine emulator.

This class implements the Z80Environment interface to provide the Z80 CPU core with a virtual Pacman hardware.

The emulator also virtualizes input and output systems so that any application can easily interface with the emulator in order to provide input (e.g. key presses or joystick movements) and display output. For the latter, the application can choose to perform its own rendering or to use emulator functions that render video and sound in a standard, easy-to-use format.

Source:

arcade.h:77

Author:

Alessandro Scotti

Version:

1.1

Entity	Inherited From	Type	Scope	Short Description
~PacmanMachine		destructor	public	Destructor.
PacmanMachine		constructor	public	Constructor.
$anonymous$		enum	public	Machine hardware data
$anonymous$		enum	public	DIP switches
decodeCharSet		static method	public	Decodes and expands the 4K ROM containing the character definitions into a 16K RAM buffer where each byte correspond directly to a 8x8 character pixel.
decodePaletteByte		static method	public	Decode one byte from the encoded color palette.
decodeSprites		static method	public	Decodes and expands the 4K ROM containing the sprite definitions into a 16K RAM buffer where each byte correspond directly to a 16x16 sprite pixel.
getCoinLockout		method	public	Returns the status of the coin lockout door.
getCoinMeter		method	public	Returns the number of coins inserted since the machine was powered on.
getColorMem		method	public	Returns a pointer to the color memory in "normalized" form (224x288, one byte per pixel).
getDeviceMode		method	public	Returns the current status of an input device.
getDipSwitches		method	public	Returns the value of the DIP switches.
getFrameCount		method	public	Returns how many times run() has been called since last reset.
getPalette		method	public	Returns a pointer to the decoded 32 color palette: each entry contains a color in RGB format encoded as 0x00bbggrr.
getPlayerOneLight		method	public	Returns the status of the start light for player one.
getPlayerTwoLight		method	public	Returns the status of the start light for player two.
getRAM		method	public	Returns a pointer to the 20K ROM/RAM buffer containing the 16K game ROM (starting at 0x0000) and 4K of RAM (starting at 0x4000, this includes the video RAM at 0x4000-0x43FF and the color RAM at 0x4400-0x47FF).
getSizeOfSnapshotBuffer		method	public	Returns the size of the buffer needed to take a snapshot of the machine.
getSprite		method	public	Returns a pointer to the current settings of the specified sprite.
getVideoMem		method	public	Returns a pointer to the video memory in "normalized" form (224x288, one byte per pixel).
InputDevice		enum	public	Input devices and switches
InputDeviceMode		enum	public	Input device mode
onReturnFromInterrupt	Z80Environment	method	public	Called immediately after a RETI is executed.
playSound		method	public	Reproduces the sound that is currently being generated by the sound chip into the specified buffer.
readByte	Z80Environment	method	public	Reads one byte from memory at the specified address.
readPort	Z80Environment	method	public	Reads one byte from the specified port.
renderVideo		method	public	Draws the current video into the specified buffer.
reset		method	public	Resets the machine.
restoreSnapshot		method	public	Restores a snapshot taken with takeSnapshot().
run		method	public	Runs the machine for one frame, i.e.
setColorROMs		method	public	Sets the color ROMs containing the color definitions and the color map.
setDeviceMode		method	public	Tells the emulator that the status of an input device has changed.
setDipSwitches		method	public	Sets the value of the DIP switches that control several game settings (see the Dip...
setROM		method	public	Sets the main game ROM.
setSpeedHack		method	public	Enables/disables a common speed hack that allows Pacman to move four times faster than the ghosts.
setVideoROMs		method	public	Sets the video ROMs that contain character and sprite definitions.
takeSnapshot		method	public	Takes a snapshot of the machine.
writeByte	Z80Environment	method	public	Writes one byte to memory at the specified address.
writePort	Z80Environment	method	public	Writes one byte from the specified port.

Destructor.

Source:

arcade.h:165

Code:

public virtual ~ PacmanMachine ( )

Constructor.

Source:

arcade.h:160

Code:

public PacmanMachine (

)

Machine hardware data

Source:

arcade.h:91

Code:

public enum {	ScreenWidth = 224 ,
	ScreenHeight = 288 ,
	ScreenWidthChars = 28 ,
	ScreenHeightChars = 36 ,
	CharWidth = 8 ,
	CharHeight = 8 ,
	VideoFrequency = 60 ,
	CpuClock = 3072000 ,
	SoundClock = 96000 ,
	CpuCyclesPerFrame = CpuClock / VideoFrequency }

DIP switches

Source:

arcade.h:154

Code:

public enum {	DipPlay_Free = 0x00 ,
	DipPlay_OneCoinOneGame = 0x01 ,
	DipPlay_OneCoinTwoGames = 0x02 ,
	DipPlay_TwoCoinsOneGame = 0x03 ,
	DipPlay_Mask = 0x03 ,
	DipLives_1 = 0x00 ,
	DipLives_2 = 0x04 ,
	DipLives_3 = 0x08 ,
	DipLives_5 = 0x0C ,
	DipLives_Mask = 0x0C ,
	DipBonus_10000 = 0x00 ,
	DipBonus_15000 = 0x10 ,
	DipBonus_20000 = 0x20 ,
	DipBonus_None = 0x30 ,
	DipBonus_Mask = 0x30 ,
	DipDifficulty_Normal = 0x40 ,
	DipDifficulty_Hard = 0x00 ,
	DipDifficulty_Mask = 0x40 ,
	DipGhostNames_Normal = 0x80 ,
	DipGhostNames_Alternate = 0x00 ,
	DipGhostNames_Mask = 0x80 ,
	DipMode_Play = 0x0000 ,
	DipMode_Test = 0x0100 ,
	DipMode_Mask = 0x0100 ,
	DipCabinet_Upright = 0x0000 ,
	DipCabinet_Cocktail = 0x0200 ,
	DipCabinet_Mask = 0x0200 ,
	DipRackAdvance_Off = 0x0000 ,
	DipRackAdvance_Auto = 0x0400 ,
	DipRackAdvance_Mask = 0x0400 }

Decodes and expands the 4K ROM containing the character definitions into a 16K RAM buffer where each byte correspond directly to a 8x8 character pixel.

Source:

arcade.h:426

Code:

public static void decodeCharSet (	unsigned char * mem ,
	unsigned char * charset )

Decode one byte from the encoded color palette.

Source:

arcade.h:435

Code:

public static unsigned decodePaletteByte (

unsigned char b )

Decodes and expands the 4K ROM containing the sprite definitions into a 16K RAM buffer where each byte correspond directly to a 16x16 sprite pixel.

Source:

arcade.h:432

Code:

public static void decodeSprites (	unsigned char * mem ,
	unsigned char * sprite_data )

Returns the status of the coin lockout door.

Source:

arcade.h:450

Code:

public unsigned char getCoinLockout (

) const

Returns the number of coins inserted since the machine was powered on.

Source:

arcade.h:254

Code:

public unsigned getCoinMeter (

) const

Returns a pointer to the color memory in "normalized" form (224x288, one byte per pixel).

Note: Pacman has a rather peculiar video/color memory layout but this buffer is kept "normalized" by the emulator so it has the same format as the output buffer used by renderVideo(). The raw color memory can be found in the RAM buffer at 0x4400-0x47FF.

This function is only necessary if the application wants to perform its own rendering, because renderVideo() already draws the video.

Source:

arcade.h:384

See Also:

renderVideo

Code:

public const unsigned char * getColorMem (

) const

Returns the current status of an input device.

Source:

arcade.h:228

Code:

public virtual InputDeviceMode getDeviceMode (

InputDevice device ) const

Returns the value of the DIP switches.

Source:

arcade.h:238

Code:

public unsigned getDipSwitches (

) const

Returns how many times run() has been called since last reset.

Source:

arcade.h:259

Code:

public unsigned getFrameCount (

) const

Returns a pointer to the decoded 32 color palette: each entry contains a color in RGB format encoded as 0x00bbggrr.

Source:

arcade.h:323

Code:

public const unsigned * getPalette (

) const

Returns the status of the start light for player one.

Source:

arcade.h:440

Code:

public unsigned char getPlayerOneLight (

) const

Returns the status of the start light for player two.

Source:

arcade.h:445

Code:

public unsigned char getPlayerTwoLight (

) const

Returns a pointer to the 20K ROM/RAM buffer containing the 16K game ROM (starting at 0x0000) and 4K of RAM (starting at 0x4000, this includes the video RAM at 0x4000-0x43FF and the color RAM at 0x4400-0x47FF).

The first 16K of the buffer contain the game ROM as specified in the setROM() function.

Source:

arcade.h:336

Code:

public const unsigned char * getRAM (

) const

Returns the size of the buffer needed to take a snapshot of the machine.

Source:

arcade.h:389

Code:

public virtual unsigned getSizeOfSnapshotBuffer (

) const

Returns a pointer to the current settings of the specified sprite.

This function is only necessary if the application wants to perform its own rendering, because renderVideo() already draws the sprites.

Source:

arcade.h:348

See Also:

renderVideo

Code:

public const PacmanSprite * getSprite (

int index ) const

Returns a pointer to the video memory in "normalized" form (224x288, one byte per pixel).

Note: Pacman has a rather peculiar video/color memory layout but this buffer is kept "normalized" by the emulator so it has the same format as the output buffer used by renderVideo(). The raw video memory can be found in the RAM buffer at 0x4000-0x43FF.

This function is only necessary if the application wants to perform its own rendering, because renderVideo() already draws the video.

Source:

arcade.h:366

See Also:

renderVideo

Code:

public const unsigned char * getVideoMem (

) const

Input devices and switches

Source:

arcade.h:111

Code:

public enum InputDevice {	Joy1_Up = 0 ,
	Joy1_Left ,
	Joy1_Right ,
	Joy1_Down ,
	Switch_RackAdvance ,
	CoinSlot_1 ,
	CoinSlot_2 ,
	Switch_AddCredit ,
	Joy2_Up ,
	Joy2_Left ,
	Joy2_Right ,
	Joy2_Down ,
	Switch_Test ,
	Key_OnePlayer ,
	Key_TwoPlayers ,
	Switch_CocktailMode }

Input device mode

Source:

arcade.h:120

Code:

public enum InputDeviceMode {	DeviceOn ,
	DevicePushed = DeviceOn ,
	DeviceOff ,
	DeviceReleased = DeviceOff ,
	DeviceToggle }

Called immediately after a RETI is executed.

Inherited From:

Z80Environment

Source:

z80.h:94

Code:

public virtual void onReturnFromInterrupt (

)

Reproduces the sound that is currently being generated by the sound chip into the specified buffer.

The sound chip has three independent voices that generate 8-bit signed PCM audio at 96 KHz. This function resamples the voices at the specified sampling rate and mixes them into the output buffer. The output buffer can be converted to 8-bit (signed) PCM by dividing each sample by 3 (since there are three voices) or it can be expanded to 16-bit by multiplying each sample by 85 (i.e. 256 divided by 3). If necessary, it is possible to approximate these values with 4 and 64 in order to use arithmetic shifts that are usually faster to execute.

Note: this function clears the content of the output buffer before mixing voices into it.

Source:

arcade.h:281

Params:

buf	pointer to sound buffer that receives the audio samples
len	length of the sound buffer
samplingRate	sampling rate (in Hertz or samples per second) of the sound buffer

Code:

public virtual void playSound (	int * buf ,
	int len ,
	int samplingRate )

Reads one byte from memory at the specified address.

The address parameter may contain any value, including values greater than 0xFFFF (64k), so if necessary the implementation must check for illegal values and handle them according to the implemented system specifications.

Inherited From:

Z80Environment

Source:

z80.h:59

Code:

public virtual unsigned char readByte (

unsigned addr )

Reads one byte from the specified port.

Note: the port value is always between 00h and FFh included.

Inherited From:

Z80Environment

Source:

z80.h:80

Code:

public virtual unsigned char readPort (

unsigned port )

Draws the current video into the specified buffer.

The buffer must be at least 224*288 bytes long. Pixels are stored in left-to-right/top-to-bottom order starting from the upper left corner. There is one byte per pixel, containing an index into the color palette returned by getPalette().

It's up to the application to display the buffer to the user. The code might look like this:

    unsigned char video_buffer[ PacmanMachine::ScreenWidth * PacmanMachine::ScreenHeight ];
    unsigned char * vbuf = video_buffer;
    const unsigned * palette = arcade.getPalette();

    arcade.renderVideo( vbuf );

    for( int y=0; y<PacmanMachine::ScreenHeight; y++ ) {
        for( int x=0; x<PacmanMachine::ScreenWidth; x++ ) {
            unsigned color = palette[ *vbuf++ ];
            unsigned char red = color & 0xFF;
            unsigned char green = (color >> 8) & 0xFF;
            unsigned char blue = (color >> 16) & 0xFF;

            setPixel( x, y, red, green, blue );
        }
    }

Source:

arcade.h:315

Code:

public virtual void renderVideo (

unsigned char * buffer )

Resets the machine.

This function is equivalent to turning the machine off and on again, but it preserves the ROMs that were previously set so the application does not have to reinitialize them.

It is usually called on startup and to enable changes in the DIP switch settings.

Source:

arcade.h:178

Param:

settings

Code:

public virtual void reset (

)

Restores a snapshot taken with takeSnapshot().

This function uses the data saved in the snapshot buffer to restore the machine status.

Source:

arcade.h:420

Param:

buffer

buffer where the snapshot data is stored

Returns:

the number of bytes read from the buffer

Code:

public virtual unsigned restoreSnapshot (

unsigned char * buffer )

Runs the machine for one frame, i.e.

1/60th of a second in Pacman.

Note that sound is updated after each frame, but the video is only updated every other frame.

Source:

arcade.h:186

Code:

public virtual int run (

)

Sets the color ROMs containing the color definitions and the color map.

Source:

arcade.h:223

Params:

palette	pointer to 32 byte PROM containing color definitions
color	pointer to 256-entry 4-bit PROM containing the mapping between the color index and the color definition (from the palette)

Code:

public virtual void setColorROMs (	const unsigned char * palette ,
	const unsigned char * color )

Tells the emulator that the status of an input device has changed.

Source:

arcade.h:233

Code:

public virtual void setDeviceMode (	InputDevice device ,
	InputDeviceMode mode )

Sets the value of the DIP switches that control several game settings (see the Dip...

constants above).

Most of the DIP switches are read at program startup and take effect only after a machine reset.

Source:

arcade.h:247

Code:

public void setDipSwitches (

unsigned value )

Sets the main game ROM.

Source:

arcade.h:193

Param:

rom	pointer to the 16K game ROM

Code:

public virtual void setROM (

const unsigned char * rom )

Enables/disables a common speed hack that allows Pacman to move four times faster than the ghosts.

Source:

arcade.h:461

Param:

enabled

true to enabled the hack, false to disable

Returns:

0 if successful, otherwise the patch could not be applied (probably because the loaded ROM set does not support it)

Code:

public virtual int setSpeedHack (

int enabled )

Sets the video ROMs that contain character and sprite definitions.

Usually character and sprite data come together with the game ROM in a 24K ROM bundle and the application can use the following code:

    unsigned char * rom_bundle = ...24K game and video ROM bundle...

    pacmanMachine.setROM( rom_bundle );
    pacmanMachine.setVideoROMs( rom_bundle+0x4000, rom_bundle+0x5000 );

Source:

arcade.h:213

Params:

charset	pointer to 4K character definition data
spriteset	pointer to 4K sprite definition data

Code:

public virtual void setVideoROMs (	const unsigned char * charset ,
	const unsigned char * spriteset )

Takes a snapshot of the machine.

A snapshot saves all of the machine memory and settings, including RAM, ROM, CPU status and I/O registers. It can be restored at any time to bring the machine back to the exact status it had when the snapshot was taken.

Snapshots come very handy to save the progress of a game during a good performance!

Note: the size of the snapshot buffer must be no less than the size returned by the getSizeOfSnapshotBuffer() function.

Source:

arcade.h:408

Param:

buffer

buffer where the snapshot data is stored

Returns:

the number of bytes written into the buffer

Code:

public virtual unsigned takeSnapshot (

unsigned char * buffer )

Writes one byte to memory at the specified address.

The address parameter may contain any value, including values greater than 0xFFFF (64k), so if necessary the implementation must check for illegal values and handle them according to the implemented system specifications.

Inherited From:

Z80Environment

Source:

z80.h:71

Code:

public virtual void writeByte (	unsigned addr ,
	unsigned char value )

Writes one byte from the specified port.

Note: the port value is always between 00h and FFh included.

Inherited From:

Z80Environment

Source:

z80.h:88

Code:

public virtual void writePort (	unsigned port ,
	unsigned char value )

Copyright (c) 1997-2003,2004 Alessandro Scotti. All rights reserved.