summaryrefslogtreecommitdiffstatshomepage
path: root/src/emu/gamedrv.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/emu/gamedrv.h')
-rw-r--r--src/emu/gamedrv.h354
1 files changed, 318 insertions, 36 deletions
diff --git a/src/emu/gamedrv.h b/src/emu/gamedrv.h
index 2843e7a36c8..eba153e3410 100644
--- a/src/emu/gamedrv.h
+++ b/src/emu/gamedrv.h
@@ -16,6 +16,9 @@
#include <type_traits>
+/// \defgroup machinedef Machine definition macros
+
+
//**************************************************************************
// CONSTANTS
//**************************************************************************
@@ -59,51 +62,76 @@ struct machine_flags
DECLARE_ENUM_BITWISE_OPERATORS(machine_flags::type);
-// flags for machine drivers
constexpr u64 MACHINE_TYPE_ARCADE = machine_flags::TYPE_ARCADE;
constexpr u64 MACHINE_TYPE_CONSOLE = machine_flags::TYPE_CONSOLE;
constexpr u64 MACHINE_TYPE_COMPUTER = machine_flags::TYPE_COMPUTER;
constexpr u64 MACHINE_TYPE_OTHER = machine_flags::TYPE_OTHER;
-constexpr u64 MACHINE_NOT_WORKING = machine_flags::NOT_WORKING;
-constexpr u64 MACHINE_SUPPORTS_SAVE = machine_flags::SUPPORTS_SAVE;
-constexpr u64 MACHINE_NO_COCKTAIL = machine_flags::NO_COCKTAIL;
-constexpr u64 MACHINE_IS_BIOS_ROOT = machine_flags::IS_BIOS_ROOT;
-constexpr u64 MACHINE_REQUIRES_ARTWORK = machine_flags::REQUIRES_ARTWORK;
-constexpr u64 MACHINE_CLICKABLE_ARTWORK = machine_flags::CLICKABLE_ARTWORK;
-constexpr u64 MACHINE_UNOFFICIAL = machine_flags::UNOFFICIAL;
-constexpr u64 MACHINE_NO_SOUND_HW = machine_flags::NO_SOUND_HW;
-constexpr u64 MACHINE_MECHANICAL = machine_flags::MECHANICAL;
-constexpr u64 MACHINE_IS_INCOMPLETE = machine_flags::IS_INCOMPLETE;
+
+
+/// \addtogroup machinedef
+/// \{
+/// \name System emulation status constants
+///
+/// Constants representing system emulation status flags. May be
+/// combined for use as FLAGS arguments to the #GAME, #GAMEL, #CONS,
+/// #COMP and #SYST macros.
+/// \{
+
+// flags for machine drivers
+constexpr u64 MACHINE_NOT_WORKING = machine_flags::NOT_WORKING; ///< Imperfect emulation prevents using the system as intended
+constexpr u64 MACHINE_SUPPORTS_SAVE = machine_flags::SUPPORTS_SAVE; ///< All devices in the system supports save states (enables auto save feature, and won't show a warning on using save states)
+constexpr u64 MACHINE_NO_COCKTAIL = machine_flags::NO_COCKTAIL; ///< The system supports screen flipping for use in a cocktail cabinet, but this feature is not properly emulated
+constexpr u64 MACHINE_IS_BIOS_ROOT = machine_flags::IS_BIOS_ROOT; ///< The system represents an empty system board of some kind - clones are treated as separate systems rather than variants
+constexpr u64 MACHINE_REQUIRES_ARTWORK = machine_flags::REQUIRES_ARTWORK; ///< The system requires external artwork for key functionality
+constexpr u64 MACHINE_CLICKABLE_ARTWORK = machine_flags::CLICKABLE_ARTWORK; ///< Enables pointer display for the system to facilitate using clickable artwork
+constexpr u64 MACHINE_UNOFFICIAL = machine_flags::UNOFFICIAL; ///< The system represents an after-market or end-user modification to a system
+constexpr u64 MACHINE_NO_SOUND_HW = machine_flags::NO_SOUND_HW; ///< The system has no sound output capability
+constexpr u64 MACHINE_MECHANICAL = machine_flags::MECHANICAL; ///< The system depends on mechanical features for key functionality
+constexpr u64 MACHINE_IS_INCOMPLETE = machine_flags::IS_INCOMPLETE; ///< The system represents an incomplete prototype
// flags that map to device feature flags
-constexpr u64 MACHINE_UNEMULATED_PROTECTION = 0x00000001'00000000; // game's protection not fully emulated
-constexpr u64 MACHINE_WRONG_COLORS = 0x00000002'00000000; // colors are totally wrong
-constexpr u64 MACHINE_IMPERFECT_COLORS = 0x00000004'00000000; // colors are not 100% accurate, but close
-constexpr u64 MACHINE_IMPERFECT_GRAPHICS = 0x00000008'00000000; // graphics are wrong/incomplete
-constexpr u64 MACHINE_NO_SOUND = 0x00000010'00000000; // sound is missing
-constexpr u64 MACHINE_IMPERFECT_SOUND = 0x00000020'00000000; // sound is known to be wrong
-constexpr u64 MACHINE_IMPERFECT_CONTROLS = 0x00000040'00000000; // controls are known to be imperfectly emulated
-constexpr u64 MACHINE_NODEVICE_MICROPHONE = 0x00000080'00000000; // any game/system that has unemulated audio capture device
-constexpr u64 MACHINE_NODEVICE_PRINTER = 0x00000100'00000000; // any game/system that has unemulated hardcopy output device
-constexpr u64 MACHINE_NODEVICE_LAN = 0x00000200'00000000; // any game/system that has unemulated local networking
-constexpr u64 MACHINE_IMPERFECT_TIMING = 0x00000400'00000000; // timing is known to be imperfectly emulated
+constexpr u64 MACHINE_UNEMULATED_PROTECTION = 0x00000001'00000000; ///< Some form of protection is imperfectly emulated (e.g. copy protection or anti-tampering)
+constexpr u64 MACHINE_WRONG_COLORS = 0x00000002'00000000; ///< Colours are completely wrong
+constexpr u64 MACHINE_IMPERFECT_COLORS = 0x00000004'00000000; ///< Colours are close but not completely accurate
+constexpr u64 MACHINE_IMPERFECT_GRAPHICS = 0x00000008'00000000; ///< Graphics are emulated incorrectly for the system
+constexpr u64 MACHINE_NO_SOUND = 0x00000010'00000000; ///< The system has sound output, but it is not emulated
+constexpr u64 MACHINE_IMPERFECT_SOUND = 0x00000020'00000000; ///< Sound is known to be imperfectly emulated for the system
+constexpr u64 MACHINE_IMPERFECT_CONTROLS = 0x00000040'00000000; ///< Controls or inputs are emulated imperfectly for the system
+constexpr u64 MACHINE_NODEVICE_MICROPHONE = 0x00000080'00000000; ///< The system has unemulated audio capture functionality
+constexpr u64 MACHINE_NODEVICE_PRINTER = 0x00000100'00000000; ///< The system has unemulated printer functionality
+constexpr u64 MACHINE_NODEVICE_LAN = 0x00000200'00000000; ///< The system has unemulated local area networking
+constexpr u64 MACHINE_IMPERFECT_TIMING = 0x00000400'00000000; ///< Timing is known to be imperfectly emulated for the system
// useful combinations of flags
-constexpr u64 MACHINE_IS_SKELETON = MACHINE_NO_SOUND | MACHINE_NOT_WORKING; // flag combination for skeleton drivers
+constexpr u64 MACHINE_IS_SKELETON = MACHINE_NO_SOUND | MACHINE_NOT_WORKING; ///< Useful combination of flags for preliminary systems
constexpr u64 MACHINE_IS_SKELETON_MECHANICAL = MACHINE_IS_SKELETON | MACHINE_MECHANICAL | MACHINE_REQUIRES_ARTWORK; // flag combination for skeleton mechanical machines
+/// \}
+/// \}
+
//**************************************************************************
// TYPE DEFINITIONS
//**************************************************************************
-// static POD structure describing each game driver entry
+/// \brief Static system description
+///
+/// A plain data structure providing static information about an system.
+/// Used to allow multiple systems to be implemented using a single
+/// system device class (an implementation of #driver_device).
class game_driver
{
public:
typedef void (*machine_creator_wrapper)(machine_config &, device_t &);
typedef void (*driver_init_wrapper)(device_t &);
+ /// \brief Get unemulated system features
+ ///
+ /// Converts system flags corresponding to unemulated device
+ /// features to the a device feature type bit field.
+ /// \param [in] flags A system flags bit field.
+ /// \return A device feature type bit field corresponding to
+ /// unemulated features declared in the \p flags argument.
static constexpr device_t::feature_type unemulated_features(u64 flags)
{
return
@@ -114,6 +142,14 @@ public:
((flags & MACHINE_NODEVICE_LAN) ? device_t::feature::LAN : device_t::feature::NONE);
}
+ /// \brief Get imperfectly emulated system features
+ ///
+ /// Converts system flags corresponding to imperfectly emulated
+ /// device features to the a device feature type bit field.
+ /// \param [in] flags A system flags bit field.
+ /// \return A device feature type bit field corresponding to
+ /// imperfectly emulated features declared in the \p flags
+ /// argument.
static constexpr device_t::feature_type imperfect_features(u64 flags)
{
return
@@ -126,7 +162,7 @@ public:
}
device_type type; // static type info for driver class
- const char * parent; // if this is a clone, the name of the parent
+ const char * parent; // name of the parent or BIOS system if applicable
const char * year; // year the game was released
const char * manufacturer; // manufacturer of the game
machine_creator_wrapper machine_creator; // machine driver tokens
@@ -136,7 +172,7 @@ public:
const char * compatible_with;
const internal_layout * default_layout; // default internally defined layout
machine_flags::type flags; // orientation and other flags; see defines above
- char name[MAX_DRIVER_NAME_CHARS + 1]; // short name of the game
+ char name[MAX_DRIVER_NAME_CHARS + 1]; // short name of the system
};
@@ -164,9 +200,61 @@ driver_device_creator< \
game_driver::unemulated_features(FLAGS), \
game_driver::imperfect_features(FLAGS)>
-// standard GAME() macro
-#define GAME(YEAR,NAME,PARENT,MACHINE,INPUT,CLASS,INIT,MONITOR,COMPANY,FULLNAME,FLAGS) \
-GAME_DRIVER_TRAITS(NAME,FULLNAME) \
+
+/// \addtogroup machinedef
+/// \{
+
+/// \brief Define a "game" system
+///
+/// Use this macro to define most systems intended for public use,
+/// including arcade games, gambling machines, vending machines, and
+/// information kiosks. Muse be used in the global namespace.
+///
+/// Creates an appropriately named and populated #game_driver structure
+/// describing the system.
+/// \param YEAR The year that the system was first made available. Must
+/// be a token containing only the digits zero to nine, question mark
+/// and plus sign.
+/// \param NAME The short name of the system, used for identification,
+/// and in filesystem paths for assets and data. Must be a token no
+/// longer than sixteen characters, containing only ASCII lowercase
+/// letters, digits and underscores. Must be globally unique across
+/// systems and devices.
+/// \param PARENT Short name of the parent or BIOS system if applicable,
+/// or a single digit zero otherwise.
+/// \param MACHINE Function used to buid machine configuration for the
+/// system. Must be a public member function of the system device
+/// class (\p CLASS argument), returning void and taking a reference
+/// to a #machine_config object as a parameter.
+/// \param INPUT Input port definitions for the root device of the
+/// system, usually defined using #INPUT_PORTS_START and associated
+/// macros.
+/// \param CLASS Class to instantiate as the root device of the system.
+/// Must be an implementation of #driver_device.
+/// \param INIT Initialisation function called after all child devices
+/// have started, but before the driver start functions are called.
+/// Often used for tasks like decrypting ROMs. Must be a public
+/// member function of the system device class (\p CLASS argument),
+/// returning void and accepting no parameters. The function
+/// #driver_device::empty_init is supplied for systems that don't need
+/// to perform additional tasks.
+/// \param MONITOR Screen orientation flags applied to all screens in
+/// the system, after the individual screens' orientation flags are
+/// applied. Usually one #ROT0, #ROT90, #ROT180 or #ROT270.
+/// \param COMPANY Name of the developer or distributor of the system.
+/// Must be a string.
+/// \param FULLNAME Display name for the system. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \param FLAGS Bitwise combination of emulation status flags for the
+/// system, in addition to flags supplied by the system device class
+/// (see #device_t::unemulated_features and
+/// #device_t::imperfect_features). It is advisable to supply
+/// unemulated and imperfectly emulated feature flags that apply to
+/// all systems implemented using the class in the class itself to
+/// avoid repetition.
+/// \sa GAMEL CONS COMP SYST
+#define GAME(YEAR, NAME, PARENT, MACHINE, INPUT, CLASS, INIT, MONITOR, COMPANY, FULLNAME, FLAGS) \
+GAME_DRIVER_TRAITS(NAME, FULLNAME) \
extern game_driver const GAME_NAME(NAME) \
{ \
GAME_DRIVER_TYPE(NAME, CLASS, FLAGS), \
@@ -183,9 +271,62 @@ extern game_driver const GAME_NAME(NAME) \
#NAME \
};
-// standard macro with additional layout
-#define GAMEL(YEAR,NAME,PARENT,MACHINE,INPUT,CLASS,INIT,MONITOR,COMPANY,FULLNAME,FLAGS,LAYOUT) \
-GAME_DRIVER_TRAITS(NAME,FULLNAME) \
+
+/// \brief Define a "game" system with an additional internal layout
+///
+/// Equivalent to the #GAME macro, but with the additional ability to
+/// supply system-specific internal artwork layout data. Views from the
+/// system-specific layout are available in addition to any views from
+/// layout data specified in the machine configuration. Must be used in
+/// the global namespace.
+///
+/// Creates an appropriately named and populated #game_driver structure
+/// describing the system.
+/// \param YEAR The year that the system was first made available. Must
+/// be a token containing only the digits zero to nine, question mark
+/// and plus sign.
+/// \param NAME The short name of the system, used for identification,
+/// and in filesystem paths for assets and data. Must be a token no
+/// longer than sixteen characters, containing only ASCII lowercase
+/// letters, digits and underscores. Must be globally unique across
+/// systems and devices.
+/// \param PARENT Short name of the parent or BIOS system if applicable,
+/// or a single digit zero otherwise.
+/// \param MACHINE Function used to buid machine configuration for the
+/// system. Must be a public member function of the system device
+/// class (\p CLASS argument), returning void and taking a reference
+/// to a #machine_config object as a parameter.
+/// \param INPUT Input port definitions for the root device of the
+/// system, usually defined using #INPUT_PORTS_START and associated
+/// macros.
+/// \param CLASS Class to instantiate as the root device of the system.
+/// Must be an implementation of #driver_device.
+/// \param INIT Initialisation function called after all child devices
+/// have started, but before the driver start functions are called.
+/// Often used for tasks like decrypting ROMs. Must be a public
+/// member function of the system device class (\p CLASS argument),
+/// returning void and accepting no parameters. The function
+/// #driver_device::empty_init is supplied for systems that don't need
+/// to perform additional tasks.
+/// \param MONITOR Screen orientation flags applied to all screens in
+/// the system, after the individual screens' orientation flags are
+/// applied. Usually one #ROT0, #ROT90, #ROT180 or #ROT270.
+/// \param COMPANY Name of the developer or distributor of the system.
+/// Must be a string.
+/// \param FULLNAME Display name for the system. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \param FLAGS Bitwise combination of emulation status flags for the
+/// system, in addition to flags supplied by the system device class
+/// (see #device_t::unemulated_features and
+/// #device_t::imperfect_features). It is advisable to supply
+/// unemulated and imperfectly emulated feature flags that apply to
+/// all systems implemented using the class in the class itself to
+/// avoid repetition.
+/// \param LAYOUT An #internal_layout structure providing additional
+/// internal artwork for the system.
+/// \sa GAME CONS COMP SYST
+#define GAMEL(YEAR, NAME, PARENT, MACHINE, INPUT, CLASS, INIT, MONITOR, COMPANY, FULLNAME, FLAGS, LAYOUT) \
+GAME_DRIVER_TRAITS(NAME, FULLNAME) \
extern game_driver const GAME_NAME(NAME) \
{ \
GAME_DRIVER_TYPE(NAME, CLASS, FLAGS), \
@@ -203,8 +344,54 @@ extern game_driver const GAME_NAME(NAME) \
};
-// standard console definition macro
-#define CONS(YEAR,NAME,PARENT,COMPAT,MACHINE,INPUT,CLASS,INIT,COMPANY,FULLNAME,FLAGS) \
+/// \brief Define a "console" system
+///
+/// Use this macro to define appliance-like entertainment systems
+/// designed for domestic use. Must be used in the global namespace.
+///
+/// Creates an appropriately named and populated #game_driver structure
+/// describing the system.
+/// \param YEAR The year that the system was first made available. Must
+/// be a token containing only the digits zero to nine, question mark
+/// and plus sign.
+/// \param NAME The short name of the system, used for identification,
+/// and in filesystem paths for assets and data. Must be a token no
+/// longer than sixteen characters, containing only ASCII lowercase
+/// letters, digits and underscores. Must be globally unique across
+/// systems and devices.
+/// \param PARENT Short name of the parent or BIOS system if applicable,
+/// or a single digit zero otherwise.
+/// \param COMPAT Short name of a system that this system is compatible
+/// with if applicable, or a single digit zero otherwise.
+/// \param MACHINE Function used to buid machine configuration for the
+/// system. Must be a public member function of the system device
+/// class (\p CLASS argument), returning void and taking a reference
+/// to a #machine_config object as a parameter.
+/// \param INPUT Input port definitions for the root device of the
+/// system, usually defined using #INPUT_PORTS_START and associated
+/// macros.
+/// \param CLASS Class to instantiate as the root device of the system.
+/// Must be an implementation of #driver_device.
+/// \param INIT Initialisation function called after all child devices
+/// have started, but before the driver start functions are called.
+/// Often used for tasks like decrypting ROMs. Must be a public
+/// member function of the system device class (\p CLASS argument),
+/// returning void and accepting no parameters. The function
+/// #driver_device::empty_init is supplied for systems that don't need
+/// to perform additional tasks.
+/// \param COMPANY Name of the developer or distributor of the system.
+/// Must be a string.
+/// \param FULLNAME Display name for the system. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \param FLAGS Bitwise combination of emulation status flags for the
+/// system, in addition to flags supplied by the system device class
+/// (see #device_t::unemulated_features and
+/// #device_t::imperfect_features). It is advisable to supply
+/// unemulated and imperfectly emulated feature flags that apply to
+/// all systems implemented using the class in the class itself to
+/// avoid repetition. Screen orientation flags may be included here.
+/// \sa GAME GAMEL COMP SYST
+#define CONS(YEAR, NAME, PARENT, COMPAT, MACHINE, INPUT, CLASS, INIT, COMPANY, FULLNAME, FLAGS) \
GAME_DRIVER_TRAITS(NAME,FULLNAME) \
extern game_driver const GAME_NAME(NAME) \
{ \
@@ -222,7 +409,54 @@ extern game_driver const GAME_NAME(NAME) \
#NAME \
};
-// standard computer definition macro
+
+/// \brief Define a "computer" system
+///
+/// Use this macro to define computer-like systems. Must be used in the
+/// global namespace.
+///
+/// Creates an appropriately named and populated #game_driver structure
+/// describing the system.
+/// \param YEAR The year that the system was first made available. Must
+/// be a token containing only the digits zero to nine, question mark
+/// and plus sign.
+/// \param NAME The short name of the system, used for identification,
+/// and in filesystem paths for assets and data. Must be a token no
+/// longer than sixteen characters, containing only ASCII lowercase
+/// letters, digits and underscores. Must be globally unique across
+/// systems and devices.
+/// \param PARENT Short name of the parent or BIOS system if applicable,
+/// or a single digit zero otherwise.
+/// \param COMPAT Short name of a system that this system is compatible
+/// with if applicable, or a single digit zero otherwise.
+/// \param MACHINE Function used to buid machine configuration for the
+/// system. Must be a public member function of the system device
+/// class (\p CLASS argument), returning void and taking a reference
+/// to a #machine_config object as a parameter.
+/// \param INPUT Input port definitions for the root device of the
+/// system, usually defined using #INPUT_PORTS_START and associated
+/// macros.
+/// \param CLASS Class to instantiate as the root device of the system.
+/// Must be an implementation of #driver_device.
+/// \param INIT Initialisation function called after all child devices
+/// have started, but before the driver start functions are called.
+/// Often used for tasks like decrypting ROMs. Must be a public
+/// member function of the system device class (\p CLASS argument),
+/// returning void and accepting no parameters. The function
+/// #driver_device::empty_init is supplied for systems that don't need
+/// to perform additional tasks.
+/// \param COMPANY Name of the developer or distributor of the system.
+/// Must be a string.
+/// \param FULLNAME Display name for the system. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \param FLAGS Bitwise combination of emulation status flags for the
+/// system, in addition to flags supplied by the system device class
+/// (see #device_t::unemulated_features and
+/// #device_t::imperfect_features). It is advisable to supply
+/// unemulated and imperfectly emulated feature flags that apply to
+/// all systems implemented using the class in the class itself to
+/// avoid repetition. Screen orientation flags may be included here.
+/// \sa GAME GAMEL CONS SYST
#define COMP(YEAR,NAME,PARENT,COMPAT,MACHINE,INPUT,CLASS,INIT,COMPANY,FULLNAME,FLAGS) \
GAME_DRIVER_TRAITS(NAME,FULLNAME) \
extern game_driver const GAME_NAME(NAME) \
@@ -241,7 +475,54 @@ extern game_driver const GAME_NAME(NAME) \
#NAME \
};
-// standard system definition macro
+
+/// \brief Define a generic system
+///
+/// Use this macro to define miscellaneous systems that don't fall into
+/// one of the other categories. Must be used in the global namespace.
+///
+/// Creates an appropriately named and populated #game_driver structure
+/// describing the system.
+/// \param YEAR The year that the system was first made available. Must
+/// be a token containing only the digits zero to nine, question mark
+/// and plus sign.
+/// \param NAME The short name of the system, used for identification,
+/// and in filesystem paths for assets and data. Must be a token no
+/// longer than sixteen characters, containing only ASCII lowercase
+/// letters, digits and underscores. Must be globally unique across
+/// systems and devices.
+/// \param PARENT Short name of the parent or BIOS system if applicable,
+/// or a single digit zero otherwise.
+/// \param COMPAT Short name of a system that this system is compatible
+/// with if applicable, or a single digit zero otherwise.
+/// \param MACHINE Function used to buid machine configuration for the
+/// system. Must be a public member function of the system device
+/// class (\p CLASS argument), returning void and taking a reference
+/// to a #machine_config object as a parameter.
+/// \param INPUT Input port definitions for the root device of the
+/// system, usually defined using #INPUT_PORTS_START and associated
+/// macros.
+/// \param CLASS Class to instantiate as the root device of the system.
+/// Must be an implementation of #driver_device.
+/// \param INIT Initialisation function called after all child devices
+/// have started, but before the driver start functions are called.
+/// Often used for tasks like decrypting ROMs. Must be a public
+/// member function of the system device class (\p CLASS argument),
+/// returning void and accepting no parameters. The function
+/// #driver_device::empty_init is supplied for systems that don't need
+/// to perform additional tasks.
+/// \param COMPANY Name of the developer or distributor of the system.
+/// Must be a string.
+/// \param FULLNAME Display name for the system. Must be a string, and
+/// must be globally unique across systems and devices.
+/// \param FLAGS Bitwise combination of emulation status flags for the
+/// system, in addition to flags supplied by the system device class
+/// (see #device_t::unemulated_features and
+/// #device_t::imperfect_features). It is advisable to supply
+/// unemulated and imperfectly emulated feature flags that apply to
+/// all systems implemented using the class in the class itself to
+/// avoid repetition. Screen orientation flags may be included here.
+/// \sa GAME GAMEL CONS COMP
#define SYST(YEAR,NAME,PARENT,COMPAT,MACHINE,INPUT,CLASS,INIT,COMPANY,FULLNAME,FLAGS) \
GAME_DRIVER_TRAITS(NAME,FULLNAME) \
extern game_driver const GAME_NAME(NAME) \
@@ -260,5 +541,6 @@ extern game_driver const GAME_NAME(NAME) \
#NAME \
};
+/// \}
#endif // MAME_EMU_GAMEDRV_H