libmame.h File Reference

#include <stdarg.h>
#include <stdint.h>

Go to the source code of this file.

Classes
struct	LibMame_ScreenResolution
struct	LibMame_SoundSample
struct	LibMame_Chip
struct	LibMame_Dipswitch
struct	LibMame_PerPlayerControllers
struct	LibMame_SharedControllers
struct	LibMame_AllControllers
struct	LibMame_BiosSet
struct	LibMame_Image
struct	LibMame_PerPlayerControlsState
struct	LibMame_SharedControlsState
struct	LibMame_AllControlsState
struct	LibMame_RunGameOptions
struct	LibMame_RenderPrimitive
struct	LibMame_RunGameCallbacks
Defines
#define	LIBMAME_WORKINGFLAGS_WRONG_COLORS   0x001
#define	LIBMAME_WORKINGFLAGS_IMPERFECT_COLORS   0x002
#define	LIBMAME_WORKINGFLAGS_IMPERFECT_GRAPHICS   0x004
#define	LIBMAME_WORKINGFLAGS_NO_SOUND   0x008
#define	LIBMAME_WORKINGFLAGS_IMPERFECT_SOUND   0x010
#define	LIBMAME_WORKINGFLAGS_NO_COCKTAIL   0x020
#define	LIBMAME_WORKINGFLAGS_UNEMULATED_PROTECTION   0x040
#define	LIBMAME_WORKINGFLAGS_NO_SAVE_STATE   0x080
#define	LIBMAME_WORKINGFLAGS_NOTWORKING   0x100
#define	LIBMAME_RENDERFLAGS_TEXTURE_ORIENTATION(flags)   ((flags) & 0x000F)
#define	LIBMAME_RENDERFLAGS_TEXTURE_FORMAT(flags)   ((LibMame_TextureFormat) ((flags) & 0x00F0))
#define	LIBMAME_RENDERFLAGS_BLEND_MODE(flags)   ((flags) & 0x0F00)
#define	LIBMAME_RENDERFLAGS_ANTIALIAS(flags)   ((flags) & 0x1000)
#define	LIBMAME_RENDERFLAGS_SCREEN_TEXTURE(flags)   ((flags) & 0x2000)
#define	LIBMAME_RENDERFLAGS_TEXTURE_WRAP(flags)   ((flags) & 0x4000)
Typedefs
typedef struct LibMame_RunningGame	LibMame_RunningGame
typedef enum LibMame_ImageStatus_Status	LibMame_ImageStatus
typedef struct LibMame_ScreenResolution	LibMame_ScreenResolution
typedef struct LibMame_SoundSample	LibMame_SoundSample
typedef struct LibMame_Chip	LibMame_Chip
typedef struct LibMame_Dipswitch	LibMame_Dipswitch
typedef struct LibMame_PerPlayerControllers	LibMame_PerPlayerControllers
typedef struct LibMame_SharedControllers	LibMame_SharedControllers
typedef struct LibMame_AllControllers	LibMame_AllControllers
typedef struct LibMame_BiosSet	LibMame_BiosSet
typedef struct LibMame_Image	LibMame_Image
typedef struct LibMame_PerPlayerControlsState	LibMame_PerPlayerControlsState
typedef struct LibMame_SharedControlsState	LibMame_SharedControlsState
typedef struct LibMame_AllControlsState	LibMame_AllControlsState
typedef struct LibMame_RunGameOptions	LibMame_RunGameOptions
typedef struct LibMame_RenderPrimitive	LibMame_RenderPrimitive
typedef struct LibMame_RunGameCallbacks	LibMame_RunGameCallbacks
Enumerations
enum	LibMame_InitializeStatus { LibMame_InitializeStatus_Success = 0, LibMame_InitializeStatus_OutOfMemory, LibMame_InitializeStatus_GeneralFailure }
enum	LibMame_ScreenType { LibMame_ScreenType_Raster, LibMame_ScreenType_LCD, LibMame_ScreenType_Vector }
enum	LibMame_OrientationType { LibMame_OrientationType_Normal = 0, LibMame_OrientationType_90 = 5, LibMame_OrientationType_180 = 3, LibMame_OrientationType_270 = 6 }
enum	LibMame_JoystickDirection {   LibMame_JoystickDirection_Up, LibMame_JoystickDirection_Right, LibMame_JoystickDirection_Down, LibMame_JoystickDirection_Left,   LibMame_JoystickDirectionCount }
enum	LibMame_ControllerType {   LibMame_ControllerType_LeftHorizontalJoystick, LibMame_ControllerType_LeftVerticalJoystick, LibMame_ControllerType_Left4WayJoystick, LibMame_ControllerType_Left8WayJoystick,   LibMame_ControllerType_RightHorizontalJoystick, LibMame_ControllerType_RightVerticalJoystick, LibMame_ControllerType_Right4WayJoystick, LibMame_ControllerType_Right8WayJoystick,   LibMame_ControllerType_AnalogHorizontalJoystick, LibMame_ControllerType_AnalogVerticalJoystick, LibMame_ControllerType_Analog8WayJoystick, LibMame_ControllerType_Spinner,   LibMame_ControllerType_VerticalSpinner, LibMame_ControllerType_Paddle, LibMame_ControllerType_VerticalPaddle, LibMame_ControllerType_Trackball,   LibMame_ControllerType_Lightgun, LibMame_ControllerType_Pedal, LibMame_ControllerType_Pedal2, LibMame_ControllerType_Pedal3,   LibMame_ControllerTypeCount }
enum	LibMame_NormalButtonType {   LibMame_NormalButtonType_1, LibMame_NormalButtonType_2, LibMame_NormalButtonType_3, LibMame_NormalButtonType_4,   LibMame_NormalButtonType_5, LibMame_NormalButtonType_6, LibMame_NormalButtonType_7, LibMame_NormalButtonType_8,   LibMame_NormalButtonType_9, LibMame_NormalButtonType_10, LibMame_NormalButtonType_11, LibMame_NormalButtonType_12,   LibMame_NormalButtonType_13, LibMame_NormalButtonType_14, LibMame_NormalButtonType_15, LibMame_NormalButtonType_16,   LibMame_NormalButtonTypeCount }
enum	LibMame_MahjongButtonType {   LibMame_MahjongButtonType_A, LibMame_MahjongButtonType_B, LibMame_MahjongButtonType_C, LibMame_MahjongButtonType_D,   LibMame_MahjongButtonType_E, LibMame_MahjongButtonType_F, LibMame_MahjongButtonType_G, LibMame_MahjongButtonType_H,   LibMame_MahjongButtonType_I, LibMame_MahjongButtonType_J, LibMame_MahjongButtonType_K, LibMame_MahjongButtonType_L,   LibMame_MahjongButtonType_M, LibMame_MahjongButtonType_N, LibMame_MahjongButtonType_O, LibMame_MahjongButtonType_P,   LibMame_MahjongButtonType_Q, LibMame_MahjongButtonType_Kan, LibMame_MahjongButtonType_Pon, LibMame_MahjongButtonType_Chi,   LibMame_MahjongButtonType_Reach, LibMame_MahjongButtonType_Ron, LibMame_MahjongButtonType_Bet, LibMame_MahjongButtonType_Last_Chance,   LibMame_MahjongButtonType_Score, LibMame_MahjongButtonType_Double_Up, LibMame_MahjongButtonType_Flip_Flop, LibMame_MahjongButtonType_Big,   LibMame_MahjongButtonType_Small, LibMame_MahjongButtonTypeCount }
enum	LibMame_HanafudaButtonType {   LibMame_HanafudaButtonType_A, LibMame_HanafudaButtonType_B, LibMame_HanafudaButtonType_C, LibMame_HanafudaButtonType_D,   LibMame_HanafudaButtonType_E, LibMame_HanafudaButtonType_F, LibMame_HanafudaButtonType_G, LibMame_HanafudaButtonType_H,   LibMame_HanafudaButtonType_Yes, LibMame_HanafudaButtonType_No, LibMame_HanafudaButtonTypeCount }
enum	LibMame_GamblingButtonType {   LibMame_GamblingButtonType_High, LibMame_GamblingButtonType_Low, LibMame_GamblingButtonType_Half, LibMame_GamblingButtonType_Deal,   LibMame_GamblingButtonType_D_Up, LibMame_GamblingButtonType_Take, LibMame_GamblingButtonType_Stand, LibMame_GamblingButtonType_Bet,   LibMame_GamblingButtonType_Keyin, LibMame_GamblingButtonType_Keyout, LibMame_GamblingButtonType_Payout, LibMame_GamblingButtonType_Door,   LibMame_GamblingButtonType_Service, LibMame_GamblingButtonType_Book, LibMame_GamblingButtonType_Hold1, LibMame_GamblingButtonType_Hold2,   LibMame_GamblingButtonType_Hold3, LibMame_GamblingButtonType_Hold4, LibMame_GamblingButtonType_Hold5, LibMame_GamblingButtonType_Cancel,   LibMame_GamblingButtonType_Stop1, LibMame_GamblingButtonType_Stop2, LibMame_GamblingButtonType_Stop3, LibMame_GamblingButtonType_Stop4,   LibMame_GamblingButtonType_Stop_All, LibMame_GamblingButtonTypeCount }
enum	LibMame_SharedButtonType {   LibMame_SharedButtonType_Coin1, LibMame_SharedButtonType_Coin2, LibMame_SharedButtonType_Coin3, LibMame_SharedButtonType_Coin4,   LibMame_SharedButtonType_Coin5, LibMame_SharedButtonType_Coin6, LibMame_SharedButtonType_Coin7, LibMame_SharedButtonType_Coin8,   LibMame_SharedButtonType_Bill1, LibMame_SharedButtonType_Start1, LibMame_SharedButtonType_Start2, LibMame_SharedButtonType_Start3,   LibMame_SharedButtonType_Start4, LibMame_SharedButtonType_Start5, LibMame_SharedButtonType_Start6, LibMame_SharedButtonType_Start7,   LibMame_SharedButtonType_Start8, LibMame_SharedButtonType_Service, LibMame_SharedButtonType_Service1, LibMame_SharedButtonType_Service2,   LibMame_SharedButtonType_Service3, LibMame_SharedButtonType_Service4, LibMame_SharedButtonType_Tilt, LibMame_SharedButtonType_Interlock,   LibMame_SharedButtonType_Volume_Up, LibMame_SharedButtonType_Volume_Down, LibMame_SharedButtonTypeCount }
enum	LibMame_SpecialButtonType {   LibMame_SpecialButtonType_1, LibMame_SpecialButtonType_2, LibMame_SpecialButtonType_3, LibMame_SpecialButtonType_4,   LibMame_SpecialButtonType_5, LibMame_SpecialButtonType_6, LibMame_SpecialButtonType_7, LibMame_SpecialButtonType_8,   LibMame_SpecialButtonType_9, LibMame_SpecialButtonType_10, LibMame_SpecialButtonType_11, LibMame_SpecialButtonType_12,   LibMame_SpecialButtonType_13, LibMame_SpecialButtonType_14, LibMame_SpecialButtonType_15, LibMame_SpecialButtonType_16,   LibMame_SpecialButtonType_17, LibMame_SpecialButtonType_18, LibMame_SpecialButtonType_19, LibMame_SpecialButtonType_20,   LibMame_SpecialButtonType_21, LibMame_SpecialButtonType_22, LibMame_SpecialButtonType_23, LibMame_SpecialButtonType_24,   LibMame_SpecialButtonType_25, LibMame_SpecialButtonType_26, LibMame_SpecialButtonType_27, LibMame_SpecialButtonType_28,   LibMame_SpecialButtonType_29, LibMame_SpecialButtonType_30, LibMame_SpecialButtonType_31, LibMame_SpecialButtonType_32,   LibMame_SpecialButtonTypeCount }
enum	LibMame_UiButtonType {   LibMame_UiButtonType_Configure, LibMame_UiButtonType_On_Screen_Display, LibMame_UiButtonType_Debug_Break, LibMame_UiButtonType_Pause,   LibMame_UiButtonType_Reset_Machine, LibMame_UiButtonType_Soft_Reset, LibMame_UiButtonType_Show_Gfx, LibMame_UiButtonType_Frameskip_Dec,   LibMame_UiButtonType_Frameskip_Inc, LibMame_UiButtonType_Throttle, LibMame_UiButtonType_Fast_Forward, LibMame_UiButtonType_Show_Fps,   LibMame_UiButtonType_Snapshot, LibMame_UiButtonType_Record_Movie, LibMame_UiButtonType_Toggle_Cheat, LibMame_UiButtonType_Up,   LibMame_UiButtonType_Down, LibMame_UiButtonType_Left, LibMame_UiButtonType_Right, LibMame_UiButtonType_Home,   LibMame_UiButtonType_End, LibMame_UiButtonType_Page_Up, LibMame_UiButtonType_Page_Down, LibMame_UiButtonType_Select,   LibMame_UiButtonType_Cancel, LibMame_UiButtonType_Display_Comment, LibMame_UiButtonType_Clear, LibMame_UiButtonType_Zoom_In,   LibMame_UiButtonType_Zoom_Out, LibMame_UiButtonType_Prev_Group, LibMame_UiButtonType_Next_Group, LibMame_UiButtonType_Rotate,   LibMame_UiButtonType_Show_Profiler, LibMame_UiButtonType_Toggle_Ui, LibMame_UiButtonType_Toggle_Debug, LibMame_UiButtonType_Paste,   LibMame_UiButtonType_Save_State, LibMame_UiButtonType_Load_State, LibMame_UiButtonTypeCount }
enum	LibMame_ImageStatus_Status { LibMame_ImageStatus_GoodDump, LibMame_ImageStatus_BadDump, LibMame_ImageStatus_NoDump }
enum	LibMame_RenderPrimitiveType { LibMame_RenderPrimitiveType_Invalid, LibMame_RenderPrimitiveType_Line, LibMame_RenderPrimitiveType_Quad }
enum	LibMame_TextureFormat {   LibMame_TextureFormat_Undefined = 0x0000, LibMame_TextureFormat_Palette16 = 0x0010, LibMame_TextureFormat_PaletteA16 = 0x0020, LibMame_TextureFormat_RGB15 = 0x0030,   LibMame_TextureFormat_RGB32 = 0x0040, LibMame_TextureFormat_ARGB32 = 0x0050, LibMame_TextureFormat_YUY16 = 0x0060 }
enum	LibMame_BlendMode { LibMame_BlendMode_None = 0x0000, LibMame_BlendMode_Alpha = 0x0100, LibMame_BlendMode_RGB_Multiply = 0x0200, LibMame_BlendMode_RGB_Add = 0x0300 }
enum	LibMame_StartupPhase { LibMame_StartupPhase_Preparing, LibMame_StartupPhase_LoadingRoms, LibMame_StartupPhase_InitializingMachine }
enum	LibMame_RunGameStatus {   LibMame_RunGameStatus_Success, LibMame_RunGameStatus_InvalidGameNum, LibMame_RunGameStatus_FailedValidityCheck, LibMame_RunGameStatus_MissingFiles,   LibMame_RunGameStatus_NoSuchGame, LibMame_RunGameStatus_InvalidConfig, LibMame_RunGameStatus_GeneralError }
Functions
LibMame_InitializeStatus	LibMame_Initialize ()
void	LibMame_Deinitialize ()
const char *	LibMame_Get_Version_String ()
int	LibMame_Get_Game_Count ()
int	LibMame_Get_Game_Number (const char *short_name)
int	LibMame_Get_Game_Matches (const char *short_name, int num_matches, int *gamenums)
const char *	LibMame_Get_Game_Short_Name (int gamenum)
const char *	LibMame_Get_Game_Full_Name (int gamenum)
int	LibMame_Get_Game_Year_Of_Release (int gamenum)
int	LibMame_Get_Game_CloneOf (int gamenum)
const char *	LibMame_Get_Game_Manufacturer (int gamenum)
int	LibMame_Get_Game_WorkingFlags (int gamenum)
LibMame_OrientationType	LibMame_Get_Game_Orientation (int gamenum)
LibMame_ScreenType	LibMame_Get_Game_ScreenType (int gamenum)
LibMame_ScreenResolution	LibMame_Get_Game_ScreenResolution (int gamenum)
float	LibMame_Get_Game_ScreenRefreshRateHz (int gamenum)
int	LibMame_Get_Game_SoundChannels (int gamenum)
int	LibMame_Get_Game_SoundSamples_Count (int gamenum)
int	LibMame_Get_Game_SoundSamplesSource (int gamenum)
const char *	LibMame_Get_Game_SoundSampleFileName (int gamenum, int samplenum)
int	LibMame_Get_Game_Chip_Count (int gamenum)
LibMame_Chip	LibMame_Get_Game_Chip (int gamenum, int chipnum)
int	LibMame_Get_Game_Dipswitch_Count (int gamenum)
LibMame_Dipswitch	LibMame_Get_Game_Dipswitch (int gamenum, int num)
int	LibMame_Get_Game_MaxSimultaneousPlayers (int gamenum)
LibMame_AllControllers	LibMame_Get_Game_AllControllers (int gamenum)
int	LibMame_Get_Game_BiosSet_Count (int gamenum)
LibMame_BiosSet	LibMame_Get_Game_BiosSet (int gamenum, int biossetnum)
int	LibMame_Get_Game_Rom_Count (int gamenum)
LibMame_Image	LibMame_Get_Game_Rom (int gamenum, int romnum)
int	LibMame_Get_Game_Hdd_Count (int gamenum)
LibMame_Image	LibMame_Get_Game_Hdd (int gamenum, int hddnum)
const char *	LibMame_Get_Game_SourceFileName (int gamenum)
void	LibMame_Get_Default_RunGameOptions (LibMame_RunGameOptions *options)
LibMame_RunGameStatus	LibMame_RunGame (int gamenum, int benchmarking, const LibMame_RunGameOptions *options, const LibMame_RunGameCallbacks *cbs, void *callback_data)
const char *	LibMame_RunningGame_GetSpeedText (LibMame_RunningGame *game)
void	LibMame_RunningGame_Schedule_Pause (LibMame_RunningGame *game)
void	LibMame_RunningGame_Schedule_Exit (LibMame_RunningGame *game)
void	LibMame_RunningGame_Schedule_Hard_Reset (LibMame_RunningGame *game)
void	LibMame_RunningGame_Schedule_Soft_Reset (LibMame_RunningGame *game)
void	LibMame_RunningGame_SaveState (LibMame_RunningGame *game, const char *filename)
void	LibMame_RunningGame_LoadState (LibMame_RunningGame *game, const char *filename)
void	LibMame_RunningGame_ChangeDipswitchValue (LibMame_RunningGame *game, const char *tag, uint32_t mask, const char *value)

---

Detailed Description

LibMame provides a single API for (almost) all functionality of the MAME engine. It provides the following types of functions:

1. Functions for querying the set of games supported by this version of LibMame, and many descriptive details about each game:

• LibMame_Get_Version_String
• LibMame_Get_Game_Count
• LibMame_Get_Game_Number
• LibMame_Get_Game_Matches
• LibMame_Get_Game_Short_Name
• LibMame_Get_Game_Full_Name
• LibMame_Get_Game_Year_Of_Release
• LibMame_Get_Game_CloneOf
• LibMame_Get_Game_Manufacturer
• LibMame_Get_Game_WorkingFlags
• LibMame_Get_Game_OrientationFlags
• LibMame_Get_Game_ScreenType
• LibMame_Get_Game_ScreenResolution
• LibMame_Get_Game_ScreenRefreshRateHz
• LibMame_Get_Game_SoundChannels
• LibMame_Get_Game_SoundSamples_Count
• LibMame_Get_Game_SoundSamplesSource
• LibMame_Get_Game_SoundSampleFileName
• LibMame_Get_Game_Chip_Count
• LibMame_Get_Game_Chip
• LibMame_Get_Game_Dipswitch_Count
• LibMame_Get_Game_Dipswitch
• LibMame_Get_Game_MaxSimultaneousPlayers
• LibMame_Get_Game_AllControllers
• LibMame_Get_Game_BiosSet_Count
• LibMame_Get_Game_BiosSet
• LibMame_Get_Game_Rom_Count
• LibMame_Get_Game_Rom
• LibMame_Get_Game_Hdd_Count
• LibMame_Get_Game_Hdd
• LibMame_Get_Game_SourceFileName

2. A function for running a MAME game (only one MAME game may be run concurrently within the same process due to limitations in the MAME engine). MAME will emulate the game and will interact with the rest of the system (for displaying frames of the game, playing sound, and getting controller input) via callbacks.

• LibMame_RunGame

3. Functions for manipulating a running MAME game, including pausing, resetting, and manipulating configuration values of various kinds.

• LibMame_RunningGame_Pause
• LibMame_RunningGame_Schedule_Exit
• LibMame_RunningGame_Schedule_Hard_Reset
• LibMame_RunningGame_Schedule_Soft_Reset
• LibMame_RunningGame_SaveState
• LibMame_RunningGame_LoadState
• LibMame_RunningGame_ChangeDipswitchValue

4. Miscellaneous functions necessary for supporting the other libmame functionality:

• LibMame_Initialize
• LibMame_Deinitialize
• LibMame_Get_Default_RunGameOptions

In general, applications using libmame will follow this pattern:

1. Call LibMame_Initialize.

2. Collect game information for display using the LibMame_Get_Game_XXX functions.

3. Look up the number of the game that the user wants to play using LibMame_Get_Game_Number.

4. Set options for running the game by first calling LibMame_Get_Default_RunGameOptions, and then customizing the resulting options according to user preference.

5. Set up internal state for managing the display, sound, and controller input for the game about to be run.

The target display frame rate can be found by calling LibMame_Get_Game_ScreenRefreshRateHz, if needed, and the size at which the game was originally redered is known by calling LibMame_Get_Game_ScreenResolution, although this is not necessarily the same resolution as the visible portion of the game's screen; the visible portion of the game's screen can only be discerned by examining the render primitive bounds in the UpdateVideo callback.

The set of controls that the game will require inputs on can be found by calling LibMame_Get_Game_AllControllers (and the maximum number of players for whom controller input is needed is available from LibMame_Get_Game_MaxSimultaneousPlayers). The application will typically use this information to decide how to map whatever controls it knows about to the inputs that the game is expecting, usually via user preference (managed by the application).

6. Call LibMame_RunGame to run the game, passing in pointers to callback functions that will handle the rendering of audio and video and collecting controller input.

7. As the game is running, according to user input, call the LibMame_RunningGame_XXX functions (but only from the MakeRunningGameCallbacks (or in certain cases, Paused) callbacks, which means that user commands must typically be noted and then applied at the next call to MakeRunningGameCallbacks).

8. When the game completes (i.e. the LibMame_RunningGame_Schedule_Exit callback is made by the application), LibMame_RunGame will return, and the application may then repeat steps 5, 6, and 7 if it wishes.

9. When the application is completely finished calling any LibMame functions, before it exits, it must then call LibMame_Deinitialize.

Please keep in mind that although the API is structured as if it were possible to run multiple MAME games simultaneously from the same application, there is a limit in the MAME engine that prevents more than one game from running at a time. This limit may someday be lifted, in which case this API will already be ready to take advantage of that, but until the limit is lifted, remember that LibMame_RunGame may only be called from one thread at a time within a single application.

---

Define Documentation

#define LIBMAME_RENDERFLAGS_ANTIALIAS

(

flags

)

((flags) & 0x1000)

Calculates the antialias value of a LibMame_RenderPrimitive's flags; zero means no antialiasing, nonzero means antialiasing

#define LIBMAME_RENDERFLAGS_BLEND_MODE

(

flags

)

((flags) & 0x0F00)

Calculates the blend mode of a LibMame_RenderPrimitive's flags; one of the LibMame_RenderFlags_BlendMode enumerated values.

#define LIBMAME_RENDERFLAGS_SCREEN_TEXTURE

(

flags

)

((flags) & 0x2000)

Calculates the screen texture value of a LibMame_RenderPrimitive's flags; zero means that the texture is part of the game's screen, nonzero means that the texture is not part of the game's screen, but is part of some other MAME UI element.

#define LIBMAME_RENDERFLAGS_TEXTURE_FORMAT

(

flags

)

((LibMame_TextureFormat) ((flags) & 0x00F0))

Calculates the texture format of a LibMame_RenderPrimitive's flags; one of the LibMame_RenderFlags_TextureFormat enumerated values.

#define LIBMAME_RENDERFLAGS_TEXTURE_ORIENTATION

(

flags

)

((flags) & 0x000F)

These flags define the screen orientation of the game as it was originally displayed. These macros can be used to obtain values from the LibMame_RenderPrimitive structure's flags field. Calculates the texture orientation of a LibMame_RenderPrimitive's flags; one of the LibMame_OrientationType enumerated values.

#define LIBMAME_RENDERFLAGS_TEXTURE_WRAP

(

flags

)

((flags) & 0x4000)

Calculates the texture wrap of a LibMame_RenderPrimitive's flags; zero means do texture wrapping by repeating the texture; nonzero means do texture wrapping by clamping the texture.

#define LIBMAME_WORKINGFLAGS_IMPERFECT_COLORS   0x002

Colors are not 100% accurate, but close.

#define LIBMAME_WORKINGFLAGS_IMPERFECT_GRAPHICS   0x004

Graphics are wrong/incomplete.

#define LIBMAME_WORKINGFLAGS_IMPERFECT_SOUND   0x010

Sound is known to be wrong.

#define LIBMAME_WORKINGFLAGS_NO_COCKTAIL   0x020

Screen flip support is missing.

#define LIBMAME_WORKINGFLAGS_NO_SAVE_STATE   0x080

Game does not support saving state.

#define LIBMAME_WORKINGFLAGS_NO_SOUND   0x008

Sound is missing, either due to missing sound files, or missing hardware emulation.

#define LIBMAME_WORKINGFLAGS_NOTWORKING   0x100

Game does not work at all.

#define LIBMAME_WORKINGFLAGS_UNEMULATED_PROTECTION   0x040

Game's protection not fully emulated.

#define LIBMAME_WORKINGFLAGS_WRONG_COLORS   0x001

These flags define the 'working' status of a game. Any number of these flags may be or'd together to indicate the complete working status of a game. If none of these flags are set, then the game is known to work perfectly. Colors are totally wrong.

---

Typedef Documentation

typedef struct LibMame_AllControllers LibMame_AllControllers

This describes all of the controller inputs for a game.

typedef struct LibMame_AllControlsState LibMame_AllControlsState

This combines the per-player and the shared controls state into one structure representing all states of all controls.

typedef struct LibMame_BiosSet LibMame_BiosSet

This structure defines a BIOS set, which is the set of ROMS defining the BIOS of a game that may be loaded instead of other BIOS sets for the game. If a game lists multiple BIOS sets, then any one of them may be loaded for the game to produce different behaviors depending on the BIOS set.

typedef struct LibMame_Chip LibMame_Chip

This describes a chip that MAME emulates.

typedef struct LibMame_Dipswitch LibMame_Dipswitch

This describes a dipswitch that MAME allows to be adjusted for a game.

typedef struct LibMame_Image LibMame_Image

This structure defines a single image (ROM or HDD) that a game uses.

typedef enum LibMame_ImageStatus_Status LibMame_ImageStatus

These are the possible ROM/HDD image status values.

typedef struct LibMame_PerPlayerControllers LibMame_PerPlayerControllers

This describes a player's control inputs for a game. This is a set of individual controllers comprising the entire set of control inputs that a player would use to play a game. All players are assumed to use the same type and number of controls during a multiplayer game.

typedef struct LibMame_PerPlayerControlsState LibMame_PerPlayerControlsState

This describes all of the controller values that can be polled by MAME for individual players. One structure of this type for each player is included in the LibMame_AllControlsState structure. Not all values provided in this structure are used for every game; see the LibMame_Get_Game_AllControllers() function for a way to get a description of the set of controls actually used by the currently running game.

typedef struct LibMame_RenderPrimitive LibMame_RenderPrimitive

This is the type of a render primitive passed to the update video callback by libmame. It is one element of a list of render primitives, all of which must be rendered in order to produce a complete frame of video for the running game.

typedef struct LibMame_RunGameCallbacks LibMame_RunGameCallbacks

This is the set of callbacks that the caller of LibMame_RunGame passes in. These provide the interface to allow MAME to supply the frames of video and audio that constitute a running game, as well as allowing MAME to gather input from players of the game, and to provide a mechanism for altering the game state as it is running

typedef struct LibMame_RunGameOptions LibMame_RunGameOptions

These are the configuration options for LibMame_RunGame. Defaults can be loaded by calling LibMame_Get_Default_RunGameOptions, and then customizations done before calling LibMame_RunGame with the resulting options.

typedef struct LibMame_RunningGame LibMame_RunningGame

typedef struct LibMame_ScreenResolution LibMame_ScreenResolution

This is a screen size in pixels

typedef struct LibMame_SharedControllers LibMame_SharedControllers

This describes the shared controller inputs for a game. This is a set of individual controllers comprising the entire set of control inputs that a game has that are not active play controllers. All players share these controllers.

typedef struct LibMame_SharedControlsState LibMame_SharedControlsState

This describes all of the controller values that can be polled by MAME for controls that are shared by all players. Not all values provided in this structure are used for every game.

typedef struct LibMame_SoundSample LibMame_SoundSample

This describes the name and location of a sound sample.

---

Enumeration Type Documentation

enum LibMame_BlendMode

The possible blend modes that can result from the evaluation of the LIBMAME_RENDERFLAGS_BLEND_MODE macro

Enumerator:

LibMame_BlendMode_None	No blending
LibMame_BlendMode_Alpha	Standard alpha blending
LibMame_BlendMode_RGB_Multiply	Apply source alpha to source pixel, then multiply RGB values
LibMame_BlendMode_RGB_Add	Apply source alpha to source pixel, then add RGB values

enum LibMame_ControllerType

All of the possible controller types

Enumerator:

LibMame_ControllerType_LeftHorizontalJoystick
LibMame_ControllerType_LeftVerticalJoystick
LibMame_ControllerType_Left4WayJoystick
LibMame_ControllerType_Left8WayJoystick
LibMame_ControllerType_RightHorizontalJoystick
LibMame_ControllerType_RightVerticalJoystick
LibMame_ControllerType_Right4WayJoystick
LibMame_ControllerType_Right8WayJoystick
LibMame_ControllerType_AnalogHorizontalJoystick
LibMame_ControllerType_AnalogVerticalJoystick
LibMame_ControllerType_Analog8WayJoystick
LibMame_ControllerType_Spinner
LibMame_ControllerType_VerticalSpinner
LibMame_ControllerType_Paddle
LibMame_ControllerType_VerticalPaddle
LibMame_ControllerType_Trackball
LibMame_ControllerType_Lightgun
LibMame_ControllerType_Pedal
LibMame_ControllerType_Pedal2
LibMame_ControllerType_Pedal3
LibMame_ControllerTypeCount

enum LibMame_GamblingButtonType

All of the possible gambling buttons.

Enumerator:

LibMame_GamblingButtonType_High
LibMame_GamblingButtonType_Low
LibMame_GamblingButtonType_Half
LibMame_GamblingButtonType_Deal
LibMame_GamblingButtonType_D_Up
LibMame_GamblingButtonType_Take
LibMame_GamblingButtonType_Stand
LibMame_GamblingButtonType_Bet
LibMame_GamblingButtonType_Keyin
LibMame_GamblingButtonType_Keyout
LibMame_GamblingButtonType_Payout
LibMame_GamblingButtonType_Door
LibMame_GamblingButtonType_Service
LibMame_GamblingButtonType_Book
LibMame_GamblingButtonType_Hold1
LibMame_GamblingButtonType_Hold2
LibMame_GamblingButtonType_Hold3
LibMame_GamblingButtonType_Hold4
LibMame_GamblingButtonType_Hold5
LibMame_GamblingButtonType_Cancel
LibMame_GamblingButtonType_Stop1
LibMame_GamblingButtonType_Stop2
LibMame_GamblingButtonType_Stop3
LibMame_GamblingButtonType_Stop4
LibMame_GamblingButtonType_Stop_All
LibMame_GamblingButtonTypeCount

enum LibMame_HanafudaButtonType

All of the possible Hanafuda buttons.

Enumerator:

LibMame_HanafudaButtonType_A
LibMame_HanafudaButtonType_B
LibMame_HanafudaButtonType_C
LibMame_HanafudaButtonType_D
LibMame_HanafudaButtonType_E
LibMame_HanafudaButtonType_F
LibMame_HanafudaButtonType_G
LibMame_HanafudaButtonType_H
LibMame_HanafudaButtonType_Yes
LibMame_HanafudaButtonType_No
LibMame_HanafudaButtonTypeCount

enum LibMame_ImageStatus_Status

These are the possible ROM/HDD image status values.

Enumerator:

LibMame_ImageStatus_GoodDump	The image is good (true to the original game)
LibMame_ImageStatus_BadDump	The image is bad, but is the best available image
LibMame_ImageStatus_NoDump	There is no image available for this ROM/HDD image

enum LibMame_InitializeStatus

Status codes that can be returned by LibMame_Initialize()

Enumerator:

LibMame_InitializeStatus_Success
LibMame_InitializeStatus_OutOfMemory
LibMame_InitializeStatus_GeneralFailure

enum LibMame_JoystickDirection

All of the possible joystick directions

Enumerator:

LibMame_JoystickDirection_Up
LibMame_JoystickDirection_Right
LibMame_JoystickDirection_Down
LibMame_JoystickDirection_Left
LibMame_JoystickDirectionCount

enum LibMame_MahjongButtonType

All of the possible Mahjong buttons.

Enumerator:

LibMame_MahjongButtonType_A
LibMame_MahjongButtonType_B
LibMame_MahjongButtonType_C
LibMame_MahjongButtonType_D
LibMame_MahjongButtonType_E
LibMame_MahjongButtonType_F
LibMame_MahjongButtonType_G
LibMame_MahjongButtonType_H
LibMame_MahjongButtonType_I
LibMame_MahjongButtonType_J
LibMame_MahjongButtonType_K
LibMame_MahjongButtonType_L
LibMame_MahjongButtonType_M
LibMame_MahjongButtonType_N
LibMame_MahjongButtonType_O
LibMame_MahjongButtonType_P
LibMame_MahjongButtonType_Q
LibMame_MahjongButtonType_Kan
LibMame_MahjongButtonType_Pon
LibMame_MahjongButtonType_Chi
LibMame_MahjongButtonType_Reach
LibMame_MahjongButtonType_Ron
LibMame_MahjongButtonType_Bet
LibMame_MahjongButtonType_Last_Chance
LibMame_MahjongButtonType_Score
LibMame_MahjongButtonType_Double_Up
LibMame_MahjongButtonType_Flip_Flop
LibMame_MahjongButtonType_Big
LibMame_MahjongButtonType_Small
LibMame_MahjongButtonTypeCount

enum LibMame_NormalButtonType

All of the possible general purpose buttons.

Enumerator:

LibMame_NormalButtonType_1
LibMame_NormalButtonType_2
LibMame_NormalButtonType_3
LibMame_NormalButtonType_4
LibMame_NormalButtonType_5
LibMame_NormalButtonType_6
LibMame_NormalButtonType_7
LibMame_NormalButtonType_8
LibMame_NormalButtonType_9
LibMame_NormalButtonType_10
LibMame_NormalButtonType_11
LibMame_NormalButtonType_12
LibMame_NormalButtonType_13
LibMame_NormalButtonType_14
LibMame_NormalButtonType_15
LibMame_NormalButtonType_16
LibMame_NormalButtonTypeCount

enum LibMame_OrientationType

Types of orientation for games; this is the orientation of the screen relative to the displayed image.

Enumerator:

LibMame_OrientationType_Normal	Normal orientation
LibMame_OrientationType_90	90 degrees rotation
LibMame_OrientationType_180	180 degrees rotation
LibMame_OrientationType_270	270 degrees rotation

enum LibMame_RenderPrimitiveType

The possible types of render primitives passed into the update display callback

Enumerator:

LibMame_RenderPrimitiveType_Invalid
LibMame_RenderPrimitiveType_Line
LibMame_RenderPrimitiveType_Quad

enum LibMame_RunGameStatus

Status codes that can be returned by LibMame_RunGame()

Enumerator:

LibMame_RunGameStatus_Success
LibMame_RunGameStatus_InvalidGameNum
LibMame_RunGameStatus_FailedValidityCheck
LibMame_RunGameStatus_MissingFiles
LibMame_RunGameStatus_NoSuchGame
LibMame_RunGameStatus_InvalidConfig
LibMame_RunGameStatus_GeneralError

enum LibMame_ScreenType

Screen types

Enumerator:

LibMame_ScreenType_Raster
LibMame_ScreenType_LCD
LibMame_ScreenType_Vector

enum LibMame_SharedButtonType

All of the possible 'other' buttons.

Enumerator:

LibMame_SharedButtonType_Coin1
LibMame_SharedButtonType_Coin2
LibMame_SharedButtonType_Coin3
LibMame_SharedButtonType_Coin4
LibMame_SharedButtonType_Coin5
LibMame_SharedButtonType_Coin6
LibMame_SharedButtonType_Coin7
LibMame_SharedButtonType_Coin8
LibMame_SharedButtonType_Bill1
LibMame_SharedButtonType_Start1
LibMame_SharedButtonType_Start2
LibMame_SharedButtonType_Start3
LibMame_SharedButtonType_Start4
LibMame_SharedButtonType_Start5
LibMame_SharedButtonType_Start6
LibMame_SharedButtonType_Start7
LibMame_SharedButtonType_Start8
LibMame_SharedButtonType_Service
LibMame_SharedButtonType_Service1
LibMame_SharedButtonType_Service2
LibMame_SharedButtonType_Service3
LibMame_SharedButtonType_Service4
LibMame_SharedButtonType_Tilt
LibMame_SharedButtonType_Interlock
LibMame_SharedButtonType_Volume_Up
LibMame_SharedButtonType_Volume_Down
LibMame_SharedButtonTypeCount

enum LibMame_SpecialButtonType

All of the possible 'special' buttons.

Enumerator:

LibMame_SpecialButtonType_1
LibMame_SpecialButtonType_2
LibMame_SpecialButtonType_3
LibMame_SpecialButtonType_4
LibMame_SpecialButtonType_5
LibMame_SpecialButtonType_6
LibMame_SpecialButtonType_7
LibMame_SpecialButtonType_8
LibMame_SpecialButtonType_9
LibMame_SpecialButtonType_10
LibMame_SpecialButtonType_11
LibMame_SpecialButtonType_12
LibMame_SpecialButtonType_13
LibMame_SpecialButtonType_14
LibMame_SpecialButtonType_15
LibMame_SpecialButtonType_16
LibMame_SpecialButtonType_17
LibMame_SpecialButtonType_18
LibMame_SpecialButtonType_19
LibMame_SpecialButtonType_20
LibMame_SpecialButtonType_21
LibMame_SpecialButtonType_22
LibMame_SpecialButtonType_23
LibMame_SpecialButtonType_24
LibMame_SpecialButtonType_25
LibMame_SpecialButtonType_26
LibMame_SpecialButtonType_27
LibMame_SpecialButtonType_28
LibMame_SpecialButtonType_29
LibMame_SpecialButtonType_30
LibMame_SpecialButtonType_31
LibMame_SpecialButtonType_32
LibMame_SpecialButtonTypeCount

enum LibMame_StartupPhase

The possible startup stats that libmame can report about as it is starting up a game.

Enumerator:

LibMame_StartupPhase_Preparing	MAME is preparing internal state before loading ROMs.
LibMame_StartupPhase_LoadingRoms	MAME is loading ROMs. This happens before machine initialization.
LibMame_StartupPhase_InitializingMachine	MAME is intializing internal machine state in preparation for running a game.

enum LibMame_TextureFormat

The possible texture formats that can result from the evaluation of the LIBMAME_RENDERFLAGS_TETURE_FORMAT macro

Enumerator:

LibMame_TextureFormat_Undefined	Requires a palette to be specified
LibMame_TextureFormat_Palette16	16 bpp palettized, alpha ignored
LibMame_TextureFormat_PaletteA16	16 bpp palettized, alpha respected
LibMame_TextureFormat_RGB15	16 bpp 5-5-5 RGB
LibMame_TextureFormat_RGB32	32 bpp 8-8-8 RGB
LibMame_TextureFormat_ARGB32	32 bpp 8-8-8-8 ARGB
LibMame_TextureFormat_YUY16	16 bpp 8-8 Y/Cb, Y/Cr in sequence

enum LibMame_UiButtonType

All of the possible UI buttons.

Enumerator:

LibMame_UiButtonType_Configure
LibMame_UiButtonType_On_Screen_Display
LibMame_UiButtonType_Debug_Break
LibMame_UiButtonType_Pause
LibMame_UiButtonType_Reset_Machine
LibMame_UiButtonType_Soft_Reset
LibMame_UiButtonType_Show_Gfx
LibMame_UiButtonType_Frameskip_Dec
LibMame_UiButtonType_Frameskip_Inc
LibMame_UiButtonType_Throttle
LibMame_UiButtonType_Fast_Forward
LibMame_UiButtonType_Show_Fps
LibMame_UiButtonType_Snapshot
LibMame_UiButtonType_Record_Movie
LibMame_UiButtonType_Toggle_Cheat
LibMame_UiButtonType_Up
LibMame_UiButtonType_Down
LibMame_UiButtonType_Left
LibMame_UiButtonType_Right
LibMame_UiButtonType_Home
LibMame_UiButtonType_End
LibMame_UiButtonType_Page_Up
LibMame_UiButtonType_Page_Down
LibMame_UiButtonType_Select
LibMame_UiButtonType_Cancel
LibMame_UiButtonType_Display_Comment
LibMame_UiButtonType_Clear
LibMame_UiButtonType_Zoom_In
LibMame_UiButtonType_Zoom_Out
LibMame_UiButtonType_Prev_Group
LibMame_UiButtonType_Next_Group
LibMame_UiButtonType_Rotate
LibMame_UiButtonType_Show_Profiler
LibMame_UiButtonType_Toggle_Ui
LibMame_UiButtonType_Toggle_Debug
LibMame_UiButtonType_Paste
LibMame_UiButtonType_Save_State
LibMame_UiButtonType_Load_State
LibMame_UiButtonTypeCount

---

Function Documentation

void LibMame_Deinitialize

(

)

Deinitializes libmame, releasing any resources that the library has allocated. It is not necessary to call this method before a process exits, as the operating system will reclaim the memory that libmame has allocated; however, when debugging, it may be useful to call this so that memory allocated by libmame does not appear to have been leaked when the program exits.

void LibMame_Get_Default_RunGameOptions

(

LibMame_RunGameOptions *

options

)

Sets the LibMame_RunGameOptions structure to contain all default values.

Parameters:

options

is the options structure to set defaults in

LibMame_AllControllers LibMame_Get_Game_AllControllers

(

int

gamenum

)

This returns a structure describing the controllers for a given game.

Parameters:

gamenum

is the game number of the game

Returns:

a structure describing controllers for a given game.

LibMame_BiosSet LibMame_Get_Game_BiosSet	(	int	gamenum,
		int	biossetnum
	)

This returns a BIOS set for a given game.

Parameters:

gamenum	is the game number of the game
biossetnum	is the number of the BIOS set

Returns:

a BIOS set for a given game.

int LibMame_Get_Game_BiosSet_Count

(

int

gamenum

)

This returns the number of BIOS sets that are known for a given game. A BIOS set describes a set of BIOS roms that may be selected to enable specific functionality in a game.

Parameters:

gamenum

is the game number of the game

Returns:

number of BIOS sets that are known for a given game.

LibMame_Chip LibMame_Get_Game_Chip	(	int	gamenum,
		int	chipnum
	)

Returns a description of a chip that MAME emulates for a given game.

Parameters:

gamenum	is the game number of the game
chipnum	is the chip number of the chip

Returns:

a description of a chip that MAME emulates for a given game.

int LibMame_Get_Game_Chip_Count

(

int

gamenum

)

Returns the number of chips that MAME emulates for a given game.

Parameters:

gamenum

is the game number of the game

Returns:

the number of chips that MAME emulates for a given game.

int LibMame_Get_Game_CloneOf

(

int

gamenum

)

Returns the game number of the game that this game is a clone of, if the game is a clone. Returns -1 if the game is not a clone.

Parameters:

gamenum

is the game number of the game

Returns:

the game number of the game that this game is a clone of, if the game is a clone, or -1 if the game is not a clone.

int LibMame_Get_Game_Count

(

)

Returns the total number of games supported by this instance of libmame.

Returns:

the total number of games supported by this instance of libmame.

LibMame_Dipswitch LibMame_Get_Game_Dipswitch	(	int	gamenum,
		int	num
	)

Returns a description of a dipswitch that MAME supports for a given game.

Parameters:

gamenum	is the game number of the game
num	is the number of the setting

Returns:

a description of a dipswitch that MAME supports for a given game.

int LibMame_Get_Game_Dipswitch_Count

(

int

gamenum

)

Returns the number of dipswitches that MAME supports for a given game.

Parameters:

gamenum

is the game number of the game

Returns:

the number of dipswitches that MAME supports for a given game.

const char* LibMame_Get_Game_Full_Name

(

int

gamenum

)

Returns the full name of a game.

Parameters:

gamenum

is the game number of the game

Returns:

the full name of a game.

LibMame_Image LibMame_Get_Game_Hdd	(	int	gamenum,
		int	hddnum
	)

This returns information about an HDD image that is known to be used by a given game.

Parameters:

gamenum	is the game number of the game
romnum	is the number of the HDD image to return

Returns:

information about an HDD image that is known to be used by a given game

int LibMame_Get_Game_Hdd_Count

(

int

gamenum

)

This returns the number of Hard Disk Drive images (also called CHDs) for a given game. In general, a game needs all of its CHDs to run.

Parameters:

gamenum

is the game number of the game

Returns:

the number of Hard Disk Drive images for a given game

const char* LibMame_Get_Game_Manufacturer

(

int

gamenum

)

Returns the name of the manufacturer of the given game.

Parameters:

gamenum

is the game number of the game

Returns:

the name of the manufacturer of the given game.

int LibMame_Get_Game_Matches	(	const char *	short_name,
		int	num_matches,
		int *	gamenums
	)

Returns the best matches for a given game short name.

Parameters:

short_name	is the short name to find matches for
num_matches	gives the maxium number of matches to find; [gamenums] must have at least this number of entries
gamenums	will have its first N entries set to the game numbers of matching games (best match first), where N is the return value of this function

Returns:

the number of matches returned; this many of the first entries of [gamenums] will include game numbers of games which matched.

int LibMame_Get_Game_MaxSimultaneousPlayers

(

int

gamenum

)

Returns the maximum number of simultaneous players of a game. Each player is assumed to have an identical controllers as the others. MAME supports a maximum of 8 simultaneous players so this value will always range from 1 to 8.

Parameters:

gamenum

is the game number of the game

Returns:

the maximum number of simultaneous players of a game

int LibMame_Get_Game_Number

(

const char *

short_name

)

Returns the game number of a game given the short name of the game, or -1 if there is no such game.

Returns:

the game number of a game given the short name of the game, or -1 if there is no such game.

LibMame_OrientationType LibMame_Get_Game_Orientation

(

int

gamenum

)

Returns a value describing the game's original orientation as it was originally played.

Parameters:

gamenum

is the game number of the game

Returns:

a value describing the game's original orientation

LibMame_Image LibMame_Get_Game_Rom	(	int	gamenum,
		int	romnum
	)

This returns information about a ROM that is known to be used by a given game.

Parameters:

gamenum	is the game number of the game
romnum	is the number of the ROM to return

Returns:

information about a ROM that is known to be used by a given game

int LibMame_Get_Game_Rom_Count

(

int

gamenum

)

This returns the number of ROM images (BIOS or game ROMs) that are known for a given game. In general, a game needs all of the ROMs from one BIOS set, plus all ROMs not in any BIOS set, to run.

Parameters:

gamenum

is the game number of the game

Returns:

the number of ROM images (BIOS or game ROMs) that are known for a given game

float LibMame_Get_Game_ScreenRefreshRateHz

(

int

gamenum

)

Returns the original screen refresh rate, in Hz, of the game.

Parameters:

gamenum

is the game number of the game

Returns:

the original screen refresh rate, in Hz, of the game.

LibMame_ScreenResolution LibMame_Get_Game_ScreenResolution

(

int

gamenum

)

Returns the original resolution of the game. If the game is a vector game, then this is an undefined value.

Parameters:

gamenum

is the game number of the game

Returns:

the original resolution of the game.

LibMame_ScreenType LibMame_Get_Game_ScreenType

(

int

gamenum

)

Returns the type of the game's original screen.

Parameters:

gamenum

is the game number of the game

Returns:

the type of the game's original screen.

const char* LibMame_Get_Game_Short_Name

(

int

gamenum

)

Returns the short name of a game.

Parameters:

gamenum

is the game number of the game

Returns:

the short name of a game.

int LibMame_Get_Game_SoundChannels

(

int

gamenum

)

Returns the number of channels of sound that the game supports: 0 means no sound, 1 means mono sound, 2 means stereo sound, anything higher than 2 means surround sound.

Parameters:

gamenum

is the game number of the game

Returns:

the number of channels of sound that the game supports

const char* LibMame_Get_Game_SoundSampleFileName	(	int	gamenum,
		int	samplenum
	)

Returns the file name of a sound sample for a game.

Parameters:

gamenum	is the game number of the game
samplenum	is the sample number of the sample

Returns:

the file name of a sound sample for a game.

int LibMame_Get_Game_SoundSamples_Count

(

int

gamenum

)

Returns the number of sound samples this game uses.

Parameters:

gamenum

is the game number of the game

Returns:

the number of sound samples this game uses.

int LibMame_Get_Game_SoundSamplesSource

(

int

gamenum

)

Returns the game number of the game that has the actual sample files for this game. Some games reference sound sample files from other games, and thus use a different source game number than their own game number.

Parameters:

gamenum

is the game number of the game

Returns:

the game number of the game that has the actual sample files for this game

const char* LibMame_Get_Game_SourceFileName

(

int

gamenum

)

Returns the name of the MAME source file that implements the game.

Parameters:

gamenum

is the game number of the game

Returns:

the name of the MAME source file that implements the game.

int LibMame_Get_Game_WorkingFlags

(

int

gamenum

)

Returns the set of flags describing the game's 'working' status. This is an or'd together set of flags from the LIBMAME_WORKINGFLAGS_XXX symbols. If 0 is returned, then the game is working perfectly, including being able to save game state.

Parameters:

gamenum

is the game number of the game

Returns:

the set of flags describing the game's 'working' status, or 0 if the game is working perfectly, including being able to save game state.

int LibMame_Get_Game_Year_Of_Release

(

int

gamenum

)

Returns the year that a game was released, or -1 if the year is unknown.

Parameters:

gamenum

is the game number of the game

Returns:

the year that a game was released, or -1 if the year is unknown.

const char* LibMame_Get_Version_String

(

)

Returns the string describing the version of mame that this instance of libmame corresponds to.

Returns:

the string describing the version of mame that this instance of libmame corresponds to.

LibMame_InitializeStatus LibMame_Initialize

(

)

Initializes libmame, preparing any resources that the library needs for operation. This function must be called before any other LibMame function is called, and also must be called after any call to LibMame_Deinitialize before any other LibMame function can be called.

Returns:

LibMame_InitializeStatus_Success (which is 0) on success, one of the other LibMame_InitializeStatus_XXX values on error

LibMame_RunGameStatus LibMame_RunGame	(	int	gamenum,
		int	benchmarking,
		const LibMame_RunGameOptions *	options,
		const LibMame_RunGameCallbacks *	cbs,
		void *	callback_data
	)

Runs a game. Currently, this is a non-thread-safe call, so only one thread can be running this at a time. The game will be run until it is instructed to exit by a call to LibMame_RunningGame_ScheduleExit().

Parameters:

gamenum	is the game number of the game to run
benchmarking	is a special parameter which should only be set to nonzero by benchmarking programs that don't interact with the user
options	if non-NULL, provides the options that the game will be run with. If NULL, defaults will be used.
cbs	is the set of callback functions that will be made as the game runs to gather input and to display output
callback_data	is a pointer that is passed into all of the callback functions

Returns:

the status that resulted from running (or attempting to run) the game

void LibMame_RunningGame_ChangeDipswitchValue	(	LibMame_RunningGame *	game,
		const char *	tag,
		uint32_t	mask,
		const char *	value
	)

Sets a new value for a dipswitch. The dipswitch is identified by the name and mask of the LibMame_Dipswitch. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.
tag	is the tag of the dipswitch setting
mask	is the mask of the dipswitch setting
value	is the value, which must be one of the value_names of the LibMame_Dipswitch for this dipswitch

const char* LibMame_RunningGame_GetSpeedText

(

LibMame_RunningGame *

game

)

Returns a text string describing the current speed of the game relative to its ideal speed, and additionally information about the autoskip activation. The returned text is only valid until a subsequent call to this function.

Parameters:

game	is the game that is to be queried; this game is known because it was passed into the StartingUp() callback function.

Returns:

a text string describing the current speed of the game relative to its ideal speed

void LibMame_RunningGame_LoadState	(	LibMame_RunningGame *	game,
		const char *	filename
	)

Requests that the currently running game load a previously saved snapshot of its state from the given file as soon as possible, which will replace the current state. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.
filename	is the filename to read the save state from

void LibMame_RunningGame_SaveState	(	LibMame_RunningGame *	game,
		const char *	filename
	)

Requests that the currently running game save a snapshot of its state to the given file as soon as possible. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.
filename	is the filename to write the save state to

void LibMame_RunningGame_Schedule_Exit

(

LibMame_RunningGame *

game

)

Requests that the currently running game exit as soon as possible. This will cause the LibMame_RunGame call that ran the game to return after the game has exited. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.

void LibMame_RunningGame_Schedule_Hard_Reset

(

LibMame_RunningGame *

game

)

Requests that the currently running game execute a hard reset as soon as possible, which will completely reset the state of the game and return it to its "just powered on" state. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.

void LibMame_RunningGame_Schedule_Pause

(

LibMame_RunningGame *

game

)

Requests that the currently running game be paused. This will result in a call to the Paused callback of the callbacks structure that was passed into LibMame_RunGame() function. The game will unpause when that Paused callback returns. This function may only be called from within the MakeRunningGameCalls callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.

void LibMame_RunningGame_Schedule_Soft_Reset

(

LibMame_RunningGame *

game

)

Requests that the currently running game execute a soft reset as soon as possible, which will reset the state of the game without simulating a power cycle as is done with the hard reset. This function may only be called from within the MakeRunningGameCalls or Paused callback, and not from any other context of execution.

Parameters:

game	is the game that is to be paused; this game is known because it was passed into the StartingUp() callback function.