Home :: PacmanEmulator :: Machine classes

class PacmanMachine

? ^ 
    extends Z80Environment as public

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

Contents

^ 
EntityInherited FromTypeScopeShort Description
~PacmanMachinedestructor publicDestructor.
PacmanMachineconstructor publicConstructor.
$anonymous$enum publicMachine hardware data
$anonymous$enum publicDIP switches
decodeCharSetstatic method publicDecodes and expands the 4K ROM containing the character definitions into a 16K RAM buffer where each byte correspond directly to a 8x8 character pixel.
decodePaletteBytestatic method publicDecode one byte from the encoded color palette.
decodeSpritesstatic method publicDecodes and expands the 4K ROM containing the sprite definitions into a 16K RAM buffer where each byte correspond directly to a 16x16 sprite pixel.
getCoinLockoutmethod publicReturns the status of the coin lockout door.
getCoinMetermethod publicReturns the number of coins inserted since the machine was powered on.
getColorMemmethod publicReturns a pointer to the color memory in "normalized" form (224x288, one byte per pixel).
getDeviceModemethod publicReturns the current status of an input device.
getDipSwitchesmethod publicReturns the value of the DIP switches.
getFrameCountmethod publicReturns how many times run() has been called since last reset.
getPalettemethod publicReturns a pointer to the decoded 32 color palette: each entry contains a color in RGB format encoded as 0x00bbggrr.
getPlayerOneLightmethod publicReturns the status of the start light for player one.
getPlayerTwoLightmethod publicReturns the status of the start light for player two.
getRAMmethod publicReturns 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).
getSizeOfSnapshotBuffermethod publicReturns the size of the buffer needed to take a snapshot of the machine.
getSpritemethod publicReturns a pointer to the current settings of the specified sprite.
getVideoMemmethod publicReturns a pointer to the video memory in "normalized" form (224x288, one byte per pixel).
InputDeviceenum publicInput devices and switches
InputDeviceModeenum publicInput device mode
onReturnFromInterruptZ80Environmentmethod publicCalled immediately after a RETI is executed.
playSoundmethod publicReproduces the sound that is currently being generated by the sound chip into the specified buffer.
readByteZ80Environmentmethod publicReads one byte from memory at the specified address.
readPortZ80Environmentmethod publicReads one byte from the specified port.
renderVideomethod publicDraws the current video into the specified buffer.
resetmethod publicResets the machine.
restoreSnapshotmethod publicRestores a snapshot taken with takeSnapshot().
runmethod publicRuns the machine for one frame, i.e.
setColorROMsmethod publicSets the color ROMs containing the color definitions and the color map.
setDeviceModemethod publicTells the emulator that the status of an input device has changed.
setDipSwitchesmethod publicSets the value of the DIP switches that control several game settings (see the Dip...
setROMmethod publicSets the main game ROM.
setSpeedHackmethod publicEnables/disables a common speed hack that allows Pacman to move four times faster than the ghosts.
setVideoROMsmethod publicSets the video ROMs that contain character and sprite definitions.
takeSnapshotmethod publicTakes a snapshot of the machine.
writeByteZ80Environmentmethod publicWrites one byte to memory at the specified address.
writePortZ80Environmentmethod publicWrites one byte from the specified port.

destructor ~PacmanMachine

? ^  > 
Destructor.
Source:
arcade.h:165
Code:
public virtual ~ PacmanMachine ( )

constructor PacmanMachine

? ^  < > 
Constructor.
Source:
arcade.h:160
Code:
public PacmanMachine ( )

enum $anonymous$

? ^  < > 
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 }

enum $anonymous$

? ^  < > 
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 }

static method decodeCharSet

? ^  < > 
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 )

static method decodePaletteByte

? ^  < > 
Decode one byte from the encoded color palette.
Source:
arcade.h:435
Code:
public static unsigned decodePaletteByte ( unsigned char b )

static method decodeSprites

? ^  < > 
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 )

method getCoinLockout

? ^  < > 
Returns the status of the coin lockout door.
Source:
arcade.h:450
Code:
public unsigned char getCoinLockout ( ) const

method getCoinMeter

? ^  < > 
Returns the number of coins inserted since the machine was powered on.
Source:
arcade.h:254
Code:
public unsigned getCoinMeter ( ) const

method getColorMem

? ^  < > 
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

method getDeviceMode

? ^  < > 
Returns the current status of an input device.
Source:
arcade.h:228
Code:
public virtual InputDeviceMode getDeviceMode ( InputDevice device ) const

method getDipSwitches

? ^  < > 
Returns the value of the DIP switches.
Source:
arcade.h:238
Code:
public unsigned getDipSwitches ( ) const

method getFrameCount

? ^  < > 
Returns how many times run() has been called since last reset.
Source:
arcade.h:259
Code:
public unsigned getFrameCount ( ) const

method getPalette

? ^  < > 
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

method getPlayerOneLight

? ^  < > 
Returns the status of the start light for player one.
Source:
arcade.h:440
Code:
public unsigned char getPlayerOneLight ( ) const

method getPlayerTwoLight

? ^  < > 
Returns the status of the start light for player two.
Source:
arcade.h:445
Code:
public unsigned char getPlayerTwoLight ( ) const

method getRAM

? ^  < > 
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

method getSizeOfSnapshotBuffer

? ^  < > 
Returns the size of the buffer needed to take a snapshot of the machine.
Source:
arcade.h:389
Code:
public virtual unsigned getSizeOfSnapshotBuffer ( ) const

method getSprite

? ^  < > 
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

method getVideoMem

? ^  < > 
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

enum InputDevice

? ^  < > 
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 }

enum InputDeviceMode

? ^  < > 
Input device mode
Source:
arcade.h:120
Code:
public enum InputDeviceMode { DeviceOn ,
DevicePushed = DeviceOn ,
DeviceOff ,
DeviceReleased = DeviceOff ,
DeviceToggle }

method onReturnFromInterrupt

? ^  < > 
Called immediately after a RETI is executed.
Inherited From:
Z80Environment
Source:
z80.h:94
Code:
public virtual void onReturnFromInterrupt ( )

method playSound

? ^  < > 
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 )

method readByte

? ^  < > 
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 )

method readPort

? ^  < > 
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 )

method renderVideo

? ^  < > 
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 )

method reset

? ^  < > 
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 ( )

method restoreSnapshot

? ^  < > 
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 )

method run

? ^  < > 
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 ( )

method setColorROMs

? ^  < > 
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 )

method setDeviceMode

? ^  < > 
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 )

method setDipSwitches

? ^  < > 
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 )

method setROM

? ^  < > 
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 )

method setSpeedHack

? ^  < > 
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 )

method setVideoROMs

? ^  < > 
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 )

method takeSnapshot

? ^  < > 
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 )

method writeByte

? ^  < > 
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 )

method writePort

? ^  < > 
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.