summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r--docs/source/techspecs/device_disasm_interface.rst10
-rw-r--r--docs/source/techspecs/device_memory_interface.rst15
-rw-r--r--docs/source/techspecs/floppy.rst8
-rw-r--r--docs/source/techspecs/index.rst29
-rw-r--r--docs/source/techspecs/inputsystem.rst460
-rw-r--r--docs/source/techspecs/layout_files.rst90
-rw-r--r--docs/source/techspecs/layout_script.rst181
-rw-r--r--docs/source/techspecs/luaengine.rst203
-rw-r--r--docs/source/techspecs/luareference.rst3184
-rw-r--r--docs/source/techspecs/m6502.rst10
-rw-r--r--docs/source/techspecs/memory.rst28
-rw-r--r--docs/source/techspecs/naming.rst61
-rw-r--r--docs/source/techspecs/object_finders.rst4
-rw-r--r--docs/source/techspecs/poly_manager.rst2
14 files changed, 714 insertions, 3571 deletions
diff --git a/docs/source/techspecs/device_disasm_interface.rst b/docs/source/techspecs/device_disasm_interface.rst
index beacaf8e6df..a2ab4fa7eec 100644
--- a/docs/source/techspecs/device_disasm_interface.rst
+++ b/docs/source/techspecs/device_disasm_interface.rst
@@ -168,7 +168,7 @@ A CPU core derives from **device_disasm_interface** through
That method must return a pointer to a newly allocated disassembler
object. The caller takes ownership and handles the lifetime.
-THis method will be called at most one in the lifetime of the cpu
+This method will be called at most one in the lifetime of the cpu
object.
4. Disassembler configuration and communication
@@ -184,7 +184,7 @@ model name), feel free to use a parameter. Otherwise derive the
class.
Dynamic configuration must be done by first defining a nested public
-struct called "config" in the disassembler, with virtual destructor
+struct called ``config`` in the disassembler, with virtual destructor
and pure virtual methods to pull the required information. A pointer
to that struct should be passed to the disassembler constructor. The
cpu core should then add a derivation from that config struct and
@@ -195,9 +195,9 @@ the config class to give the information.
----------------
There currently is no way for the debugger GUI to add per-core
-configuration. It is needed for in particular the s2650 and the
-saturn cores. It should go through the cpu core class itself, since
-it's pulled from the config struct.
+configuration. In particular, it is needed for the s2650 and Saturn
+cores. It should go through the cpu core class itself, since it's
+pulled from the config struct.
There is support missing in unidasm for per-cpu configuration. That's
needed for a lot of things, see the unidasm source code for the
diff --git a/docs/source/techspecs/device_memory_interface.rst b/docs/source/techspecs/device_memory_interface.rst
index 2eae46f3906..1f8e2b1c37b 100644
--- a/docs/source/techspecs/device_memory_interface.rst
+++ b/docs/source/techspecs/device_memory_interface.rst
@@ -68,7 +68,7 @@ describing its configuration. Some examples to look up when needed:
The ``has_configured_map`` method allows to test whether an
``address_map`` has been associated with a given space in the
-``memory_space_config`` method . That allows optional memory spaces to
+``memory_space_config`` method. That allows optional memory spaces to
be implemented, such as ``AS_OPCODES`` in certain CPU cores.
@@ -152,14 +152,17 @@ Indicates whether a given space actually exists.
.. code-block:: C++
- bool translate(int spacenum, int intention, offs_t &address);
+ bool translate(int spacenum, int intention, offs_t &address, address_space *&target_space);
Does a logical to physical address translation through the device's
MMU. spacenum gives the space number, intention for the type of the
-future access (``TRANSLATE_(READ\|WRITE\|FETCH)(\|_USER\|_DEBUG)``)
-and address is an in/out parameter holding the address to translate on
-entry and the translated version on return. Should return ``true`` if
-the translation went correctly, or ``false`` if the address is unmapped.
+future access (``TR_(READ\|WRITE\|FETCH)``), address is an in/out
+parameter holding the address to translate on entry and the translated
+version on return, and finally target_space is the actual space the
+access would end up in, which may be in a different device. Should
+return ``true`` if the translation went correctly, or ``false`` if the
+address is unmapped. The call must not change the state of the
+device.
Note that for some historical reason, the device itself must override
the virtual method ``memory_translate`` with the same signature.
diff --git a/docs/source/techspecs/floppy.rst b/docs/source/techspecs/floppy.rst
index 609e5c53013..39060d4eddf 100644
--- a/docs/source/techspecs/floppy.rst
+++ b/docs/source/techspecs/floppy.rst
@@ -23,7 +23,7 @@ The new floppy subsystem aims at emulating the behaviour of floppies and floppy
A floppy disk is a disc that stores magnetic orientations on their surface disposed in a series on concentric circles called tracks or cylinders [1]_. Its main characteristics are its size (goes from a diameter of around 2.8" to 8") , its number of writable sides (1 or 2) and its magnetic resistivity. The magnetic resistivity indicates how close magnetic orientation changes can happen and the information kept. That's one third of what defines the term "density" that is so often used for floppies (the other two are floppy drive head size and bit-level encoding).
-The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tengentially to the track, e.g in the direction or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to).
+The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tangentially to the track, i.e. in the direction of or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc.) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to).
A specific position in the disk rotation triggers an index pulse. That position can be detected through a hole in the surface (very visible in 5.25" and 3" floppies for instance) or through a specific position of the rotating center (3.5" floppies, perhaps others). This index pulse is used to designate the beginning of the track, but is not used by every system. Older 8" floppies have multiple index holes used to mark the beginning of sectors (called hard sectoring) but one of them is positioned differently to be recognized as the track start, and the others are at fixed positions relative to the origin one.
@@ -70,7 +70,7 @@ In every cell there may or may not be a magnetic orientation transition, e.g. a
Of course protections play with that to make formats not reproducible by the system controller, either breaking the three-zeroes rule or playing with the cells durations/sizes.
-Bit endocing is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints.
+Bit encoding is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints.
2.3.1.2. FM encoding
````````````````````
@@ -108,9 +108,9 @@ Other encodings exist, like M2FM, but they're very rare and system-specific.
2.3.1.6. Reading back encoded data
``````````````````````````````````
-Writing encoded data is easy, you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (+/- 2% is not rare) and local perturbations (air turbulence, surface distance...) make the instant speed very variable in general. So to extract the cell values stream the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is build within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows to correct the phase on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used a Phase-Locked Loop (PLL) which vary both phase and window duration to adapt better to wrong rotational speeds, with usually a tolerance of +/- 15%.
+Writing encoded data is easy: you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (±2% is not rare), and local perturbations (air turbulence, surface distance…) make the instantaneous speed very variable in general. So to extract the cell values stream, the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is built within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window, the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows the phase to be corrected on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used Phase-Locked Loops (PLLs) which vary both phase and window duration to adapt better to inaccuarate rotational speeds, usually with a tolerance of ±15%.
-Once the cell data stream is extracted decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream.
+Once the cell data stream is extracted, decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream.
2.3.2. Sector-level organization
diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst
index 40d4048e522..ee41de889d8 100644
--- a/docs/source/techspecs/index.rst
+++ b/docs/source/techspecs/index.rst
@@ -5,19 +5,18 @@ This section covers technical specifications useful to programmers working on
MAME’s source or working on scripts that run within the MAME framework.
.. toctree::
- :titlesonly:
+ :titlesonly:
- naming
- layout_files
- layout_script
- object_finders
- device_memory_interface
- device_rom_interface
- device_disasm_interface
- memory
- floppy
- nscsi
- luaengine
- luareference
- m6502
- poly_manager
+ naming
+ layout_files
+ layout_script
+ object_finders
+ inputsystem
+ device_memory_interface
+ device_rom_interface
+ device_disasm_interface
+ memory
+ floppy
+ nscsi
+ m6502
+ poly_manager
diff --git a/docs/source/techspecs/inputsystem.rst b/docs/source/techspecs/inputsystem.rst
new file mode 100644
index 00000000000..7a027b0ff22
--- /dev/null
+++ b/docs/source/techspecs/inputsystem.rst
@@ -0,0 +1,460 @@
+.. _inputsystem:
+
+Input System
+============
+
+.. contents::
+ :local:
+ :depth: 2
+
+
+.. _inputsystem-intro:
+
+Introduction
+------------
+
+The variety of systems MAME emulates, as well as the variation in host
+systems and peripherals, necessitates a flexible, configurable input
+system.
+
+Note that the input system is concerned with low-level user input.
+High-level user interaction, involving things like text input and
+pointing devices, is handled separately.
+
+
+.. _inputsystem-components:
+
+Components
+----------
+
+From the emulated system’s point of view, the input system has the
+following conceptual components.
+
+Input device
+~~~~~~~~~~~~
+
+Input devices supply input values. An input device typically
+corresponds to a physical device in the host system, for example a
+keyboard, mouse or game controller. However, there isn’t always a
+one-to-one correspondence between input devices and physical devices.
+For example the SDL keyboard provider module aggregates all keyboards
+into a single input device, and the Win32 lightgun provider module can
+present two input devices using input from a single mouse.
+
+Input devices are identified by their device class (keyboard, mouse,
+joystick or lightgun) and device number within the class. Input
+provider modules can also supply an implementation-dependent identifier
+to allow the user to configure stable device numbering.
+
+Note that input devices are unrelated to emulated devices (``device_t``
+implementations) despite the similar name.
+
+Input device item
+~~~~~~~~~~~~~~~~~
+
+Also known as a **control**, and input device item corresponds to a
+input source that produces a single value. This usually corresponds to
+a physical control or sensor, for example a joystick axis, a button or
+an accelerometer.
+
+MAME supports three kinds of controls: **switches**, **absolute axes**
+and **relative axes**:
+
+* Switches produce the value 0 when inactive (released or off) or 1 when
+ active (pressed or on).
+* Absolute axes produce a value normalised to the range -65,536 to
+ 65,536 with zero corresponding to the neutral position.
+* Relative axes produce a value corresponding to the movement since the
+ previous input update. Mouse-like devices scale values to
+ approximately 512 per nominal 100 DPI pixel.
+
+Negative axis values should correspond to directions up, to the left,
+away from the player, or anti-clockwise. For single-ended axes (e.g.
+pedals or displacement-sensitive triggers and buttons), only zero and
+the negative portion of the range should be used.
+
+Switches are used to represent controls that naturally have two distinct
+states, like buttons and toggle switches.
+
+Absolute axes are used to represent controls with a definite range
+and/or neutral position. Examples include steering wheels with limit
+stops, joystick axes, and displacement-sensitive triggers.
+
+Relative axes are used to represent controls with an effectively
+infinite range. Examples include mouse/trackball axes, incremental
+encoder dials, and gyroscopes.
+
+Accelerometers and force sensing joystick axes should be represented as
+absolute axes, even though the range is theoretically open-ended. In
+practice, there is a limit to the range the transducers can report,
+which is usually substantially larger than needed for normal operation.
+
+Input device items are identified by their associated device’s class and
+device number along with an **input item ID**. MAME supplies item IDs
+for common types of controls. Additional controls or controls that do
+not correspond to a common type are dynamically assigned item IDs. MAME
+supports hundreds to items per input device.
+
+I/O port field
+~~~~~~~~~~~~~~
+
+An I/O port field represents an input source in an emulated device or
+system. Most types of I/O port fields can be assigned one or more
+combinations of controls, allowing the user to control the input to
+the emulated system.
+
+Similarly to input device items, there are multiple types of I/O port
+fields:
+
+* **Digital fields** function as switches that produce one of two
+ distinct values. They are used for keyboard keys, eight-way joystick
+ direction switches, toggle switches, photointerruptors and other
+ emulated inputs that function as two-position switches.
+* **Absolute analog fields** have a range with defined minimum, maximum
+ and neutral positions. They are used for analog joystick axes,
+ displacement-sensitive pedals, paddle knobs, and other emulated inputs
+ with a defined range.
+* **Relative analog fields** have a range with defined minimum, maximum
+ and starting positions. On each update, the value accumulates and
+ wraps when it passes either end of the range. Functionally, this is
+ like the output of an up/down counter connected to an incremental
+ encoder. They are used for mouse/trackball axes, steering wheels
+ without limit stops, and other emulated inputs that have no range
+ limits.
+* DIP switch, configuration and adjuster fields allow the user to set
+ the value through MAME’s user interface.
+* Additional special field types are used to produce fixed or
+ programmatically generated values.
+
+A digital field appears to the user as a single assignable input, which
+accepts switch values.
+
+An analog field appears to the user as three assignable inputs: an
+**axis input**, which accepts axis values; and an **increment input**
+and a **decrement input** which accept switch values.
+
+Input manager
+~~~~~~~~~~~~~
+
+The input manager has several responsibilities:
+
+* Tracking the available input devices in the system.
+* Reading input values.
+* Converting between internal identifier values, configuration token
+ strings and display strings.
+
+In practice, emulated devices and systems rarely interact with the input
+manager directly. The most common reason to access the input manager is
+implementing special debug controls, which should be disabled in release
+builds. Plugins that respond to input need to call the input manager to
+read inputs.
+
+I/O port manager
+~~~~~~~~~~~~~~~~
+
+The I/O port manager’s primary responsibilities include:
+
+* Managing assignments of controls to I/O port fields and user interface
+ actions.
+* Reading input values via the input manager and updating I/O port field
+ values.
+
+Like the input manager, the I/O port manager is largely transparent to
+emulated devices and systems. You just need to set up your I/O ports
+and fields, and the I/O port manager handles the rest.
+
+
+.. _inputsystem-structures:
+
+Structures and data types
+-------------------------
+
+The following data types are used for dealing with input.
+
+Input code
+~~~~~~~~~~
+
+An input code specifies an input device item and how it should be
+interpreted. It is a tuple consisting of the following values: **device
+class**, **device number**, **item class**, **item modifier** and **item
+ID**:
+
+* The device class, device number and item ID together identify the
+ input device item to read.
+* The item class specifies the type of output value desired: switch,
+ absolute axis or relative axis. Axis values can be converted to
+ switch values by specifying an appropriate modifier.
+* The modifier specifies how a value should be interpreted. Valid
+ options depend on the type of input device item and the specified
+ item class.
+
+If the specified input item is a switch, it can only be read using the
+switch class, and no modifiers are supported. Attempting to read a
+switch as an absolute or relative axis always returns zero.
+
+If the specified input item is an absolute axis, it can be read as an
+absolute axis or as a switch:
+
+* Reading an absolute axis item as an absolute axis returns the current
+ state of the control, potentially transformed if a modifier is
+ specified. Supported modifiers are **reverse** to reverse the range
+ of the control, **positive** to map the positive range of the control
+ onto the output (zero corresponding to -65,536 and 65,536
+ corresponding to 65,536), and **negative** to map the negative range
+ of the control onto the output (zero corresponding to -65,536 and
+ -65,536 corresponding to 65,536).
+* Reading an absolute axis item as a switch returns zero or 1 depending
+ on whether the control is past a threshold in the direction specified
+ by the modifier. Use the **negative** modifier to return 1 when the
+ control is beyond the threshold in the negative direction (up or
+ left), or the **positive** modifier to return 1 when the control is
+ beyond the threshold in the positive direction (down or right). There
+ are two special pairs of modifiers, **left**/**right** and
+ **up**/**down** that are only applicable to the primary X/Y axes of
+ joystick devices. The user can specify a *joystick map* to control
+ how these modifiers interpret joystick movement.
+* Attempting to read an absolute axis item as a relative axis always
+ returns zero.
+
+If the specified input item is a relative axis, it can be read as a
+relative axis or as a switch:
+
+* Reading a relative axis item as a relative axis returns the change in
+ value since the last input update. The only supported modifier is
+ **reverse**, which negates the value, reversing the direction.
+* Reading a relative axis as a switch returns 1 if the control moved in
+ the direction specified by the modifier since the last input update.
+ Use the **negative**/**left**/**up** modifiers to return 1 when the
+ control has been moved in the negative direction (up or left), or the
+ **positive**/**right**/**down** modifiers to return 1 when the control
+ has moved in the positive direction (down or right).
+* Attempting to read a relative axis item as an absolute axis always
+ returns zero.
+
+There are also special input codes used for specifying how multiple
+controls are to be combined in an input sequence.
+
+The most common place you’ll encounter input codes in device and system
+driver code is when specifying initial assignments for I/O port fields
+that don’t have default assignments supplied by the core. The
+``PORT_CODE`` macro is used for this purpose.
+
+MAME provides macros and helper functions for producing commonly used
+input codes, including standard keyboard keys and
+mouse/joystick/lightgun axes and buttons.
+
+Input sequence
+~~~~~~~~~~~~~~
+
+An input sequence specifies a combination controls that can be assigned
+to an input. The name refers to the fact that it is implemented as a
+sequence container with input codes as elements. It is somewhat
+misleading, as input sequences are interpreted using instantaneous
+control values. Input sequences are interpreted differently for switch
+and axis input.
+
+Input sequences for switch input must only contain input codes with the
+item class set to switch along with the special **or** and **not** input
+codes. The input sequence is interpreted using sum-of-products logic.
+A **not** code causes the value returned by the immediately following
+code to be inverted. The conjunction of values returned by successive
+codes is evaluated until an **or** code is encountered. If the current
+value is 1 when an **or** code is encountered it is returned, otherwise
+evaluation continues.
+
+Input sequences for axis input can contain input codes with the item
+class set to switch, absolute axis or relative axis along with the
+special **or** and **not** codes. It’s helpful to think of the input
+sequence as containing one or more groups of input codes separated by
+**or** codes:
+
+* A **not** code causes the value returned by an immediately following
+ switch code to be inverted. It has no effect on absolute or relative
+ axis codes.
+* Within a group, the conjunction of the values returned by switch codes
+ is evaluated. If it is zero, the group is ignored.
+* Within a group, multiple axis values of the same type are summed.
+ Values returned by absolute axis codes are summed, and values returned
+ by relative axis codes are summed.
+* If any absolute axis code in a group returns a non-zero value, the sum
+ of relative axes in the group is ignored. Any non-zero absolute axis
+ value takes precedence over relative axis values.
+* The same logic is applied when combining group values: group values
+ produced from the same axis type are summed, and values produced from
+ absolute axes take precedence over values produced from relative axes.
+* After the group values are summed, if the value was produced from
+ absolute axes it is clamped to the range -65,536 to 65,536 (values
+ produced from relative axes are not clamped).
+
+Emulation code rarely needs to deal with input sequences directly, as
+they’re handled internally between the I/O port manager and input
+manager. The input manager also converts input sequences to and from
+the token strings stored in configuration files and produces text for
+displaying input sequences to users.
+
+Plugins with controls or hotkeys need to use input sequences to allow
+configuration. Utility classes are provided to allow input sequences to
+be entered by the user in a consistent way, and the input manager can be
+used for conversions to and from configuration and display strings. It
+is very rare to need to directly manipulate input sequences.
+
+
+.. _inputsystem-providermodules:
+
+Input provider modules
+----------------------
+
+Input provider modules are part of the OS-dependent layer (OSD), and are
+not directly exposed to emulation and user interface code. Input
+provider modules are responsible for detecting available host input
+devices, setting up input devices for the input manager, and providing
+callbacks to read the current state of input device items. Input
+provider modules may also provide additional default input assignments
+suitable for host input devices that are present.
+
+The user is given a choice of input modules to use. One input provider
+module is used for each of the four input device classes (keyboard,
+mouse, joystick and lightgun). The available modules depend on the host
+operating system and OSD implementation. Different modules may use
+different APIs, support different kinds of devices, or present devices
+in different ways.
+
+
+.. _inputsystem-playerpositions:
+
+Player positions
+----------------
+
+MAME uses a concept called *player positions* to help manage input
+assignments. The number of player positions supported depends on the
+I/O port field type:
+
+* Ten player positions are supported for common game inputs, including
+ joystick, pedal, paddle, dial, trackball, lightgun and mouse.
+* Four player positions are supported for mahjong and hanafuda inputs.
+* One player position is supported for gambling system inputs.
+* Other inputs do not use player positions. This includes coin slots,
+ arcade start buttons, tilt switches, service switches and
+ keyboard/keypad keys.
+
+The user can configure default input assignments per player position for
+supported I/O port field types which are saved in the file
+**default.cfg**. These assignments are used for all systems unless the
+device/system driver supplies its own default assignments, or the user
+configures system-specific input assignments.
+
+In order to facilitate development of reusable emulated devices with
+inputs, particularly slot devices, the I/O port manager automatically
+renumbers player positions when setting up the emulated system:
+
+* The I/O port manager starts at player position 1 and begins
+ iterating the emulated device tree in depth first order, starting from
+ the root device.
+* If a device has I/O port fields that support player positions, they
+ are renumbered to start from the I/O port manager’s current player
+ position.
+* Before advancing to the next device, the I/O port manager sets its
+ current player position to the last seen player position plus one.
+
+For a simple example, consider what happens when you run a Sega Mega
+Drive console with two game pads connected:
+
+* The I/O port manager starts at player position 1 at the root device.
+* The first device encountered with I/O port fields that support player
+ positions is the first game pad. The inputs are renumbered to start
+ at player position 1. This has no visible effect, as the I/O port
+ fields are initially numbered starting at player position 1.
+* Before moving to the next device, the I/O port manager sets its
+ current player position to 2 (the last player position seen plus one).
+* The next device encountered with I/O port fields that support player
+ positions is the second game pad. The inputs are renumbered to start
+ at player position 2. This avoids I/O port field type conflicts with
+ the first game pad.
+* Before moving to the next device, the I/O port manager sets its
+ current player position to 3 (the last player position seen plus one).
+* No more devices with I/O port fields that support player positions are
+ encountered.
+
+
+.. _inputsystem-updatingfields:
+
+Updating I/O port fields
+------------------------
+
+The I/O port manager updates I/O port fields once for each video frame
+produced by the first emulated screen in the system. How a field is
+updated depends on whether it is a digital or analog field.
+
+Updating digital fields
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Updating digital I/O port fields is simple:
+
+* The I/O port manager reads the current value for the field’s assigned
+ input sequence (via the input manager).
+* If the value is zero, the field’s default value is set.
+* If the value is non-zero, the binary complement of the field’s default
+ value is set.
+
+Updating absolute analog fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Updating absolute analog I/O port fields is more complex due to the need
+to support a variety of control setups:
+
+* The I/O port manager reads the current value for the field’s assigned
+ axis input sequence (via the input manager).
+* If the current value changed since the last update and the input
+ device item that produced the current value was an absolute axis, the
+ field’s value is set to the current value scaled to the correct range,
+ and no further processing is performed.
+* If the current value is non-zero and the input device item that
+ produced the current value was a relative axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ increment input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is added
+ to its value, scaled by its sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ decrement input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is
+ subtracted from its value, scaled by its sensitivity setting.
+* If the current axis input, increment input and decrement input values
+ are all zero, but either or both of the increment input and decrement
+ input values were non-zero the last time the field’s value changed in
+ response to user input, the field’s auto-centring speed setting value
+ is added to or subtracted from its value to move it toward its default
+ value.
+
+Note that the sensitivity setting value for absolute analog fields
+affects the response to relative axis input device items and
+increment/decrement inputs, but it does not affect the response to
+absolute axis input device items or the auto-centring speed.
+
+Updating relative analog fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Relative analog I/O port fields also need special handling to cater for
+multiple control setups, but they are a little simpler than absolute
+analog fields:
+
+* The I/O port manager reads the current value for the field’s assigned
+ axis input sequence (via the input manager).
+* If the current value is non-zero and the input device item that
+ produced the current value was an absolute axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting,
+ and no further processing is performed.
+* If the current value is non-zero and the input device item that
+ produced the current value was a relative axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ increment input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is added
+ to its value, scaled by its sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ decrement input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is
+ subtracted from its value, scaled by its sensitivity setting.
+
+Note that the sensitivity setting value for relative analog fields
+affects the response to all user input.
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index c43a7df8e1b..a014756a32b 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -396,8 +396,8 @@ Elements
~~~~~~~~
Elements are one of the basic visual objects that may be arranged, along with
-screens, to make up a view. Elements may be built up one or more *components*,
-but an element is treated as as single surface when building the scene graph
+screens, to make up a view. Elements may be built up of one or more *components*,
+but an element is treated as a single surface when building the scene graph
and rendering. An element may be used in multiple views, and may be used
multiple times within a view.
@@ -497,15 +497,15 @@ image
human-readable SVG graphics. A ``file`` attribute or ``data`` child element
must be supplied; it is an error if neither or both are supplied.
- If the ``alphafile`` attribute refers refers to a file, it must have the
- same dimensions (in pixels) as the file referred to by the ``file``
- attribute, and must have a bit depth no greater than eight bits per channel
- per pixel. The intensity from this image (brightness) is copied to the
- alpha channel, with full intensity (white in a greyscale image)
- corresponding to fully opaque, and black corresponding to fully transparent.
- The ``alphafile`` attribute will be ignored if the ``file`` attribute refers
- to an SVG image or the ``data`` child element contains SVG data; it is only
- used in conjunction with bitmap images.
+ If the ``alphafile`` attribute refers to a file, it must have the same
+ dimensions (in pixels) as the file referred to by the ``file`` attribute,
+ and must have a bit depth no greater than eight bits per channel per pixel.
+ The intensity from this image (brightness) is copied to the alpha channel,
+ with full intensity (white in a greyscale image) corresponding to fully
+ opaque, and black corresponding to fully transparent. The ``alphafile``
+ attribute will be ignored if the ``file`` attribute refers to an SVG image
+ or the ``data`` child element contains SVG data; it is only used in
+ conjunction with bitmap images.
The image file(s) should be placed in the same directory/archive as the
layout file. Image file formats are detected by examining the content of
@@ -517,21 +517,6 @@ text
be an integer, where 0 (zero) means centred, 1 (one) means left-aligned, and
2 (two) means right-aligned. If the ``align`` attribute is absent, the text
will be centred.
-dotmatrix
- Draws an eight-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrix5dot
- Draws a five-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrixdot
- Draws a single element of a dot matrix display as a circular pixels in the
- specified colour. The least significant bit of the element’s state
- determines whether the pixel is lit. An unlit pixel is drawn at low
- intensity (0x20/0xff).
led7seg
Draws a standard seven-segment (plus decimal point) digital LED/fluorescent
display in the specified colour. The low eight bits of the element’s state
@@ -539,14 +524,6 @@ led7seg
the bits correspond to the top segment, the upper right-hand segment,
continuing clockwise to the upper left segment, the middle bar, and the
decimal point. Unlit segments are drawn at low intensity (0x20/0xff).
-led8seg_gts1
- Draws an eight-segment digital fluorescent display of the type used in
- Gottlieb System 1 pinball machines (actually a Futaba part). Compared to
- standard seven-segment displays, these displays have no decimal point, the
- horizontal middle bar is broken in the centre, and there is a broken
- vertical middle bar controlled by the bit that would control the decimal
- point in a standard seven-segment display. Unlit segments are drawn at low
- intensity (0x20/0xff).
led14seg
Draws a standard fourteen-segment alphanumeric LED/fluorescent display in
the specified colour. The low fourteen bits of the element’s state control
@@ -713,6 +690,11 @@ element. This means a view can reference elements and groups that appear after
it in the file, and parameters from the enclosing scope will have their final
values from the end of the ``mamelayout`` element.
+A ``view`` element may have a ``showpointers`` attribute to set whether mouse
+and pen pointers should be shown for the view. If present, the value must be
+either ``yes`` or ``no``. If the ``showpointers`` attribute is not present, pen
+and mouse pointers are shown for views that contain items bound to I/O ports.
+
The following child elements are allowed inside a ``view`` element:
bounds
@@ -754,7 +736,7 @@ screen
collection
Adds screens and/or items in a collection that can be shown or hidden by the
user (see :ref:`layfile-parts-collections`). The name of the collection is
- specified using the required ``name`` attribute.. There is a limit of 32
+ specified using the required ``name`` attribute. There is a limit of 32
collections per view.
group
Adds the content of the group to the view (see :ref:`layfile-parts-groups`).
@@ -1211,7 +1193,7 @@ Clickable items
If a view item (``element`` or ``screen`` element) has ``inputtag`` and
``inputmask`` attribute values that correspond to a digital switch field in the
emulated system, clicking the element will activate the switch. The switch
-will remain active as long as the mouse button is held down and the pointer is
+will remain active as long as the primary button is held down and the pointer is
within the item’s current bounds. (Note that the bounds may change depending on
the item’s animation state, see :ref:`layfile-interact-itemanim`).
@@ -1220,6 +1202,12 @@ device that caused the layout file to be loaded. The ``inputmask`` attribute
must be an integer specifying the bits of the I/O port field that the item
should activate. This sample shows instantiation of clickable buttons:
+The ``clickthrough`` attribute controls whether clicks can pass through the view
+item to other view items drawn above it. The ``clickthrough`` attribute must be
+``yes`` or ``no`` if present. The default is ``no`` (clicks do not pass
+through) for view items with ``inputtag`` and ``inputmask`` attributes, and
+``yes`` (clicks pass through) for other view items.
+
.. code-block:: XML
<element ref="btn_3" inputtag="X2" inputmask="0x10">
@@ -1232,9 +1220,8 @@ should activate. This sample shows instantiation of clickable buttons:
<bounds x="1.775" y="5.375" width="1.0" height="1.0" />
</element>
-When handling mouse input, MAME treats all layout elements as being rectangular,
-and only activates the first clickable item whose area includes the location of
-the mouse pointer.
+When handling pointer input, MAME treats all layout elements as being
+rectangular.
.. _layfile-interact-elemstate:
@@ -1292,7 +1279,7 @@ View item animation
Items’ colour and position/size within their containing view may be animated.
This is achieved by supplying multiple ``color`` and/or ``bounds`` child
elements with ``state`` attributes. The ``state`` attribute of each ``color``
-or ``bounds`` child element must be a non-negative integer. Withing a view
+or ``bounds`` child element must be a non-negative integer. Within a view
item, no two ``color`` elements may have equal state ``state`` attributes, and
no two ``bounds`` elements may have equal ``state`` attributes.
@@ -1484,33 +1471,36 @@ Example layout files
These layout files demonstrate various artwork system features. They are all
internal layouts included in MAME.
-`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0235>`_
+`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0261>`_
A simple case of using translucent colour overlays to visually separate and
highlight elements on a black and white screen.
-`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0235>`_
+`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0261>`_
This system uses lamps for key gameplay elements. Blending modes are used
for the translucent colour overlay placed over the monitor, and the lamps
reflected in front of the monitor. Also uses collections to allow parts of
- the layout to be disabled selectively. The shapes on the overlay are drawn
- using embedded SVG images.
-`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0235>`_
+ the layout to be disabled selectively.
+`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0261>`_
This game’s monitor is viewed directly through a translucent colour overlay
rather than being reflected from inside the cabinet. This means the overlay
reflects ambient light as well as affecting the colour of the video image.
-`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0235>`_
+ The shapes on the overlay are drawn using embedded SVG images.
+`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0261>`_
A multi-segment alphanumeric display and keypad. The keys are clickable,
and provide visual feedback when pressed.
-`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0235>`_
+`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0261>`_
Builds up a multi-line dot matrix character display. Repeats are used to
avoid repetition for the rows in a character, characters in a line, and
lines in a page. Group colors allow a single element to be used for all
four display colours.
-`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0235>`_
+`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0261>`_
Animates the position of element items to simulate an electromechanical
shooting gallery game. Also demonstrates effective use of components to
build up complex graphics.
-`unkeinv.lay <https://git.redump.net/mame/tree/src/mame/layout/unkeinv.lay?h=mame0235>`_
+`minspace.lay <https://git.redump.net/mame/tree/src/mame/layout/minspace.lay?h=mame0261>`_
Shows the position of a slider control with LEDs on it.
-`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0235>`_
+`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0261>`_
Effectively using groups as a procedural programming language to build up an
image of a trainer board.
+`beena.lay <https://git.redump.net/mame/tree/src/mame/layout/beena.lay?h=mame0261>`_
+ Using event-based scripting to dynamically position elements and draw elemnt
+ content programmatically.
diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst
index f2b8ef1cbc3..7e5b7419bb7 100644
--- a/docs/source/techspecs/layout_script.rst
+++ b/docs/source/techspecs/layout_script.rst
@@ -36,9 +36,8 @@ Practical examples
Before diving into the technical details of how it works, we’ll start with some
example layout files using Lua script for enhancement. It’s assumed that you’re
familiar with MAME’s artwork system and have a basic understanding of Lua
-scripting. For details on MAME’s layout file, see :ref:`layfile`; for an
-introduction to Lua scripting in MAME, see :ref:`luaengine`; for detailed
-descriptions of MAME’s Lua classes, see :ref:`luareference`.
+scripting. For details on MAME’s layout file, see :ref:`layfile`; for detailed
+descriptions of MAME’s Lua interface, see :ref:`luascript`.
.. _layscript-examples-espial:
@@ -188,19 +187,21 @@ as a function by the layout plugin when the layout file is loaded. The layout
views have been built at this point, but the emulated system has not finished
starting. In particular, it’s not safe to access inputs and outputs at this
time. The key variable in the script environment is ``file``, which gives the
-script access to its layout file.
+script access to its :ref:`layout file <luascript-ref-renderlayfile>`.
We supply a function to be called after tags in the layout file have been
resolved. At this point, the emulated system will have completed starting.
This function does the following tasks:
-* Looks up the two I/O ports used for player input. I/O ports can be looked up
- by tag relative to the device that caused the layout file to be loaded.
-* Looks up the two view items used to display joystick state. Views can be
- looked up by name (i.e. value of the ``name`` attribute), and items within a
- view can be looked up by ID (i.e. the value of the ``id`` attribute).
+* Looks up the two :ref:`I/O ports <luascript-ref-ioport>` used for player
+ input. I/O ports can be looked up by tag relative to the device that caused
+ the layout file to be loaded.
+* Looks up the two :ref:`view items <luascript-ref-renderlayitem>` used to
+ display joystick state. Views can be looked up by name (i.e. value of the
+ ``name`` attribute), and items within a view can be looked up by ID (i.e. the
+ value of the ``id`` attribute).
* Supplies a function to be called before view items are added to the render
- target.
+ target when drawing a frame.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
the element state is 1).
@@ -414,20 +415,20 @@ Here’s our layout file:
The layout has a ``script`` element containing the Lua script, to be called as a
function by the layout plugin when the layout file is loaded. This happens
after the layout views have been build, but before the emulated system has
-finished starting. The layout file object is supplied to the script in the
-``file`` variable.
+finished starting. The :ref:`layout file <luascript-ref-renderlayfile>` object
+is supplied to the script in the ``file`` variable.
We supply a function to be called after tags in the layout file have been
resolved. This function does the following:
-* Looks up the analog axis inputs.
-* Looks up the view item that draws the outline of area where the yoke position
- is displayed.
+* Looks up the analog axis :ref:`inputs <luascript-ref-ioport>`.
+* Looks up the :ref:`view item <luascript-ref-renderlayitem>` that draws the
+ outline of area where the yoke position is displayed.
* Declares some variables to hold calculated values across function calls.
* Supplies a function to be called when the view’s dimensions have been
recomputed.
* Supplies a function to be called before adding view items to the render
- container.
+ container when drawing a frame.
* Supplies functions that will supply the bounds for the animated items.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
@@ -472,18 +473,31 @@ The layout script environment
The Lua environment is provided by the layout plugin. It’s fairly minimal, only
providing what’s needed:
-* ``file`` giving the script’s layout file object. Has a ``device`` property
- for obtaining the device that caused the layout file to be loaded, and a
- ``views`` property for obtaining the layout’s views (indexed by name).
-* ``machine`` giving MAME’s current running machine.
-* ``emu.render_bounds`` and ``emu.render_color`` functions for creating bounds
- and colour objects.
-* ``emu.print_error``, ``emu.print_info`` and ``emu.print_debug`` functions for
- diagnostic output.
-* Standard Lua ``pairs``, ``ipairs``, ``table.insert`` and ``table.remove``
- functions for manipulating tables and other containers.
+* ``file`` giving the script’s :ref:`layout file <luascript-ref-renderlayfile>`
+ object. Has a ``device`` property for obtaining the :ref:`device
+ <luascript-ref-device>` that caused the layout file to be loaded, and a
+ ``views`` property for obtaining the layout’s :ref:`views
+ <luascript-ref-renderlayview>` (indexed by name).
+* ``machine`` giving MAME’s current :ref:`running machine
+ <luascript-ref-machine>`.
+* ``emu.device_enumerator``, ``emu.palette_enumerator``,
+ ``emu.screen_enumerator``, ``emu.cassette_enumerator``,
+ ``emu.image_enumerator`` and ``emu.slot_enumerator`` functions for obtaining
+ specific device interfaces.
+* ``emu.attotime``, ``emu.render_bounds`` and ``emu.render_color`` functions for
+ creating :ref:`attotime <luascript-ref-attotime>`, :ref:`bounds
+ <luascript-ref-renderbounds>` and :ref:`colour <luascript-ref-rendercolor>`
+ objects.
+* ``emu.bitmap_ind8``, ``emu.bitmap_ind16``, ``emu.bitmap_ind32``,
+ ``emu.bitmap_ind64``, ``emu.bitmap_yuy16``, ``emu.bitmap_rgb32`` and
+ ``emu.bitmap_argb32`` objects for creating
+ :ref:`bitmaps <luascript-ref-bitmap>`.
+* ``emu.print_verbose``, ``emu.print_error``, ``emu.print_warning``,
+ ``emu.print_info`` and ``emu.print_debug`` functions for diagnostic output.
+* Standard Lua ``tonumber``, ``tostring``, ``pairs`` and ``ipairs`` functions,
+ and ``table`` and ``string`` objects for manipulating strings, tables and
+ other containers.
* Standard Lua ``print`` function for text output to the console.
-* Standard Lua ``string.format`` function for string formatting.
.. _layscript-events:
@@ -549,6 +563,96 @@ Dimensions recomputed
The callback function has no return value and takes no parameters. Call
with ``nil`` as the argument to remove the event handler.
+Pointer updated
+ ``view:set_pointer_updated_callback(cb)``
+
+ Called when a pointer enters, moves or changes button state over the view.
+
+ The callback function is passed nine arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the currently pressed buttons. The primary button
+ is the least significant bit.
+ * A bit mask representing the buttons that were pressed in this update. The
+ primary button is the least significant bit.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Pointer left
+ ``view:set_pointer_left_callback(cb)``
+
+ Called when a pointer leaves the view normally. After receiving this event,
+ the pointer ID may be reused for a new pointer.
+
+ The callback function is passed seven arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Pointer aborted
+ ``view:set_pointer_aborted_callback(cb)``
+
+ Called when a pointer leaves the view abnormally. After receiving this
+ event, the pointer ID may be reused for a new pointer.
+
+ The callback function is passed seven arguments:
+
+ * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch``
+ or ``unknown``, and will not change for the lifetime of a pointer.
+ * The pointer ID. This will be a non-negative integer that will not change
+ for the lifetime of a pointer. Pointer ID values are recycled
+ aggressively.
+ * The device ID. This will be a non-negative integer that can be used to
+ group pointers for recognising multi-touch gestures.
+ * The horizontal position of the pointer in layout coordinates.
+ * The vertical position of the pointer in layout coordinates.
+ * A bit mask representing the buttons that were released in this update.
+ The primary button is the least significant bit.
+ * The click count. This is positive for multi-click actions, or negative if
+ a click is turned into a hold or drag. This only applies to the primary
+ button.
+
+ The callback function has no return value. Call with ``nil`` as the
+ argument to remove the event handler.
+Forget pointers
+ ``view:set_forget_pointers_callback(cb)``
+
+ Called when the view should stop processing pointer input. This can happen
+ in a number of situations, including:
+
+ * The user activated a menu.
+ * The view configuration will change.
+ * The view will be deactivated.
+
+ The callback function has no return value and takes no parameters. Call
+ with ``nil`` as the argument to remove the event handler.
.. _layscript-events-item:
@@ -617,7 +721,7 @@ Get item horizontal scroll window size
horizontal window size as a proportion of the associated element’s width,
and takes no parameters. A value of 1.0 will display the entire width of
the element; smaller values will display proportionally smaller parts of the
- element. Call with ``nil`` as the argument to to restore the default
+ element. Call with ``nil`` as the argument to restore the default
horizontal scroll window size handler (based on the ``xscroll`` child
element).
Get item vertical scroll window size
@@ -632,7 +736,7 @@ Get item vertical scroll window size
vertical window size as a proportion of the associated element’s height, and
takes no parameters. A value of 1.0 will display the entire height of the
element; smaller values will display proportionally smaller parts of the
- element. Call with ``nil`` as the argument to to restore the default
+ element. Call with ``nil`` as the argument to restore the default
vertical scroll window size handler (based on the ``xscroll`` child
element).
Get item horizontal scroll position
@@ -661,3 +765,22 @@ Get item vertical scroll position
item; larger values pan down. Call with ``nil`` as the argument to restore
the default vertical scroll position handler (based on bindings in the
``yscroll`` child element).
+
+.. _layscript-events-element:
+
+Layout element events
+~~~~~~~~~~~~~~~~~~~~~
+
+Layout element events apply to an individual visual element definition.
+
+Draw
+ ``element:set_draw_callback(cb)``
+
+ Set callback for additional drawing after the element’s components have been
+ drawn. This gives the script direct control over the final texture when an
+ element item is drawn.
+
+ The callback is passed two arguments: the element state (an integer) and the
+ 32-bit ARGB bitmap at the required size. The callback must not attempt to
+ resize the bitmap. Call with ``nil`` as the argument to remove the event
+ handler.
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst
deleted file mode 100644
index 5e97d4e3885..00000000000
--- a/docs/source/techspecs/luaengine.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-.. _luaengine:
-
-Scripting MAME via Lua
-======================
-
-.. contents:: :local:
-
-
-.. _luaengine-intro:
-
-Introduction
-------------
-
-It is now possible to externally drive MAME via Lua scripts. This feature
-initially appeared in version 0.148, when a minimal Lua engine was implemented.
-Today, the Lua interface is rich enough to let you inspect and manipulate
-devices’ state, access CPU registers, read and write memory, and draw a custom
-HUD on screen.
-
-Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
-to implement this feature. The idea is to transparently expose as many of the
-useful internals as possible.
-
-Finally, a warning: the Lua API is not yet declared stable and may suddenly
-change without prior notice. However, we expose methods to let you know at
-runtime which API version you are running against, and most of the objects
-support runtime you can introspection.
-
-
-.. _luaengine-features:
-
-Features
---------
-
-The API is not yet complete, but this is a partial list of capabilities
-currently available to Lua scripts:
-
-- session information (app version, current emulated system, ROM details)
-- session control (starting, pausing, resetting, stopping)
-- event hooks (on frame painting and on user events)
-- device introspection (device tree listing, memory and register enumeration)
-- screen introspection (screens listing, screen details, frame counting)
-- screen overlay drawing (text, lines, boxes on multiple screens)
-- memory read/write (8/16/32/64 bits, signed and unsigned)
-- register and state control (state enumeration, get and set)
-
-Many of the classes are documented on the
-:ref:`Lua class reference <luareference>` page.
-
-
-.. _luaengine-usage:
-
-Usage
------
-
-MAME supports external scripting via Lua (>= 5.3) scripts, either entered at the
-interactive console or loaded as a file. To reach the console, enable the
-console plugin (e.g. run MAME with ``-plugin console``) and you will be greeted
-with a ``[MAME]>`` prompt where you can enter Lua script interactively.
-
-To load a whole script at once, store it in a plain text file and pass it using
-``-autoboot_script``. Please note that script loading may be delayed (a few
-seconds by default), but you can override the default with the
-``-autoboot_delay`` option.
-
-To control the execution of your code, you can use a loop-based or event-based
-approach. The former is not encouraged as it is resource-intensive and makes
-control flow unnecessarily complex. Instead, we suggest to register custom
-hooks to be invoked on specific events (e.g. at each frame rendering).
-
-
-.. _luaengine-walkthrough:
-
-Walkthrough
------------
-
-Let’s first run MAME in a terminal to reach the Lua console:
-
-::
-
- $ mame -console YOUR_ROM
- /| /| /| /| /| _______
- / | / | / | / | / | / /
- / |/ | / | / |/ | / ____/
- / | / | / | / /_
- / |/ | / |/ __/
- / /| /| /| |/ /| /| /____
- / / | / | / | / | / | /
- / _/ |/ / / |___/ |/ /_______/
- / /
- / _/
-
- mame 0.227
- Copyright (C) Nicola Salmoria and the MAME team
-
- Lua 5.3
- Copyright (C) Lua.org, PUC-Rio
-
- [MAME]>
-
-At this point, your game is probably running in demo mode, let’s pause it:
-
-::
-
- [MAME]> emu.pause()
- [MAME]>
-
-Even without textual feedback on the console, you’ll notice the game is now
-paused. In general, commands are quiet and only print back error messages.
-
-You can check at runtime which version of MAME you are running, with:
-
-::
-
- [MAME]> print(emu.app_name() .. " " .. emu.app_version())
- mame 0.227
-
-We now start exploring screen related methods. First, let's enumerate available
-screens:
-
-::
-
- [MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
- :screen
-
-``manager.machine`` is the :ref:`running machine <luareference-core-machine>`
-object for your current emulation session. We will be using this frequently.
-``screens`` is a :ref:`device enumerator <luareference-dev-enum>` that yields
-all emulated screens in the system; most arcade games only have one main screen.
-In our case, the main and only screen is tagged as ``:screen``, and we can
-further inspect it:
-
-::
-
- [MAME]> -- keep a reference to the main screen in a variable
- [MAME]> s = manager.machine.screens[":screen"]
- [MAME]> print(s.width .. "x" .. s.height)
- 320x224
-
-We have several methods to draw a HUD on the screen composed of lines, boxes and
-text:
-
-::
-
- [MAME]> -- we define a HUD-drawing function, and then call it
- [MAME]> function draw_hud()
- [MAME]>> s:draw_text(40, 40, "foo") -- (x0, y0, msg)
- [MAME]>> s:draw_box(20, 20, 80, 80, 0xff00ffff, 0) -- (x0, y0, x1, y1, line-color, fill-color)
- [MAME]>> s:draw_line(20, 20, 80, 80, 0xff00ffff) -- (x0, y0, x1, y1, line-color)
- [MAME]>> end
- [MAME]> draw_hud()
-
-This will draw some useless art on the screen. However, when resuming the game,
-your HUD needs to be refreshed otherwise it will just disappear. In order to do
-this, you have to register your hook to be called on every frame repaint:
-
-::
-
- [MAME]> emu.register_frame_done(draw_hud, "frame")
-
-All colors are specified in ARGB format (eight bits per channel), while screen
-origin (0,0) normally corresponds to the top-left corner.
-
-Similarly to screens, you can inspect all the devices attached to a machine:
-
-::
-
- [MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
- :audiocpu
- :maincpu
- :saveram
- :screen
- :palette
- [...]
-
-On some of them, you can also inspect and manipulate memory and state:
-
-::
-
- [MAME]> cpu = manager.machine.devices[":maincpu"]
- [MAME]> -- enumerate, read and write state registers
- [MAME]> for k, v in pairs(cpu.state) do print(k) end
- D5
- SP
- A4
- A3
- D0
- PC
- [...]
- [MAME]> print(cpu.state["D0"].value)
- 303
- [MAME]> cpu.state["D0"].value = 255
- [MAME]> print(cpu.state["D0"].value)
- 255
-
-::
-
- [MAME]> -- inspect memory
- [MAME]> for name, space in pairs(cpu.spaces) do print(name) end
- program
- [MAME]> mem = cpu.spaces["program"]
- [MAME]> print(mem:read_i8(0xc000))
- 41
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
deleted file mode 100644
index 85c7ea8cb8a..00000000000
--- a/docs/source/techspecs/luareference.rst
+++ /dev/null
@@ -1,3184 +0,0 @@
-.. _luareference:
-
-MAME Lua Class Reference
-========================
-
-.. contents::
- :local:
- :depth: 2
-
-
-.. _luareference-intro:
-
-Introduction
-------------
-
-Various aspects of MAME can be controlled using Lua scripting. Many key classes
-are exposed as Lua objects.
-
-.. _luareference-intro-containers:
-
-Containers
-~~~~~~~~~~
-
-Many properties yield container wrappers. Container wrappers are cheap to
-create, and provide an interface that is similar to a read-only table. The
-complexity of operations may vary. Container wrappers usually provide most of
-these operations:
-
-#c
- Get the number of items in the container.
-c[k]
- Returns the item corresponding to the key ``k``, or ``nil`` if the key is
- not present.
-pairs(c)
- Iterate container by key and value. The key is what you would pass to the
- index operator or the ``get`` method to get the value.
-ipairs(c)
- Iterate container by index and value. The index is what you would pass to
- the ``at`` method to get the value (this may be the same as the key for some
- containers).
-c:empty()
- Returns a Boolean indicating whether there are no items in the container.
-c:get(k)
- Returns the item corresponding to the key ``k``, or ``nil`` if the key is
- not present. Usually equivalent to the index operator.
-c:at(i)
- Returns the value at the 1-based index ``i``, or ``nil`` if it is out of
- range.
-c:find(v)
- Returns the key for item ``v``, or ``nil`` if it is not in the container.
- The key is what you would pass to the index operator to get the value.
-c:index_of(v)
- Returns the 1-based index for item ``v``, or ``nil`` if it is not in the
- container. The index is what you would pass to the ``at`` method to get the
- value.
-
-
-.. _luareference-core:
-
-Core classes
-------------
-
-Many of MAME’s core classes used to implement an emulation session are available
-to Lua scripts.
-
-.. _luareference-core-attotime:
-
-Attotime
-~~~~~~~~
-
-Wraps MAME’s ``attotime`` class, which represents a high-precision time
-interval. Attotime values support addition and subtraction with other attotime
-values, and multiplication and division by integers.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.attotime()
- Creates an attotime value representing zero (i.e. no elapsed time).
-emu.attotime(seconds, attoseconds)
- Creates an attotime with the specified whole and fractional parts.
-emu.attotime(attotime)
- Creates a copy of an existing attotime value.
-emu.attotime.from_double(seconds)
- Creates an attotime value representing the specified number of seconds.
-emu.attotime.from_ticks(periods, frequency)
- Creates an attotime representing the specified number of periods of the
- specified frequency in Hertz.
-emu.attotime.from_seconds(seconds)
- Creates an attotime value representing the specified whole number of
- seconds.
-emu.attotime.from_msec(milliseconds)
- Creates an attotime value representing the specified whole number of
- milliseconds.
-emu.attotime.from_usec(microseconds)
- Creates an attotime value representing the specified whole number of
- microseconds.
-emu.attotime.from_nsec(nanoseconds)
- Creates an attotime value representing the specified whole number of
- nanoseconds.
-
-Methods
-^^^^^^^
-
-t:as_double()
- Returns the time interval in seconds as a floating-point value.
-t:as_hz()
- Interprets the interval as a period and returns the corresponding frequency
- in Hertz as a floating-point value. Returns zero if ``t.is_never`` is true.
- The interval must not be zero.
-t:as_khz()
- Interprets the interval as a period and returns the corresponding frequency
- kilohertz as a floating-point value. Returns zero if ``t.is_never`` is
- true. The interval must not be zero.
-t:as_mhz()
- Interprets the interval as a period and returns the corresponding frequency
- megahertz as a floating-point value. Returns zero if ``t.is_never`` is
- true. The interval must not be zero.
-t:as_ticks(frequency)
- Returns the interval as a whole number of periods at the specified
- frequency. The frequency is specified in Hertz.
-
-Properties
-^^^^^^^^^^
-
-t.is_zero (read-only)
- A Boolean indicating whether the value represents no elapsed time.
-t.is_never (read-only)
- A Boolean indicating whether the value is greater than the maximum number of
- whole seconds that can be represented (treated as an unreachable time in the
- future or overflow).
-t.attoseconds (read-only)
- The fraction seconds portion of the interval in attoseconds.
-t.seconds (read-only)
- The number of whole seconds in the interval.
-t.msec (read-only)
- The number of whole milliseconds in the fractional seconds portion of the
- interval.
-t.usec (read-only)
- The number of whole microseconds in the fractional seconds portion of the
- interval.
-t.nsec (read-only)
- The number of whole nanoseconds in the fractional seconds portion of the
- interval.
-
-.. _luareference-core-mameman:
-
-MAME machine manager
-~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``mame_machine_manager`` class, which holds the running machine, UI
-manager, and other global components.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager
- The MAME machine manager is available as a global variable in the Lua
- environment.
-
-Properties
-^^^^^^^^^^
-
-manager.machine (read-only)
- The :ref:`running machine <luareference-core-machine>` for the current
- emulation session.
-manager.ui (read-only)
- The :ref:`UI manager <luareference-core-uiman>` for the current session.
-manager.options (read-only)
- The :ref:`emulation options <luareference-core-emuopts>` for the current
- session.
-manager.plugins[] (read-only)
- Gets information about the :ref:`Lua plugins <luareference-core-plugin>`
- that are present, indexed by name. The index get, ``at`` and ``index_of``
- methods have O(n) complexity.
-
-.. _luareference-core-machine:
-
-Running machine
-~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``running_machine`` class, which represents an emulation session.
-It provides access to the other core objects that implement an emulation session
-as well as the emulated device tree.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine
- Gets the running machine instance for the current emulation session.
-
-Methods
-^^^^^^^
-
-machine:exit()
- Schedules an exit from the current emulation session. This will either
- return to the system selection menu or exit the application, depending on
- how it was started. This method returns immediately, before the scheduled
- exit takes place.
-machine:hard_reset()
- Schedules a hard reset. This is implemented by tearing down the emulation
- session and starting another emulation session for the same system. This
- method returns immediately, before the scheduled reset takes place.
-machine:soft_reset()
- Schedules a soft reset. This is implemented by calling the reset method of
- the root device, which is propagated down the device tree. This method
- returns immediately, before the scheduled reset takes place.
-machine:save(filename)
- Schedules saving machine state to the specified file. If the file name is a
- relative path, it is considered to be relative to the first configured save
- state directory. This method returns immediately, before the machine state
- is saved. If this method is called when a save or load operation is already
- pending, the previously pending operation will be cancelled.
-machine:load(filename)
- Schedules loading machine state from the specified file. If the file name
- is a relative path, the configured save state directories will be searched.
- This method returns immediately, before the machine state is saved. If this
- method is called when a save or load operation is already pending, the
- previously pending operation will be cancelled.
-machine:popmessage([msg])
- Displays a pop-up message to the user. If the message is not provided, the
- currently displayed pop-up message (if any) will be hidden.
-machine:logerror(msg)
- Writes the message to the machine error log. This may be displayed in a
- debugger window, written to a file, or written to the standard error output.
-
-Properties
-^^^^^^^^^^
-
-machine.time (read-only)
- The elapsed emulated time for the current session as an
- :ref:`attotime <luareference-core-attotime>`.
-machine.system (read-only)
- The :ref:`driver metadata <luareference-core-driver>` for the current
- system.
-machine.parameters (read-only)
- The :ref:`parameters manager <luareference-core-paramman>` for the current
- emulation session.
-machine.video (read-only)
- The :ref:`video manager <luareference-core-videoman>` for the current
- emulation session.
-machine.sound (read-only)
- The :ref:`sound manager <luareference-core-soundman>` for the current
- emulation session.
-machine.output (read-only)
- The :ref:`output manager <luareference-core-outputman>` for the current
- emulation session.
-machine.memory (read-only)
- The :ref:`emulated memory manager <luareference-mem-manager>` for the
- current emulation session.
-machine.ioport (read-only)
- The :ref:`I/O port manager <luareference-input-ioportman>` for the current
- emulation session.
-machine.input (read-only)
- The :ref:`input manager <luareference-input-inputman>` for the current
- emulation session.
-machine.natkeyboard (read-only)
- Gets the :ref:`natural keyboard manager <luareference-input-natkbd>`, used
- for controlling keyboard and keypad input to the emulated system.
-machine.uiinput (read-only)
- The :ref:`UI input manager <luareference-input-uiinput>` for the current
- emulation session.
-machine.render (read-only)
- The :ref:`render manager <luareference-render-manager>` for the current
- emulation session.
-machine.debugger (read-only)
- The :ref:`debugger manager <luareference-debug-manager>` for the current
- emulation session, or ``nil`` if the debugger is not enabled.
-machine.options (read-only)
- The user-specified :ref:`options <luareference-core-emuopts>` for the
- current emulation session.
-machine.samplerate (read-only)
- The output audio sample rate in Hertz.
-machine.paused (read-only)
- A Boolean indicating whether emulation is not currently running, usually
- because the session has been paused or the emulated system has not completed
- starting.
-machine.exit_pending (read-only)
- A Boolean indicating whether the emulation session is scheduled to exit.
-machine.hard_reset_pending (read-only)
- A Boolean indicating whether a hard reset of the emulated system is pending.
-machine.devices (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`devices <luareference-dev-device>` in the emulated system.
-machine.screens (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`screen devices <luareference-dev-screen>` in the emulated system.
-machine.cassettes (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`cassette image devices <luareference-dev-cass>` in the emulated
- system.
-machine.images (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`media image devices <luareference-dev-diimage>` in the emulated system.
-machine.slots (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`slot devices <luareference-dev-dislot>` in the emulated system.
-
-.. _luareference-core-videoman:
-
-Video manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``video_manager`` class, which is responsible for coordinating
-emulated video drawing, speed throttling, and reading host inputs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.video
- Gets the video manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-video:frame_update()
- Updates emulated screens, reads host inputs, and updates video output.
-video:snapshot()
- Saves snapshot files according to the current configuration. If MAME is
- configured to take native emulated screen snapshots, one snapshot will be
- saved for each emulated screen that is visible in a host window/screen with
- the current view configuration. If MAME is not configured to use take
- native emulated screen snapshots or if the system has no emulated screens, a
- single snapshot will be saved using the currently selected snapshot view.
-video:begin_recording([filename], [format])
- Stops any video recordings currently in progress and starts recording either
- the visible emulated screens or the current snapshot view, depending on
- whether MAME is configured to take native emulated screen snapshots.
-
- If the file name is not supplied, the configured snapshot file name is used.
- If the file name is a relative path, it is interpreted relative to the first
- configured snapshot directory. If the format is supplied, it must be
- ``"avi"`` or ``"mng"``. If the format is not supplied, it defaults to AVI.
-video:end_recording()
- Stops any video recordings that are in progress.
-video:snapshot_size()
- Returns the width and height in pixels of snapshots created with the current
- snapshot target configuration and emulated screen state. This may be
- configured explicitly by the user, or calculated based on the selected
- snapshot view and the resolution of any visible emulated screens.
-video:snapshot_pixels()
- Returns the pixels of a snapshot created using the current snapshot target
- configuration as 32-bit integers packed into a binary string in host Endian
- order. Pixels are organised in row-major order, from left to right then top
- to bottom. Pixel values are colours in RGB format packed into 32-bit
- integers.
-
-Properties
-^^^^^^^^^^
-
-video.speed_factor (read-only)
- Configured emulation speed adjustment in per mille (i.e. the ratio to normal
- speed multiplied by 1,000).
-video.throttled (read/write)
- A Boolean indicating whether MAME should wait before video updates to avoid
- running faster than the target speed.
-video.throttle_rate (read/write)
- The target emulation speed as a ratio of full speed adjusted by the speed
- factor (i.e. 1 is normal speed adjusted by the speed factor, larger numbers
- are faster, and smaller numbers are slower).
-video.frameskip (read/write)
- The number of emulated video frames to skip drawing out of every twelve, or
- -1 to automatically adjust the number of frames to skip to maintain the
- target emulation speed.
-video.speed_percent (read-only)
- The current emulated speed as a percentage of the full speed adjusted by the
- speed factor.
-video.effective_frameskip (read-only)
- The number of emulated frames that are skipped out of every twelve.
-video.skip_this_frame (read-only)
- A Boolean indicating whether the video manager will skip drawing emulated
- screens for the current frame.
-video.snap_native (read-only)
- A Boolean indicating whether the video manager will take native emulated
- screen snapshots. In addition to the relevant configuration setting, the
- emulated system must have at least one emulated screen.
-video.is_recording (read-only)
- A Boolean indicating whether any video recordings are currently in progress.
-video.snapshot_target (read-only)
- The :ref:`render target <luareference-render-target>` used to produce
- snapshots and video recordings.
-
-.. _luareference-core-soundman:
-
-Sound manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``sound_manager`` class, which manages the emulated sound stream
-graph and coordinates sound output.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.sound
- Gets the sound manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-sound:start_recording([filename])
- Starts recording to a WAV file. Has no effect if currently recording. If
- the file name is not supplied, uses the configured WAV file name (from
- command line or INI file), or has no effect if no WAV file name is
- configured. Returns ``true`` if recording started, or ``false`` if
- recording is already in progress, opening the output file failed, or no file
- name was supplied or configured.
-sound:stop_recording()
- Stops recording and closes the file if currently recording to a WAV file.
-sound:get_samples()
- Returns the current contents of the output sample buffer as a binary string.
- Samples are 16-bit integers in host byte order. Samples for left and right
- stereo channels are interleaved.
-
-Properties
-^^^^^^^^^^
-
-sound.muted (read-only)
- A Boolean indicating whether sound output is muted for any reason.
-sound.ui_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- user.
-sound.debugger_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- debugger.
-sound.system_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- emulated system.
-sound.attenuation (read/write)
- The output volume attenuation in decibels. Should generally be a negative
- integer or zero.
-sound.recording (read-only)
- A Boolean indicating whether sound output is currently being recorded to a
- WAV file.
-
-.. _luareference-core-outputman:
-
-Output manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``output_manager`` class, providing access to system outputs that
-can be used for interactive artwork or consumed by external programs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.output
- Gets the output manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-output:set_value(name, val)
- Sets the specified output value. The value must be an integer. The output
- will be created if it does not already exist.
-output:set_indexed_value(prefix, index, val)
- Appends the index (formatted as a decimal integer) to the prefix and sets
- the value of the corresponding output. The value must be an integer. The
- output will be created if it does not already exist.
-output:get_value(name)
- Returns the value of the specified output, or zero if it doesn’t exist.
-output:get_indexed_value(prefix, index)
- Appends the index (formatted as a decimal integer) to the prefix and returns
- the value of the corresponding output, or zero if it doesn’t exist.
-output:name_to_id(name)
- Gets the per-session unique integer ID for the specified output, or zero if
- it doesn’t exist.
-output:id_to_name(id)
- Gets the name for the output with the specified per-session unique ID, or
- ``nil`` if it doesn’t exist. This method has O(n) complexity, so avoid
- calling it when performance is important.
-
-.. _luareference-core-paramman:
-
-Parameters manager
-~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``parameters_manager`` class, which provides a simple key-value
-store for metadata from system ROM definitions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.parameters
- Gets the parameters manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-parameters:lookup(tag)
- Gets the value for the specified parameter if it is set, or an empty string
- if it is not set.
-parameters:add(tag, value)
- Sets the specified parameter if it is not set. Has no effect if the
- specified parameter is already set.
-
-.. _luareference-core-uiman:
-
-UI manager
-~~~~~~~~~~
-
-Wraps MAME’s ``mame_ui_manager`` class, which handles menus and other user
-interface functionality.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.ui
- Gets the UI manager for the current session.
-
-Methods
-^^^^^^^
-
-ui:get_char_width(ch)
- Gets the width of a Unicode character as a proportion of the width of the UI
- container in the current font at the configured UI line height.
-ui:get_string_width(str)
- Gets the width of a string as a proportion of the width of the UI container
- in the current font at the configured UI line height.
-ui:set_aggressive_input_focus(enable)
- On some platforms, this controls whether MAME should accept input focus in
- more situations than when its windows have UI focus.
-ui:get_general_input_setting(type, [player])
- Gets a description of the configured
- :ref:`input sequence <luareference-input-iptseq>` for the specified input
- type and player suitable for using in prompts. The input type is an
- enumerated value. The player number is a zero-based index. If the player
- number is not supplied, it is assumed to be zero.
-
-Properties
-^^^^^^^^^^
-
-ui.options (read-only)
- The UI :ref:`options <luareference-core-coreopts>` for the current session.
-ui.line_height (read-only)
- The configured UI text line height as a proportion of the height of the UI
- container.
-ui.menu_active (read-only)
- A Boolean indicating whether an interactive UI element is currently active.
- Examples include menus and slider controls.
-ui.single_step (read/write)
- A Boolean controlling whether the emulated system should be automatically
- paused when the next frame is drawn. This property is automatically reset
- when the automatic pause happens.
-ui.show_fps (read/write)
- A Boolean controlling whether the current emulation speed and frame skipping
- settings should be displayed.
-ui.show_profiler (read/write)
- A Boolean controlling whether profiling statistics should be displayed.
-
-.. _luareference-core-driver:
-
-System driver metadata
-~~~~~~~~~~~~~~~~~~~~~~
-
-Provides some metadata for an emulated system.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.driver_find(name)
- Gets the driver metadata for the system with the specified short name, or
- ``nil`` if no such system exists.
-manager.machine.system
- Gets the driver metadata for the current system.
-
-Properties
-^^^^^^^^^^
-
-driver.name (read-only)
- The short name of the system, as used on the command line, in configuration
- files, and when searching for resources.
-driver.description (read-only)
- The full display name for the system.
-driver.year (read-only)
- The release year for the system. May contain question marks if not known
- definitively.
-driver.manufacturer (read-only)
- The manufacturer, developer or distributor of the system.
-driver.parent (read-only)
- The short name of parent system for organisation purposes, or ``"0"`` if the
- system has no parent.
-driver.compatible_with (read-only)
- The short name of a system that this system is compatible with software for,
- or ``nil`` if the system is not listed as compatible with another system.
-driver.source_file (read-only)
- The source file where this system driver is defined. The path format
- depends on the toolchain the emulator was built with.
-driver.rotation (read-only)
- A string indicating the rotation applied to all screens in the system after
- the screen orientation specified in the machine configuration is applied.
- Will be one of ``"rot0"``, ``"rot90"``, ``"rot180"`` or ``"rot270"``.
-driver.type (read-only)
- A string providing a system type. Will be one of ``"arcade"``,
- ``"console"``, ``"computer"`` or ``"other"``. This is for informational
- purposes only, and may not be supported in the future.
-driver.not_working (read-only)
- A Boolean indicating whether the system is marked as not working.
-driver.supports_save (read-only)
- A Boolean indicating whether the system supports save states.
-driver.no_cocktail (read-only)
- A Boolean indicating whether screen flipping in cocktail mode is
- unsupported.
-driver.is_bios_root (read-only)
- A Boolean indicating whether this system represents a system that runs
- software from removable media without media present.
-driver.requires_artwork (read-only)
- A Boolean indicating whether the system requires external artwork to be
- usable.
-driver.clickable_artwork (read-only)
- A Boolean indicating whether the system requires clickable artwork features
- to be usable.
-driver.unofficial (read-only)
- A Boolean indicating whether this is an unofficial but common user
- modification to a system.
-driver.no_sound_hw (read-only)
- A Boolean indicating whether the system has no sound output hardware.
-driver.mechanical (read-only)
- A Boolean indicating whether the system depends on mechanical features that
- cannot be properly simulated.
-driver.is_incomplete (read-only)
- A Boolean indicating whether the system is a prototype with incomplete
- functionality.
-
-.. _luareference-core-plugin:
-
-Lua plugin
-~~~~~~~~~~
-
-Provides a description of an available Lua plugin.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.plugins[name]
- Gets the description of the Lua plugin with the specified name, or ``nil``
- if no such plugin is available
-
-Properties
-^^^^^^^^^^
-
-plugin.name (read-only)
- The short name of the plugin, used in configuration and when accessing the
- plugin programmatically.
-plugin.description (read-only)
- The display name for the plugin.
-plugin.type (read-only)
- The plugin type. May be ``"plugin"`` for user-loadable plugins, or
- ``"library"`` for libraries providing common functionality to multiple
- plugins.
-plugin.directory (read-only)
- The path to the directory containing the plugin’s files.
-plugin.start (read-only)
- A Boolean indicating whether the plugin enabled.
-
-
-.. _luareference-dev:
-
-Devices
--------
-
-Several device classes and device mix-ins classes are exposed to Lua. Devices
-can be looked up by tag or enumerated.
-
-.. _luareference-dev-enum:
-
-Device enumerators
-~~~~~~~~~~~~~~~~~~
-
-Device enumerators are special containers that allow iterating over devices and
-looking up devices by tag. A device enumerator can be created to find any kind
-of device, to find devices of a particular type, or to find devices that
-implement a particular interface. When iterating using ``pairs`` or ``ipairs``,
-devices are returned by walking the device tree depth-first in creation order.
-
-The index get operator looks up a device by tag. It returns ``nil`` if no
-device with the specified tag is found, or if the device with the specified tag
-does not meet the type/interface requirements of the device enumerator. The
-complexity is O(1) if the result is cached, but an uncached device lookup is
-expensive. The ``at`` method has O(n) complexity.
-
-If you create a device enumerator with a starting point other than the root
-machine device, passing an absolute tag or a tag containing parent references to
-the index operator may return a device that would not be discovered by
-iteration. If you create a device enumerator with restricted depth, devices
-that would not be found due to being too deep in the hierarchy can still be
-looked up by tag.
-
-Creating a device enumerator with depth restricted to zero can be used to
-downcast a device or test whether a device implements a certain interface. For
-example this will test whether a device implements the media image interface:
-
-.. code-block:: Lua
-
- image_intf = emu.image_enumerator(device, 0):at(1)
- if image_intf then
- print(string.format("Device %s mounts images", device.tag))
- end
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices
- Returns a device enumerator that will iterate over
- :ref:`devices <luareference-dev-device>` in the system.
-manager.machine.screens
- Returns a device enumerator that will iterate over
- :ref:`screen devices <luareference-dev-screen>` in the system.
-manager.machine.cassettes
- Returns a device enumerator that will iterate over
- :ref:`cassette image devices <luareference-dev-cass>` in the system.
-manager.machine.images
- Returns a device enumerator that will iterate over
- :ref:`media image devices <luareference-dev-diimage>` in the system.
-manager.machine.slots
- Returns a device enumerator that will iterate over
- :ref:`slot devices <luareference-dev-dislot>` in the system.
-emu.device_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`devices <luareference-dev-device>` in the sub-tree starting at the
- specified device. The specified device will be included. If the depth is
- provided, it must be an integer specifying the maximum number of levels to
- iterate below the specified device (i.e. 1 will limit iteration to the
- device and its immediate children).
-emu.screen_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`screen devices <luareference-dev-screen>` in the sub-tree starting at
- the specified device. The specified device will be included if it is a
- screen device. If the depth is provided, it must be an integer specifying
- the maximum number of levels to iterate below the specified device (i.e. 1
- will limit iteration to the device and its immediate children).
-emu.cassette_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`cassette image devices <luareference-dev-cass>` in the sub-tree
- starting at the specified device. The specified device will be included if
- it is a cassette image device. If the depth is provided, it must be an
- integer specifying the maximum number of levels to iterate below the
- specified device (i.e. 1 will limit iteration to the device and its
- immediate children).
-emu.image_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`media image devices <luareference-dev-diimage>` in the sub-tree
- starting at the specified device. The specified device will be included if
- it is a media image device. If the depth is provided, it must be an integer
- specifying the maximum number of levels to iterate below the specified
- device (i.e. 1 will limit iteration to the device and its immediate
- children).
-emu.slot_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`slot devices <luareference-dev-dislot>` in the sub-tree starting at
- the specified device. The specified device will be included if it is a
- slot device. If the depth is provided, it must be an integer specifying the
- maximum number of levels to iterate below the specified device (i.e. 1 will
- limit iteration to the device and its immediate children).
-
-.. _luareference-dev-device:
-
-Device
-~~~~~~
-
-Wraps MAME’s ``device_t`` class, which is a base of all device classes.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]
- Gets a device by tag relative to the root machine device, or ``nil`` if no
- such device exists.
-manager.machine.devices[tag]:subdevice(tag)
- Gets a device by tag relative to another arbitrary device, or ``nil`` if no
- such device exists.
-
-Methods
-^^^^^^^
-
-device:subtag(tag)
- Converts a tag relative to the device to an absolute tag.
-device:siblingtag(tag)
- Converts a tag relative to the device’s parent device to an absolute tag.
-device:memshare(tag)
- Gets a :ref:`memory share <luareference-mem-share>` by tag relative to the
- device, or ``nil`` if no such memory share exists.
-device:membank(tag)
- Gets a :ref:`memory bank <luareference-mem-bank>` by tag relative to the
- device, or ``nil`` if no such memory bank exists.
-device:memregion(tag)
- Gets a :ref:`memory region <luareference-mem-region>` by tag relative to the
- device, or ``nil`` if no such memory region exists.
-device:ioport(tag)
- Gets an :ref:`I/O port <luareference-input-ioport>` by tag relative to the
- device, or ``nil`` if no such I/O port exists.
-device:subdevice(tag)
- Gets a device by tag relative to the device.
-device:siblingdevice(tag)
- Gets a device by tag relative to the device’s parent.
-device:parameter(tag)
- Gets a parameter value by tag relative to the device, or an empty string if
- the parameter is not set.
-
-Properties
-^^^^^^^^^^
-
-device.tag (read-only)
- The device’s absolute tag in canonical form.
-device.basetag (read-only)
- The last component of the device’s tag (i.e. its tag relative to its
- immediate parent), or ``"root"`` for the root machine device.
-device.name (read-only)
- The full display name for the device’s type.
-device.shortname (read-only)
- The short name of the devices type (this is used, e.g. on the command line,
- when looking for resource like ROMs or artwork, and in various data files).
-device.owner (read-only)
- The device’s immediate parent in the device tree, or ``nil`` for the root
- machine device.
-device.configured (read-only)
- A Boolean indicating whether the device has completed configuration.
-device.started (read-only)
- A Boolean indicating whether the device has completed starting.
-device.debug (read-only)
- The :ref:`debugger interface <luareference-debug-devdebug>` to the device if
- it is a CPU device, or ``nil`` if it is not a CPU device or the debugger is
- not enabled.
-device.spaces[] (read-only)
- A table of the device’s :ref:`address spaces <luareference-mem-space>`,
- indexed by name. Only valid for devices that implement the memory
- interface. Note that the names are specific to the device type and have no
- special significance.
-
-.. _luareference-dev-screen:
-
-Screen device
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``screen_device`` class, which represents an emulated video output.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.screens[tag]
- Gets a screen device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a screen device.
-
-Base classes
-^^^^^^^^^^^^
-
-* :ref:`luareference-dev-device`
-
-Methods
-^^^^^^^
-
-screen:orientation()
- Returns the rotation angle in degrees (will be one of 0, 90, 180 or 270),
- whether the screen is flipped left-to-right, and whether the screen is
- flipped top-to-bottom. This is the final screen orientation after the
- screen orientation specified in the machine configuration and the rotation
- for the system driver are applied.
-screen:time_until_pos(v, [h])
- Gets the time remaining until the raster reaches the specified position. If
- the horizontal component of the position is not specified, it defaults to
- zero (0, i.e. the beginning of the line). The result is a floating-point
- number in units of seconds.
-screen:time_until_vblank_start()
- Gets the time remaining until the start of the vertical blanking interval.
- The result is a floating-point number in units of seconds.
-screen:time_until_vblank_end()
- Gets the time remaining until the end of the vertical blanking interval.
- The result is a floating-point number in units of seconds.
-screen:snapshot([filename])
- Saves a screen snapshot in PNG format. If no filename is supplied, the
- configured snapshot path and name format will be used. If the supplied
- filename is not an absolute path, it is interpreted relative to the first
- configured snapshot path. The filename may contain conversion specifiers
- that will be replaced by the system name or an incrementing number.
-
- Returns a file error if opening the snapshot file failed, or ``nil``
- otherwise.
-screen:pixel(x, y)
- Gets the pixel at the specified location. Coordinates are in pixels, with
- the origin at the top left corner of the visible area, increasing to the
- right and down. Returns either a palette index or a colour in RGB format
- packed into a 32-bit integer. Returns zero (0) if the specified point is
- outside the visible area.
-screen:pixels()
- Returns all visible pixels as 32-bit integers packed into a binary string in
- host Endian order. Pixels are organised in row-major order, from left to
- right then top to bottom. Pixels values are either palette indices or
- colours in RGB format packed into 32-bit integers.
-screen:draw_box(left, top, right, bottom, [line], [fill])
- Draws an outlined rectangle with edges at the specified positions.
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The fill and line colours are in alpha/red/green/blue (ARGB) format.
- Channel values are in the range 0 (transparent or off) to 255 (opaque or
- full intensity), inclusive. Colour channel values are not pre-multiplied by
- the alpha value. The channel values must be packed into the bytes of a
- 32-bit unsigned integer, in the order alpha, red, green, blue from
- most-significant to least-significant byte. If the line colour is not
- provided, the UI text colour is used; if the fill colour is not provided,
- the UI background colour is used.
-screen:draw_line(x1, y1, x2, y2, [color])
- Draws a line from (x1, y1) to (x2, y2).
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The line colour is in alpha/red/green/blue (ARGB) format. Channel values
- are in the range 0 (transparent or off) to 255 (opaque or full intensity),
- inclusive. Colour channel values are not pre-multiplied by the alpha value.
- The channel values must be packed into the bytes of a 32-bit unsigned
- integer, in the order alpha, red, green, blue from most-significant to
- least-significant byte. If the line colour is not provided, the UI text
- colour is used.
-screen:draw_text(x|justify, y, text, [foreground], [background])
- Draws text at the specified position. If the screen is rotated the text
- will be rotated.
-
- If the first argument is a number, the text will be left-aligned at this X
- coordinate. If the first argument is a string, it must be ``"left"``,
- ``"center"`` or ``"right"`` to draw the text left-aligned at the
- left edge of the screen, horizontally centred on the screen, or
- right-aligned at the right edge of the screen, respectively. The second
- argument specifies the Y coordinate of the maximum ascent of the text.
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The foreground and background colours are in alpha/red/green/blue (ARGB)
- format. Channel values are in the range 0 (transparent or off) to 255
- (opaque or full intensity), inclusive. Colour channel values are not
- pre-multiplied by the alpha value. The channel values must be packed into
- the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
- from most-significant to least-significant byte. If the foreground colour
- is not provided, the UI text colour is used; if the background colour is not
- provided, it is fully transparent.
-
-Properties
-^^^^^^^^^^
-
-screen.width (read-only)
- The width of the bitmap produced by the emulated screen in pixels.
-screen.height (read-only)
- The height of the bitmap produced by the emulated screen in pixels.
-screen.refresh (read-only)
- The screen’s configured refresh rate in Hertz (this may not reflect the
- current value).
-screen.refresh_attoseconds (read-only)
- The screen’s configured refresh interval in attoseconds (this may not
- reflect the current value).
-screen.xoffset (read-only)
- The screen’s default X position offset. This is a floating-point number
- where one (1) corresponds to the X size of the screen’s container. This may
- be useful for restoring the default after adjusting the X offset via the
- screen’s container.
-screen.yoffset (read-only)
- The screen’s default Y position offset. This is a floating-point number
- where one (1) corresponds to the Y size of the screen’s container. This may
- be useful for restoring the default after adjusting the Y offset via the
- screen’s container.
-screen.xscale (read-only)
- The screen’s default X scale factor, as a floating-point number. This may
- be useful for restoring the default after adjusting the X scale via the
- screen’s container.
-screen.yscale (read-only)
- The screen’s default Y scale factor, as a floating-point number. This may
- be useful for restoring the default after adjusting the Y scale via the
- screen’s container.
-screen.pixel_period (read-only)
- The interval taken to draw a horizontal pixel, as a floating-point number in
- units of seconds.
-screen.scan_period (read-only)
- The interval taken to draw a scan line (including the horizontal blanking
- interval), as a floating-point number in units of seconds.
-screen.frame_period (read-only)
- The interval taken to draw a complete frame (including blanking intervals),
- as a floating-point number in units of seconds.
-screen.frame_number (read-only)
- The current frame number for the screen. This increments monotonically each
- frame interval.
-screen.container (read-only)
- The :ref:`render container <luareference-render-container>` used to draw the
- screen.
-
-.. _luareference-dev-cass:
-
-Cassette image device
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``cassette_image_device`` class, representing a compact cassette
-mechanism typically used by a home computer for program storage.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.cassettes[tag]
- Gets a cassette image device by tag relative to the root machine device, or
- ``nil`` if no such device exists or it is not a cassette image device.
-
-Base classes
-^^^^^^^^^^^^
-
-* :ref:`luareference-dev-device`
-* :ref:`luareference-dev-diimage`
-
-Methods
-^^^^^^^
-
-cassette:stop()
- Disables playback.
-cassette:play()
- Enables playback. The cassette will play if the motor is enabled.
-cassette:forward()
- Sets forward play direction.
-cassette:reverse()
- Sets reverse play direction.
-cassette:seek(time, whence)
- Jump to the specified position on the tape. The time is a floating-point
- number in units of seconds, relative to the point specified by the whence
- argument. The whence argument must be one of ``"set"``, ``"cur"`` or
- ``"end"`` to seek relative to the start of the tape, the current position,
- or the end of the tape, respectively.
-
-Properties
-^^^^^^^^^^
-
-cassette.is_stopped (read-only)
- A Boolean indicating whether the cassette is stopped (i.e. not recording and
- not playing).
-cassette.is_playing (read-only)
- A Boolean indicating whether playback is enabled (i.e. the cassette will
- play if the motor is enabled).
-cassette.is_recording (read-only)
- A Boolean indicating whether recording is enabled (i.e. the cassette will
- record if the motor is enabled).
-cassette.motor_state (read/write)
- A Boolean indicating whether the cassette motor is enabled.
-cassette.speaker_state (read/write)
- A Boolean indicating whether the cassette speaker is enabled.
-cassette.position (read-only)
- The current position as a floating-point number in units of seconds relative
- to the start of the tape.
-cassette.length (read-only)
- The length of the tape as a floating-point number in units of seconds, or
- zero (0) if no tape image is mounted.
-
-.. _luareference-dev-diimage:
-
-Image device interface
-~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_image_interface`` class which is a mix-in implemented by
-devices that can load media image files.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.images[tag]
- Gets an image device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a media image device.
-
-Methods
-^^^^^^^
-
-image:load(filename)
- Loads the specified file as a media image. Returns ``"pass"`` or
- ``"fail"``.
-image:load_software(name)
- Loads a media image described in a software list. Returns ``"pass"`` or
- ``"fail"``.
-image:unload()
- Unloads the mounted image.
-image:create(filename)
- Creates and mounts a media image file with the specified name. Returns
- ``"pass"`` or ``"fail"``.
-image:display()
- Returns a “front panel display” string for the device, if supported. This
- can be used to show status information, like the current head position or
- motor state.
-
-Properties
-^^^^^^^^^^
-
-image.is_readable (read-only)
- A Boolean indicating whether the device supports reading.
-image.is_writeable (read-only)
- A Boolean indicating whether the device supports writing.
-image.must_be_loaded (read-only)
- A Boolean indicating whether the device requires a media image to be loaded
- in order to start.
-image.is_reset_on_load (read-only)
- A Boolean indicating whether the device requires a hard reset to change
- media images (usually for cartridge slots that contain hardware in addition
- to memory chips).
-image.image_type_name (read-only)
- A string for categorising the media device.
-image.instance_name (read-only)
- The instance name of the device in the current configuration. This is used
- for setting the media image to load on the command line or in INI files.
- This is not stable, it may have a number appended that may change depending
- on slot configuration.
-image.brief_instance_name (read-only)
- The brief instance name of the device in the current configuration. This is
- used for setting the media image to load on the command line or in INI
- files. This is not stable, it may have a number appended that may change
- depending on slot configuration.
-image.formatlist[] (read-only)
- The :ref:`media image formats <luareference-dev-imagefmt>` supported by the
- device, indexed by name. The index operator and ``index_of`` methods have
- O(n) complexity; all other supported operations have O(1) complexity.
-image.exists (read-only)
- A Boolean indicating whether a media image file is mounted.
-image.readonly (read-only)
- A Boolean indicating whether a media image file is mounted in read-only
- mode.
-image.filename (read-only)
- The full path to the mounted media image file, or ``nil`` if no media image
- is mounted.
-image.crc (read-only)
- The 32-bit cyclic redundancy check of the content of the mounted image file
- if the mounted media image was not loaded from a software list, is mounted
- read-only and is not a CD-ROM, or zero (0) otherwise.
-image.loaded_through_softlist (read-only)
- A Boolean indicating whether the mounted media image was loaded from a
- software list, or ``false`` if no media image is mounted.
-image.software_list_name (read-only)
- The short name of the software list if the mounted media image was loaded
- from a software list.
-image.software_longname (read-only)
- The full name of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_publisher (read-only)
- The publisher of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_year (read-only)
- The release year of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_parent (read-only)
- The short name of the parent software item if the mounted media image was
- loaded from a software list, or ``nil`` otherwise.
-image.device (read-only)
- The underlying :ref:`device <luareference-dev-device>`.
-
-.. _luareference-dev-dislot:
-
-Slot device interface
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_slot_interface`` class which is a mix-in implemented by
-devices that instantiate a user-specified child device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.slots[tag]
- Gets an slot device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a slot device.
-
-Properties
-^^^^^^^^^^
-
-slot.fixed (read-only)
- A Boolean indicating whether this is a slot with a card specified in machine
- configuration that cannot be changed by the user.
-slot.has_selectable_options (read-only)
- A Boolean indicating whether the slot has any user-selectable options (as
- opposed to options that can only be selected programmatically, typically for
- fixed slots or to load media images).
-slot.options[] (read-only)
- The :ref:`slot options <luareference-dev-slotopt>` describing the child
- devices that can be instantiated by the slot, indexed by option value. The
- ``at`` and ``index_of`` methods have O(n) complexity; all other supported
- operations have O(1) complexity.
-slot.device (read-only)
- The underlying :ref:`device <luareference-dev-device>`.
-
-.. _luareference-dev-imagefmt:
-
-Media image format
-~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``image_device_format`` class, which describes a media file format
-supported by a :ref:`media image device <luareference-dev-diimage>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.images[tag].formatlist[name]
- Gets a media image format supported by a given device by name.
-
-Properties
-^^^^^^^^^^
-
-format.name (read-only)
- An abbreviated name used to identify the format. This often matches the
- primary filename extension used for the format.
-format.description (read-only)
- The full display name of the format.
-format.extensions[] (read-only)
- Yields a table of filename extensions used for the format.
-format.option_spec (read-only)
- A string describing options available when creating a media image using this
- format. The string is not intended to be human-readable.
-
-.. _luareference-dev-slotopt:
-
-Slot option
-~~~~~~~~~~~
-
-Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
-child device that a :ref:`slot device <luareference-dev-dislot>` can be
-configured to instantiate.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.slots[tag].options[name]
- Gets a slot option for a given :ref:`slot device <luareference-dev-dislot>`
- by name (i.e. the value used to select the option).
-
-Properties
-^^^^^^^^^^
-
-option.name (read-only)
- The name of the slot option. This is the value used to select this option
- on the command line or in an INI file.
-option.device_fullname (read-only)
- The full display name of the device type instantiated by this option.
-option.device_shortname (read-only)
- The short name of the device type instantiated by this option.
-option.selectable (read-only)
- A Boolean indicating whether the option may be selected by the user (options
- that are not user-selectable are typically used for fixed slots or to load
- media images).
-option.default_bios (read-only)
- The default BIOS setting for the device instantiated using this option, or
- ``nil`` if the default BIOS specified in the device’s ROM definitions will
- be used.
-option.clock (read-only)
- The configured clock frequency for the device instantiated using this
- option. This is an unsigned 32-bit integer. If the eight most-significant
- bits are all set, it is a ratio of the parent device’s clock frequency, with
- the numerator in bits 12-23 and the denominator in bits 0-11. If the eight
- most-significant bits are not all set, it is a frequency in Hertz.
-
-
-.. _luareference-mem:
-
-Memory system
--------------
-
-MAME’s Lua interface exposes various memory system objects, including address
-spaces, memory shares, memory banks, and memory regions. Scripts can read from
-and write to the emulated memory system.
-
-.. _luareference-mem-manager:
-
-Memory manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_manager`` class, which allows the memory shares, banks and
-regions in a system to be enumerated.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory
- Gets the global memory manager instance for the emulated system.
-
-Properties
-^^^^^^^^^^
-
-memory.shares[]
- The :ref:`memory shares <luareference-mem-share>` in the system, indexed by
- absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
- other supported operations have O(1) complexity.
-memory.banks[]
- The :ref:`memory banks <luareference-mem-bank>` in the system, indexed by
- absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
- other supported operations have O(1) complexity.
-memory.regions[]
- The :ref:`memory regions <luareference-mem-region>` in the system, indexed
- by absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity;
- all other supported operations have O(1) complexity.
-
-.. _luareference-mem-space:
-
-Address space
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``address_space`` class, which represent’s an address space
-belonging to a device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name]
- Gets the address space with the specified name for a given device. Note
- that names are specific to the device type.
-
-Methods
-^^^^^^^
-
-space:read_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified address.
-space:read_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- address.
-space:write_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified address.
-space:write_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- address.
-space:readv_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified virtual
- address. The address is translated with the debug read intent. Returns
- zero if address translation fails.
-space:readv_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- virtual address. The address is translated with the debug read intent.
- Returns zero if address translation fails.
-space:writev_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified virtual
- address. The address is translated with the debug write intent. Does not
- write if address translation fails.
-space:writev_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- virtual address. The address is translated with the debug write intent.
- Does not write if address translation fails.
-space:read_direct_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified address
- one byte at a time by obtaining a read pointer for each byte address. If
- a read pointer cannot be obtained for a byte address, the corresponding
- result byte will be zero.
-space:read_direct_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- address one byte at a time by obtaining a read pointer for each byte
- address. If a read pointer cannot be obtained for a byte address, the
- corresponding result byte will be zero.
-space:write_direct_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified address
- one byte at a time by obtaining a write pointer for each byte address. If
- a write pointer cannot be obtained for a byte address, the corresponding
- byte will not be written.
-space:write_direct_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- address one byte at a time by obtaining a write pointer for each byte
- address. If a write pointer cannot be obtained for a byte address, the
- corresponding byte will not be written.
-space:read_range(start, end, width, [step])
- Reads a range of addresses as a binary string. The end address must be
- greater than or equal to the start address. The width must be 8, 16, 30 or
- 64. If the step is provided, it must be a positive number of elements.
-
-Properties
-^^^^^^^^^^
-
-space.name (read-only)
- The display name for the address space.
-space.shift (read-only)
- The address granularity for the address space specified as the shift
- required to translate a byte address to a native address. Positive values
- shift towards the most significant bit (left) and negative values shift
- towards the least significant bit (right).
-space.index (read-only)
- The zero-based space index. Some space indices have special meanings for
- the debugger.
-space.address_mask (read-only)
- The address mask for the space.
-space.data_width (read-only)
- The data width for the space in bits.
-space.endianness (read-only)
- The Endianness of the space (``"big"`` or ``"little"``).
-space.map (read-only)
- The configured :ref:`address map <luareference-mem-map>` for the space or
- ``nil``.
-
-.. _luareference-mem-map:
-
-Address map
-~~~~~~~~~~~
-
-Wraps MAME’s ``address_map`` class, used to configure handlers for an address
-space.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map
- Gets the configured address map for an address space, or ``nil`` if no map
- is configured.
-
-Properties
-^^^^^^^^^^
-
-map.spacenum (read-only)
- The address space number of the address space the map is associated with.
-map.device (read-only)
- The device that owns the address space the map is associated with.
-map.unmap_value (read-only)
- The constant value to return from unmapped reads.
-map.global_mask (read-only)
- Global mask to be applied to all addresses when accessing the space.
-map.entries[] (read-only)
- The configured :ref:`entries <luareference-mem-mapentry>` in the address
- map. Uses 1-based integer indices. The index operator and the ``at``
- method have O(n) complexity.
-
-.. _luareference-mem-mapentry:
-
-Address map entry
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``address_map_entry`` class, representing an entry in a configured
-address map.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map.entries[index]
- Gets an entry from the configured map for an address space.
-
-Properties
-^^^^^^^^^^
-
-entry.address_start (read-only)
- Start address of the entry’s range.
-entry.address_end (read-only)
- End address of the entry’s range (inclusive).
-entry.address_mirror (read-only)
- Address mirror bits.
-entry.address_mask (read-only)
- Address mask bits. Only valid for handlers.
-entry.mask (read-only)
- Lane mask, indicating which data lines on the bus are connected to the
- handler.
-entry.cswidth (read-only)
- The trigger width for a handler that isn’t connected to all the data lines.
-entry.read (read-only)
- :ref:`Additional data <luareference-memory-handlerdata>` for the read
- handler.
-entry.write (read-only)
- :ref:`Additional data <luareference-memory-handlerdata>` for the write
- handler.
-entry.share (read-only)
- Memory share tag for making RAM entries accessible or ``nil``.
-entry.region (read-only)
- Explicit memory region tag for ROM entries, or ``nil``. For ROM entries,
- ``nil`` infers the region from the device tag.
-entry.region_offset (read-only)
- Starting offset in memory region for ROM entries.
-
-.. _luareference-memory-handlerdata:
-
-Address map handler data
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``map_handler_data`` class, which provides configuration data to
-handlers in address maps.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map.entries[index].read
- Gets the read handler data for an address map entry.
-manager.machine.devices[tag].spaces[name].map.entries[index].write
- Gets the write handler data for an address map entry.
-
-Properties
-^^^^^^^^^^
-
-data.handlertype (read-only)
- Handler type. Will be one of ``"none"``, ``"ram"``, ``"rom"``, ``"nop"``,
- ``"unmap"``, ``"delegate"``, ``"port"``, ``"bank"``, ``"submap"``, or
- ``"unknown"``. Note that multiple handler type values can yield
- ``"delegate"`` or ``"unknown"``.
-data.bits (read-only)
- Data width for the handler in bits.
-data.name (read-only)
- Display name for the handler, or ``nil``.
-data.tag (read-only)
- Tag for I/O ports and memory banks, or ``nil``.
-
-.. _luareference-mem-share:
-
-Memory share
-~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_share`` class, representing a named allocated memory zone.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.shares[tag]
- Gets a memory share by absolute tag, or ``nil`` if no such memory share
- exists.
-manager.machine.devices[tag]:memshare(tag)
- Gets a memory share by tag relative to a device, or ``nil`` if no such
- memory share exists.
-
-Methods
-^^^^^^^
-
-share:read_i{8,16,32,64}(offs)
- Reads a signed integer value of the size in bits from the specified offset
- in the memory share.
-share:read_u{8,16,32,64}(offs)
- Reads an unsigned integer value of the size in bits from the specified
- offset in the memory share.
-share:write_i{8,16,32,64}(offs, val)
- Writes a signed integer value of the size in bits to the specified offset in
- the memory share.
-share:write_u{8,16,32,64}(offs, val)
- Writes an unsigned integer value of the size in bits to the specified offset
- in the memory share.
-
-Properties
-^^^^^^^^^^
-
-share.tag (read-only)
- The absolute tag of the memory share.
-share.size (read-only)
- The size of the memory share in bytes.
-share.length (read-only)
- The length of the memory share in native width elements.
-share.endianness (read-only)
- The Endianness of the memory share (``"big"`` or ``"little"``).
-share.bitwidth (read-only)
- The native element width of the memory share in bits.
-share.bytewidth (read-only)
- The native element width of the memory share in bytes.
-
-.. _luareference-mem-bank:
-
-Memory bank
-~~~~~~~~~~~
-
-Wraps MAME’s ``memory_bank`` class, representing a named memory zone
-indirection.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.banks[tag]
- Gets a memory region by absolute tag, or ``nil`` if no such memory bank
- exists.
-manager.machine.devices[tag]:membank(tag)
- Gets a memory region by tag relative to a device, or ``nil`` if no such
- memory bank exists.
-
-Properties
-^^^^^^^^^^
-
-bank.tag (read-only)
- The absolute tag of the memory bank.
-bank.entry (read/write)
- The currently selected zero-based entry number.
-
-.. _luareference-mem-region:
-
-Memory region
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_region`` class, representing a memory region used to store
-read-only data like ROMs or the result of fixed decryptions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.regions[tag]
- Gets a memory region by absolute tag, or ``nil`` if no such memory region
- exists.
-manager.machine.devices[tag]:memregion(tag)
- Gets a memory region by tag relative to a device, or ``nil`` if no such
- memory region exists.
-
-Methods
-^^^^^^^
-
-region:read_i{8,16,32,64}(offs)
- Reads a signed integer value of the size in bits from the specified offset
- in the memory region.
-region:read_u{8,16,32,64}(offs)
- Reads an unsigned integer value of the size in bits from the specified
- offset in the memory region.
-region:write_i{8,16,32,64}(offs, val)
- Writes a signed integer value of the size in bits to the specified offset in
- the memory region.
-region:write_u{8,16,32,64}(offs, val)
- Writes an unsigned integer value of the size in bits to the specified offset
- in the memory region.
-
-Properties
-^^^^^^^^^^
-
-region.tag (read-only)
- The absolute tag of the memory region.
-region.size (read-only)
- The size of the memory region in bytes.
-region.length (read-only)
- The length of the memory region in native width elements.
-region.endianness (read-only)
- The Endianness of the memory region (``"big"`` or ``"little"``).
-region.bitwidth (read-only)
- The native element width of the memory region in bits.
-region.bytewidth (read-only)
- The native element width of the memory region in bytes.
-
-
-.. _luareference-input:
-
-Input system
-------------
-
-Allows scripts to get input from the user, and access I/O ports in the emulated
-system.
-
-.. _luareference-input-ioportman:
-
-I/O port manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O
-ports and handles input configuration.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport
- Gets the global I/O port manager instance for the emulated machine.
-
-Methods
-^^^^^^^
-
-ioport:count_players()
- Returns the number of player controllers in the system.
-ioport:type_pressed(type, [player])
- Returns a Boolean indicating whether the specified input is currently
- pressed. The input port type is an enumerated value. The player number is
- a zero-based index. If the player number is not supplied, it is assumed to
- be zero.
-ioport:type_name(type, [player])
- Returns the display name for the specified input type and player number.
- The input type is an enumerated value. The player number is a zero-based
- index. If the player number is not supplied, it is assumed to be zero.
-ioport:type_group(type, player)
- Returns the input group for the specified input type and player number. The
- input type is an enumerated value. The player number is a zero-based index.
- Returns an integer giving the grouping for the input. If the player number
- is not supplied, it is assumed to be zero.
-
- This should be called with values obtained from I/O port fields to provide
- canonical grouping in an input configuration UI.
-ioport:type_seq(type, [player], [seqtype])
- Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. If the player
- number is not supplied, it is assumed to be zero. If the sequence type is
- supplied, it must be ``"standard"``, ``"increment"`` or ``"decrement"``; if
- it is not supplied, it is assumed to be ``"standard"``.
-
- This provides access to general input configuration.
-ioport:set_type_seq(type, player, seqtype, seq)
- Set the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. The sequence
- type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
-
- This allows general input configuration to be set.
-ioport:token_to_input_type(string)
- Returns the input type and player number for the specified input type token.
-ioport:input_type_to_token(type, [player])
- Returns the token string for the specified input type and player number. If
- the player number is not supplied, it assumed to be zero.
-
-Properties
-^^^^^^^^^^
-
-ioport.ports[]
- Gets the emulated :ref:`I/O ports <luareference-input-ioport>` in the
- system. Keys are absolute tags. The ``at`` and ``index_of`` methods have
- O(n) complexity; all other supported operations have O(1) complexity.
-
-.. _luareference-input-natkbd:
-
-Natural keyboard manager
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and
-keypad inputs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.natkeyboard
- Gets the global natural keyboard manager instance for the emulated machine.
-
-Methods
-^^^^^^^
-
-natkeyboard:post(text)
- Post literal text to the emulated machine. The machine must have keyboard
- inputs with character bindings, and the correct keyboard input device must
- be enabled.
-natkeyboard:post_coded(text)
- Post text to the emulated machine. Brace-enclosed codes are interpreted in
- the text. The machine must have keyboard inputs with character bindings,
- and the correct keyboard input device must be enabled.
-
- The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``,
- ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``,
- ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``,
- ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``,
- ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``.
-natkeyboard:paste()
- Post the contents of the host clipboard to the emulated machine. The
- machine must have keyboard inputs with character bindings, and the correct
- keyboard input device must be enabled.
-natkeyboard:dump()
- Returns a string with a human-readable description of the keyboard and
- keypad input devices in the system, whether they are enabled, and their
- character bindings.
-
-Properties
-^^^^^^^^^^
-
-natkeyboard.empty (read-only)
- A Boolean indicating whether the natural keyboard manager’s input buffer is
- empty.
-natkeyboard.full (read-only)
- A Boolean indicating whether the natural keyboard manager’s input buffer is
- full.
-natkeyboard.can_post (read-only)
- A Boolean indicating whether the emulated system supports posting character
- data via the natural keyboard manager.
-natkeyboard.is_posting (read-only)
- A Boolean indicating whether posted character data is currently being
- delivered to the emulated system.
-natkeyboard.in_use (read/write)
- A Boolean indicating whether “natural keyboard” mode is enabled. When
- “natural keyboard” mode is enabled, the natural keyboard manager translates
- host character input to emulated system keystrokes.
-natkeyboard.keyboards[]
- Gets the :ref:`keyboard/keypad input devices <luareference-input-kbddev>` in
- the emulated system, indexed by absolute device tag. Index get has O(n)
- complexity; all other supported operations have O(1) complexity.
-
-.. _luareference-input-kbddev:
-
-Keyboard input device
-~~~~~~~~~~~~~~~~~~~~~
-
-Represents a keyboard or keypad input device managed by the
-:ref:`natural keyboard manager <luareference-input-natkbd>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.natkeyboard.keyboards[tag]
- Gets the keyboard input device with the specified tag, or ``nil`` if the tag
- does not correspond to a keyboard input device.
-
-Properties
-^^^^^^^^^^
-
-keyboard.device (read-only)
- The underlying device.
-keyboard.tag (read-only)
- The absolute tag of the underlying device.
-keyboard.basetag (read-only)
- The last component of the tag of the underlying device, or ``"root"`` for
- the root machine device.
-keyboard.name (read-only)
- The human-readable description of the underlying device type.
-keyboard.shortname (read-only)
- The identifier for the underlying device type.
-keyboard.is_keypad (read-only)
- A Boolean indicating whether the underlying device has keypad inputs but no
- keyboard inputs. This is used when determining which keyboard input devices
- should be enabled by default.
-keyboard.enabled (read/write)
- A Boolean indicating whether the device’s keyboard and/or keypad inputs are
- enabled.
-
-.. _luareference-input-ioport:
-
-I/O port
-~~~~~~~~
-
-Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]
- Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not
- correspond to an I/O port.
-manager.machine.devices[devtag]:ioport(porttag)
- Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such
- I/O port exists.
-
-Methods
-^^^^^^^
-
-port:read()
- Read the current input value. Returns a 32-bit integer.
-port:write(value, mask)
- Write to the I/O port output fields that are set in the specified mask. The
- value and mask must be 32-bit integers. Note that this does not set values
- for input fields.
-port:field(mask)
- Get the first :ref:`I/O port field <luareference-input-field>` corresponding
- to the bits that are set in the specified mask, or ``nil`` if there is no
- corresponding field.
-
-Properties
-^^^^^^^^^^
-
-port.device (read-only)
- The device that owns the I/O port.
-port.tag (read-only)
- The absolute tag of the I/O port
-port.active (read-only)
- A mask indicating which bits of the I/O port correspond to active fields
- (i.e. not unused or unassigned bits).
-port.live (read-only)
- The live state of the I/O port.
-port.fields[] (read-only)
- Gets a table of :ref:`fields <luareference-input-field>` indexed by name.
-
-.. _luareference-input-field:
-
-I/O port field
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]:field[mask]
- Gets a field for the given port by bit mask.
-manager.machine.ioport.ports[tag].fields[name]
- Gets a field for the given port by display name.
-
-Methods
-^^^^^^^
-
-field:set_value(value)
- Set the value of the I/O port field. For digital fields, the value is
- compared to zero to determine whether the field should be active; for
- analog fields, the value must be right-aligned and in the correct range.
-field:set_input_seq(seqtype, seq)
- Set the :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This is used to configure per-machine input
- settings. The sequence type must be ``"standard"``, ``"increment"`` or
- ``"decrement"``.
-field:input_seq(seq_type)
- Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This gets per-machine input assignments. The
- sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
-field:set_default_input_seq(seq_type, seq)
- Set the default :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This overrides the default input assignment for a
- specific input. The sequence type must be ``"standard"``, ``"increment"``
- or ``"decrement"``.
-field:default_input_seq(seq_type)
- Gets the default :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. If the default assignment is not overridden, this
- gets the general input assignment. The sequence type must be
- ``"standard"``, ``"increment"`` or ``"decrement"``.
-field:keyboard_codes(shift)
- Gets a table of characters corresponding to the field for the specified
- shift state. The shift state is a bit mask of active shift keys.
-
-Properties
-^^^^^^^^^^
-
-field.device (read-only)
- The device that owns the port that the field belongs to.
-field.port (read-only)
- The :ref:`I/O port <luareference-input-ioport>` that the field belongs to.
-field.live (read-only)
- The :ref:`live state <luareference-input-fieldlive>` of the field.
-field.type (read-only)
- The input type of the field. This is an enumerated value.
-field.name (read-only)
- The display name for the field.
-field.default_name (read-only)
- The name for the field from the emulated system’s configuration (cannot be
- overridden by scripts or plugins).
-field.player (read-only)
- Zero-based player number for the field.
-field.mask (read-only)
- Bits in the I/O port corresponding to this field.
-field.defvalue (read-only)
- The field’s default value
-field.sensitivity (read-only)
- The sensitivity or gain for analog fields
-field.way (read-only)
- The number of directions allowed by the restrictor plate/gate for a digital
- joystick, or zero (0) for other inputs.
-field.type_class (read-only)
- The type class for the input field – one of ``"keyboard"``,
- ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``.
-field.is_analog (read-only)
- A Boolean indicating whether the field is an analog axis or positional
- control.
-field.is_digital_joystick (read-only)
- A Boolean indicating whether the field corresponds to a digital joystick
- switch.
-field.enabled (read-only)
- A Boolean indicating whether the field is enabled.
-field.optional (read-only)
- A Boolean indicating whether the field is optional and not required to use
- the emulated system.
-field.cocktail (read-only)
- A Boolean indicating whether the field is only used when the system is
- configured for a cocktail table cabinet.
-field.toggle (read-only)
- A Boolean indicating whether the field corresponds to a hardware toggle
- switch or push-on, push-off button.
-field.rotated (read-only)
- A Boolean indicating whether the field corresponds to a control that is
- rotated relative its standard orientation.
-field.analog_reverse (read-only)
- A Boolean indicating whether the field corresponds to an analog control that
- increases in the opposite direction to the convention (e.g. larger values
- when a pedal is released or a joystick is moved to the left).
-field.analog_reset (read-only)
- A Boolean indicating whether the field corresponds to an incremental
- position input (e.g. a dial or trackball axis) that should be reset to zero
- for every video frame.
-field.analog_wraps (read-only)
- A Boolean indicating whether the field corresponds to an analog input that
- wraps from one end of its range to the other (e.g. an incremental position
- input like a dial or trackball axis).
-field.analog_invert (read-only)
- A Boolean indicating whether the field corresponds to an analog input that
- has its value ones-complemented.
-field.impulse (read-only)
- A Boolean indicating whether the field corresponds to a digital input that
- activates for a fixed amount of time.
-field.crosshair_scale (read-only)
- The scale factor for translating the field’s range to crosshair position. A
- value of one (1) translates the field’s full range to the full width or
- height the screen.
-field.crosshair_offset (read-only)
- The offset for translating the field’s range to crosshair position.
-field.user_value (read/write)
- The value for DIP switch or configuration settings.
-field.settings[] (read-only)
- Gets a table of the currently enabled settings for a DIP switch or
- configuration field, indexed by value.
-
-.. _luareference-input-fieldlive:
-
-Live I/O port field state
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O
-port field.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]:field(mask).live
- Gets the live state for an I/O port field.
-
-Properties
-^^^^^^^^^^
-
-live.name
- Display name for the field.
-
-.. _luareference-input-inputman:
-
-Input manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_manager`` class, which reads host input devices and checks
-whether configured inputs are active.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input
- Gets the global input manager instance for the emulated system.
-
-Methods
-^^^^^^^
-
-input:code_value(code)
- Gets the current value for the host input corresponding to the specified
- code. Returns a signed integer value, where zero is the neutral position.
-input:code_pressed(code)
- Returns a Boolean indicating whether the host input corresponding to the
- specified code has a non-zero value (i.e. it is not in the neutral
- position).
-input:code_pressed_once(code)
- Returns a Boolean indicating whether the host input corresponding to the
- specified code has moved away from the neutral position since the last time
- it was checked using this function. The input manager can track a limited
- number of inputs this way.
-input:code_name(code)
- Get display name for an input code.
-input:code_to_token(code)
- Get token string for an input code. This should be used when saving
- configuration.
-input:code_from_token(token)
- Convert a token string to an input code. Returns the invalid input code if
- the token is not valid or belongs to an input device that is not present.
-input:seq_pressed(seq)
- Returns a Boolean indicating whether the supplied
- :ref:`input sequence <luareference-input-iptseq>` is currently pressed.
-input:seq_clean(seq)
- Remove invalid elements from the supplied
- :ref:`input sequence <luareference-input-iptseq>`. Returns the new, cleaned
- input sequence.
-input:seq_name(seq)
- Get display text for an :ref:`input sequence <luareference-input-iptseq>`.
-input:seq_to_tokens(seq)
- Convert an :ref:`input sequence <luareference-input-iptseq>` to a token
- string. This should be used when saving configuration.
-input:seq_from_tokens(tokens)
- Convert a token string to an
- :ref:`input sequence <luareference-input-iptseq>`. This should be used when
- loading configuration.
-input:axis_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining an analog host input code.
-input:switch_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining a host switch input code.
-input:keyboard_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining a host switch input code that only considers keyboard input
- devices.
-input:axis_sequence_poller()
- Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an :ref:`input sequence <luareference-input-iptseq>` for
- configuring an analog input.
-input:axis_sequence_poller()
- Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an :ref:`input sequence <luareference-input-iptseq>` for
- configuring a digital input.
-
-Properties
-^^^^^^^^^^
-
-input.device_classes[] (read-only)
- Gets a table of host
- :ref:`input device classes <luareference-input-devclass>` indexed by name.
-
-.. _luareference-input-codepoll:
-
-Input code poller
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being
-activated.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input:axis_code_poller()
- Returns an input code poller that polls for analog inputs being activated.
-manager.machine.input:switch_code_poller()
- Returns an input code poller that polls for host switch inputs being
- activated.
-manager.machine.input:keyboard_code_poller()
- Returns an input code poller that polls for host switch inputs being
- activated, only considering keyboard input devices.
-
-Methods
-^^^^^^^
-
-poller:reset()
- Resets the polling logic. Active switch inputs are cleared and initial
- analog input positions are set.
-poller:poll()
- Returns an input code corresponding to the first relevant host input that
- has been activated since the last time the method was called. Returns the
- invalid input code if no relevant input has been activated.
-
-.. _luareference-input-seqpoll:
-
-Input sequence poller
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to
-assign host input combinations to emulated inputs and other actions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input:axis_sequence_poller()
- Returns an input sequence poller for assigning host inputs to an analog
- input.
-manager.machine.input:switch_sequence_poller()
- Returns an input sequence poller for assigning host inputs to a switch
- input.
-
-Methods
-^^^^^^^
-
-poller:start([seq])
- Start polling. If a sequence is supplied, it is used as a starting
- sequence: for analog inputs, the user can cycle between the full range, and
- the positive and negative portions of an axis; for switch inputs, an “or”
- code is appended and the user can add an alternate host input combination.
-poller:poll()
- Polls for for user input and updates the sequence if appropriate. Returns a
- Boolean indicating whether sequence input is complete. If this method
- returns false, you should continue polling.
-
-Properties
-^^^^^^^^^^
-
-poller.sequence (read-only)
- The current :ref:`input sequence <luareference-input-iptseq>`. This is
- updated while polling. It is possible for the sequence to become invalid.
-poller.valid (read-only)
- A Boolean indicating whether the current input sequence is valid.
-poller.modified (read-only)
- A Boolean indicating whether the sequence was changed by any user input
- since starting polling.
-
-.. _luareference-input-iptseq:
-
-Input sequence
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
-can be read or assigned to an emulated input. Input sequences can be
-manipulated using :ref:`input manager <luareference-input-inputman>` methods.
-Use an :ref:`input sequence poller <luareference-input-seqpoll>` to obtain an
-input sequence from the user.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.input_seq()
- Creates an empty input sequence.
-emu.input_seq(seq)
- Creates a copy of an existing input sequence.
-
-Methods
-^^^^^^^
-
-seq:reset()
- Clears the input sequence, removing all items.
-seq:set_default()
- Sets the input sequence to a single item containing the metavalue specifying
- that the default setting should be used.
-
-Properties
-^^^^^^^^^^
-
-seq.empty (read-only)
- A Boolean indicating whether the input sequence is empty (contains no items,
- indicating an unassigned input).
-seq.length (read-only)
- The number of items in the input sequence.
-seq.is_valid (read-only)
- A Boolean indicating whether the input sequence is a valid. To be valid, it
- must contain at least one item, all items must be valid codes, all product
- groups must contain at least one item that is not negated, and items
- referring to absolute and relative axes must not be mixed within a product
- group.
-seq.is_default (read-only)
- A Boolean indicating whether the input sequence specifies that the default
- setting should be used.
-
-.. _luareference-input-devclass:
-
-Host input device class
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_class`` class, representing a category of host input
-devices (e.g. keyboards or joysticks).
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name]
- Gets an input device class by name.
-
-Properties
-^^^^^^^^^^
-
-devclass.name (read-only)
- The device class name.
-devclass.enabled (read-only)
- A Boolean indicating whether the device class is enabled.
-devclass.multi (read-only)
- A Boolean indicating whether the device class supports multiple devices, or
- inputs from all devices in the class are combined and treated as a single
- device.
-devclass.devices[] (read-only)
- Gets a table of :ref:`host input devices <luareference-input-inputdev>` in
- the class. Keys are one-based indices.
-
-.. _luareference-input-inputdev:
-
-Host input device
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_device`` class, representing a host input device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name].devices[index]
- Gets a specific host input device.
-
-Properties
-^^^^^^^^^^
-
-inputdev.name (read-only)
- Display name for the device. This is not guaranteed to be unique.
-inputdev.id (read-only)
- Unique identifier string for the device. This may not be human-readable.
-inputdev.devindex (read-only)
- Device index within the device class. This is not necessarily the same as
- the index in the ``devices`` property of the device class – the ``devindex``
- indices may not be contiguous.
-inputdev.items (read-only)
- Gets a table of :ref:`input items <luareference-input-inputitem>`, indexed
- by item ID. The item ID is an enumerated value.
-
-.. _luareference-input-inputitem:
-
-Host input device item
-~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g.
-a key, button, or axis).
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name].devices[index].items[id]
- Gets an individual host input item. The item ID is an enumerated value.
-
-Properties
-^^^^^^^^^^
-
-item.name (read-only)
- The display name of the input item. Note that this is just the name of the
- item itself, and does not include the device name. The full display name
- for the item can be obtained by calling the ``code_name`` method on the
- :ref:`input manager <luareference-input-inputman>` with the item’s code.
-item.code (read-only)
- The input item’s identification code. This is used by several
- :ref:`input manager <luareference-input-inputman>` methods.
-item.token (read-only)
- The input item’s token string. Note that this is a token fragment for the
- item itself, and does not include the device portion. The full token for
- the item can be obtained by calling the ``code_to_token`` method on the
- :ref:`input manager <luareference-input-inputman>` with the item’s code.
-item.current (read-only)
- The item’s current value. This is a signed integer where zero is the
- neutral position.
-
-.. _luareference-input-uiinput:
-
-UI input manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.uiinput
- Gets the global UI input manager instance for the machine.
-
-Methods
-^^^^^^^
-
-uiinput:find_mouse()
- Returns host system mouse pointer X position, Y position, button state, and
- the :ref:`render target <luareference-render-target>` it falls in. The
- position is in host pixels, where zero is at the top/left. The button state
- is a Boolean indicating whether the primary mouse button is pressed.
-
- If the mouse pointer is not over one of MAME’s windows, this may return the
- position and render target from when the mouse pointer was most recently
- over one of MAME’s windows. The render target may be ``nil`` if the mouse
- pointer is not over one of MAME’s windows.
-uiinput:pressed(type)
- Returns a Boolean indicating whether the specified UI input has been
- pressed. The input type is an enumerated value.
-uiinput:pressed_repeat(type, speed)
- Returns a Boolean indicating whether the specified UI input has been
- pressed or auto-repeat has been triggered at the specified speed. The input
- type is an enumerated value; the speed is an interval in sixtieths of a
- second.
-
-Properties
-^^^^^^^^^^
-
-uiinput.presses_enabled (read/write)
- Whether the UI input manager will check for UI inputs frame updates.
-
-
-.. _luareference-render:
-
-Render system
--------------
-
-The render system is responsible for drawing what you see in MAME’s windows,
-including emulated screens, artwork, and UI elements.
-
-.. _luareference-render-bounds:
-
-Render bounds
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_bounds`` class, which represents a rectangle using
-floating-point coordinates.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.render_bounds()
- Creates a render bounds object representing a unit square, with top left
- corner at (0, 0) and bottom right corner at (1, 1). Note that render
- target coordinates don’t necessarily have equal X and Y scales, so this may
- not represent a square in the final output.
-emu.render_bounds(left, top, right, bottom)
- Creates a render bounds object representing a rectangle with top left
- corner at (x0, y0) and bottom right corner at (x1, y1).
-
- The arguments must all be floating-point numbers.
-
-Methods
-^^^^^^^
-
-bounds:includes(x, y)
- Returns a Boolean indicating whether the specified point falls within the
- rectangle. The rectangle must be normalised for this to work (right greater
- than left and bottom greater than top).
-
- The arguments must both be floating-point numbers.
-bounds:set_xy(left, top, right, bottom)
- Set the rectangle’s position and size in terms of the positions of the
- edges.
-
- The arguments must all be floating-point numbers.
-bounds:set_wh(left, top, width, height)
- Set the rectangle’s position and size in terms of the top top left corner
- position, and the width and height.
-
- The arguments must all be floating-point numbers.
-
-Properties
-^^^^^^^^^^
-
-bounds.x0 (read/write)
- The leftmost coordinate in the rectangle (i.e. the X coordinate of the left
- edge or the top left corner).
-bounds.x1 (read/write)
- The rightmost coordinate in the rectangle (i.e. the X coordinate of the
- right edge or the bottom right corner).
-bounds.y0 (read/write)
- The topmost coordinate in the rectangle (i.e. the Y coordinate of the top
- edge or the top left corner).
-bounds.y1 (read/write)
- The bottommost coordinate in the rectangle (i.e. the Y coordinate of the
- bottom edge or the bottom right corner).
-bounds.width (read/write)
- The width of the rectangle. Setting this property changes the position of
- the rightmost edge.
-bounds.height (read/write)
- The height of the rectangle. Setting this property changes the position of
- the bottommost edge.
-bounds.aspect (read-only)
- The width-to-height aspect ratio of the rectangle. Note that this is often
- in render target coordinates which don’t necessarily have equal X and Y
- scales. A rectangle representing a square in the final output doesn’t
- necessarily have an aspect ratio of 1.
-
-.. _luareference-render-color:
-
-Render colour
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_color`` class, which represents an ARGB (alpha, red,
-green, blue) format colour. Channels are floating-point values ranging from
-zero (0, transparent alpha or colour off) to one (1, opaque or full colour
-intensity). Colour channel values are not pre-multiplied by the alpha channel
-value.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.render_color()
- Creates a render colour object representing opaque white (all channels set
- to 1). This is the identity value – ARGB multiplication by this value will
- not change a colour.
-emu.render_color(a, r, g, b)
- Creates a render colour object with the specified alpha, red, green and
- blue channel values.
-
- The arguments must all be floating-point numbers in the range from zero (0)
- to one (1), inclusive.
-
-Methods
-^^^^^^^
-
-color:set(a, r, g, b)
- Sets the colour object’s alpha, red, green and blue channel values.
-
- The arguments must all be floating-point numbers in the range from zero (0)
- to one (1), inclusive.
-
-Properties
-^^^^^^^^^^
-
-color.a (read/write)
- Alpha value, in the range of zero (0, transparent) to one (1, opaque).
-color.r (read/write)
- Red channel value, in the range of zero (0, off) to one (1, full intensity).
-color.g (read/write)
- Green channel value, in the range of zero (0, off) to one (1, full
- intensity).
-color.b (read/write)
- Blue channel value, in the range of zero (0, off) to one (1, full
- intensity).
-
-.. _luareference-render-manager:
-
-Render manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_manager`` class, responsible for managing render targets
-and textures.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render
- Gets the global render manager instance for the emulation session.
-
-Properties
-^^^^^^^^^^
-
-render.max_update_rate (read-only)
- The maximum update rate in Hertz. This is a floating-point number.
-render.ui_target (read-only)
- The :ref:`render target <luareference-render-target>` used to draw the user
- interface (including menus, sliders and pop-up messages). This is usually
- the first host window or screen.
-render.ui_container (read-only)
- The :ref:`render container <luareference-render-container>` used for drawing
- the user interface.
-render.targets[] (read-only)
- The list of render targets, including output windows and screens, as well as
- hidden render targets used for things like rendering screenshots. Uses
- 1-based integer indices. The index operator and the ``at`` method have O(n)
- complexity.
-
-.. _luareference-render-target:
-
-Render target
-~~~~~~~~~~~~~
-
-Wrap’s MAME’s ``render_target`` class, which represents a video output channel.
-This could be a host window or screen, or a hidden target used for rendering
-screenshots.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render.targets[index]
- Gets a render target by index.
-manager.machine.render.ui_target
- Gets the render target used to display the user interface (including menus,
- sliders and pop-up messages). This is usually the first host window or
- screen.
-manager.machine.video.snapshot_target
- Gets the render target used to produce snapshots and video recordings.
-
-Properties
-^^^^^^^^^^
-
-target.index (read-only)
- The 1-based index of the render target. This has O(n) complexity.
-target.width (read-only)
- The width of the render target in output pixels. This is an integer.
-target.height (read-only)
- The height of the render target in output pixels. This is an integer.
-target.pixel_aspect (read-only)
- The width-to-height aspect ratio of the render target’s pixels. This is a
- floating-point number.
-target.hidden (read-only)
- A Boolean indicating whether this is an internal render target that is not
- displayed to the user directly (e.g. the render target used to draw
- screenshots).
-target.is_ui_target (read-only)
- A Boolean indicating whether this is the render target used to display the
- user interface.
-target.max_update_rate (read/write)
- The maximum update rate for the render target in Hertz.
-target.orientation (read/write)
- The target orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-target.view_names[]
- The names of the available views for this render target. Uses 1-based
- integer indices. The ``find`` and ``index_of`` methods have O(n)
- complexity; all other supported operations have O(1) complexity.
-target.current_view (read-only)
- The currently selected view for the render target. This is a
- :ref:`layout view <luareference-render-layview>` object.
-target.view_index (read/write)
- The 1-based index of the selected view for this render target.
-target.visibility_mask (read-only)
- An integer bit mask indicating which item collections are currently visible
- for the current view.
-target.screen_overlay (read/write)
- A Boolean indicating whether screen overlays are enabled.
-target.zoom_to_screen (read/write)
- A Boolean indicating whether the render target is configured to scale so
- that the emulated screen(s) fill as much of the output window/screen as
- possible.
-
-.. _luareference-render-container:
-
-Render container
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_container`` class.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render.ui_container
- Gets the render container used to draw the user interface, including menus,
- sliders and pop-up messages.
-manager.machine.screens[tag].container
- Gets the render container used to draw a given screen.
-
-Methods
-^^^^^^^
-
-container:draw_box(left, top, right, bottom, [line], [fill])
- Draws an outlined rectangle with edges at the specified positions.
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- The fill and line colours are in alpha/red/green/blue (ARGB) format.
- Channel values are in the range 0 (transparent or off) to 255 (opaque or
- full intensity), inclusive. Colour channel values are not pre-multiplied by
- the alpha value. The channel values must be packed into the bytes of a
- 32-bit unsigned integer, in the order alpha, red, green, blue from
- most-significant to least-significant byte. If the line colour is not
- provided, the UI text colour is used; if the fill colour is not provided,
- the UI background colour is used.
-container:draw_line(x1, y1, x2, y2, [color])
- Draws a line from (x1, y1) to (x2, y2).
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- Coordinates are floating-point numbers in units of screen pixels, with the
- origin at (0, 0). Note that screen pixels often aren’t square. The
- coordinate system is rotated if the screen is rotated, which is usually the
- case for vertical-format screens. Before rotation, the origin is at the top
- left, and coordinates increase to the right and downwards. Coordinates are
- limited to the screen area.
-
- The line colour is in alpha/red/green/blue (ARGB) format. Channel values
- are in the range 0 (transparent or off) to 255 (opaque or full intensity),
- inclusive. Colour channel values are not pre-multiplied by the alpha value.
- The channel values must be packed into the bytes of a 32-bit unsigned
- integer, in the order alpha, red, green, blue from most-significant to
- least-significant byte. If the line colour is not provided, the UI text
- colour is used.
-container:draw_text(x|justify, y, text, [foreground], [background])
- Draws text at the specified position. If the screen is rotated the text
- will be rotated.
-
- If the first argument is a number, the text will be left-aligned at this X
- coordinate. If the first argument is a string, it must be ``"left"``,
- ``"center"`` or ``"right"`` to draw the text left-aligned at the
- left edge of the window or screen, horizontally centred in the window or
- screen, or right-aligned at the right edge of the window or screen,
- respectively. The second argument specifies the Y coordinate of the maximum
- ascent of the text.
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- The foreground and background colours are in alpha/red/green/blue (ARGB)
- format. Channel values are in the range 0 (transparent or off) to 255
- (opaque or full intensity), inclusive. Colour channel values are not
- pre-multiplied by the alpha value. The channel values must be packed into
- the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
- from most-significant to least-significant byte. If the foreground colour
- is not provided, the UI text colour is used; if the background colour is not
- provided, it is fully transparent.
-
-Properties
-^^^^^^^^^^
-
-container.user_settings (read/write)
- The container’s :ref:`user settings <luareference-render-contsettings>`.
- This can be used to control a number of image adjustments.
-container.orientation (read/write)
- The container orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-container.xscale (read/write)
- The container’s X scale factor. This is a floating-point number.
-container.yscale (read/write)
- The container’s Y scale factor. This is a floating-point number.
-container.xoffset (read/write)
- The container’s X offset. This is a floating-point number where one (1)
- corresponds to the X size of the container.
-container.yoffset (read/write)
- The container’s Y offset. This is a floating-point number where one (1)
- corresponds to the Y size of the container.
-container.is_empty (read-only)
- A Boolean indicating whether the container has no items.
-
-.. _luareference-render-contsettings:
-
-Container user settings
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_container::user_settings`` class, representing image
-adjustments applied to a
-:ref:`render container <luareference-render-container>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.screens[tag].container
- Gets the current container user settings for a given screen.
-
-Properties
-^^^^^^^^^^
-
-settings.orientation (read/write)
- The container orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-settings.brightness (read/write)
- The brightness adjustment applied to the container. This is a
- floating-point number.
-settings.contrast (read/write)
- The contrast adjustment applied to the container. This is a floating-point
- number.
-settings.gamma (read/write)
- The gamma adjustment applied to the container. This is a floating-point
- number.
-settings.xscale (read/write)
- The container’s X scale factor. This is a floating-point number.
-settings.yscale (read/write)
- The container’s Y scale factor. This is a floating-point number.
-settings.xoffset (read/write)
- The container’s X offset. This is a floating-point number where one (1)
- represents the X size of the container.
-settings.yoffset (read/write)
- The container’s Y offset. This is a floating-point number where one (1)
- represents the Y size of the container.
-
-.. _luareference-render-layfile:
-
-Layout file
-~~~~~~~~~~~
-
-Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
-file for use by a render target.
-
-Instantiation
-^^^^^^^^^^^^^
-
-A layout file object is supplied to its layout script in the ``file`` variable.
-Layout file objects are not instantiated directly from Lua scripts.
-
-Methods
-^^^^^^^
-
-layout:set_resolve_tags_callback(cb)
- Set a function to perform additional tasks after the emulated machine has
- finished starting, tags in the layout views have been resolved, and the
- default view item handlers have been set up. The function must accept no
- arguments.
-
- Call with ``nil`` to remove the callback.
-
-Properties
-^^^^^^^^^^
-
-layout.device (read-only)
- The device that caused the layout file to be loaded. Usually the root
- machine device for external layouts.
-layout.views[] (read-only)
- The :ref:`views <luareference-render-layview>` created from the layout file.
- Views are indexed by unqualified name (i.e. the value of the ``name``
- attribute). Views are ordered how they appear in the layout file when
- iterating or using the ``at`` method. The index get, ``at`` and
- ``index_of`` methods have O(n) complexity.
-
- Note that not all views in the XML file may be created. For example views
- that reference screens provided by slot card devices will not be created if
- said slot card devices are not present in the system.
-
-.. _luareference-render-layview:
-
-Layout view
-~~~~~~~~~~~
-
-Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
-a render target. Views are created from XML layout files, which may be loaded
-from external artwork, internal to MAME, or automatically generated based on the
-screens in the emulated system.
-
-Instantiation
-^^^^^^^^^^^^^
-
-Layout scripts generally
-
-manager.machine.render.targets[index].current_view
- Gets the currently selected view for a given render target.
-
-Methods
-^^^^^^^
-
-view:has_screen(screen)
- Returns a Boolean indicating whether the screen is present in the view.
- This is true for screens that are present but not visible because the user
- has hidden the item collection they belong to.
-view:set_prepare_items_callback(cb)
- Set a function to perform additional tasks before the view items are added
- to the render target in preparation for drawing a video frame. The function
- must accept no arguments. Call with ``nil`` to remove the callback.
-view:set_preload_callback(cb)
- Set a function to perform additional tasks after preloading visible view
- items. The function must accept no arguments. Call with ``nil`` to remove
- the callback.
-
- This function may be called when the user selects a view or makes an item
- collection visible. It may be called multiple times for a view, so avoid
- repeating expensive tasks.
-view:set_recomputed_callback(cb)
- Set a function to perform additional tasks after the view’s dimensions are
- recomputed. The function must accept no arguments. Call with ``nil`` to
- remove the callback.
-
- View coordinates are recomputed in various events, including the window
- being resized, entering or leaving full-screen mode, and changing the zoom
- to screen area setting.
-
-Properties
-^^^^^^^^^^
-
-view.items[] (read-only)
- The screen and layout element :ref:`items <luareference-render-layitem>` in
- the view. This container does not support iteration by key using ``pairs``;
- only iteration by index using ``ipairs`` is supported. The key is the value
- of the ``id`` attribute if present. Only items with ``id`` attributes can
- be looked up by key. The index get method has O(1) complexity, and the
- ``at`` and ``index_of`` methods have O(n) complexity.
-view.name (read-only)
- The display name for the view. This may be qualified to indicate the device
- that caused the layout file to be loaded when it isn’t the root machine
- device.
-view.unqualified_name (read-only)
- The unqualified name of the view, exactly as it appears in the ``name``
- attribute in the XML layout file.
-view.visible_screen_count (read-only)
- The number of screens items currently enabled in the view.
-view.effective_aspect (read-only)
- The effective width-to-height aspect ratio of the view in its current
- configuration.
-view.bounds (read-only)
- A :ref:`render bounds <luareference-render-bounds>` object representing the
- effective bounds of the view in its current configuration. The coordinates
- are in view units, which are arbitrary but assumed to have square aspect
- ratio.
-view.has_art
- A Boolean indicating whether the view has any non-screen items, including
- items that are not visible because the user has hidden the item collection
- that they belong to.
-
-.. _luareference-render-layitem:
-
-Layout view item
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``layout_view_item`` class, representing an item in a view. An
-item is drawn as a rectangular textured surface. The texture is supplied by an
-emulated screen or a layout element.
-
-Instantiation
-^^^^^^^^^^^^^
-
-layout.views[name].items[id]
- Get a view item by ID. The item must have an ``id`` attribute in the XML
- layout file to be looked up by ID.
-
-Methods
-^^^^^^^
-
-item:set_state(state)
- Set the value used as the element state and animation state in the absence
- of bindings. The argument must be an integer.
-item:set_element_state_callback(cb)
- Set a function to call to obtain the element state for the item. The
- function must accept no arguments and return an integer. Call with ``nil``
- to restore the default element state callback (based on bindings in the XML
- layout file).
-
- Note that the function must not access the item’s ``element_state``
- property, as this will result in infinite recursion.
-
- This callback will not be used to obtain the animation state for the item,
- even if the item lacks explicit animation state bindings in the XML layout
- file.
-item:set_animation_state_callback(cb)
- Set a function to call to obtain the animation state for the item. The
- function must accept no arguments and return an integer. Call with ``nil``
- to restore the default animation state callback (based on bindings in the
- XML layout file).
-
- Note that the function must not access the item’s ``animation_state``
- property, as this will result in infinite recursion.
-item:set_bounds_callback(cb)
- Set a function to call to obtain the bounds for the item. The function must
- accept no arguments and return a
- :ref:`render bounds <luareference-render-bounds>` object in render target
- coordinates. Call with ``nil`` to restore the default bounds callback
- (based on the item’s animation state and ``bounds`` child elements in the
- XML layout file).
-
- Note that the function must not access the item’s ``bounds`` property, as
- this will result in infinite recursion.
-item:set_color_callback(cb)
- Set a function to call to obtain the multiplier colour for the item. The
- function must accept no arguments and return a
- :ref:`render colour <luareference-render-color>` object. Call with ``nil``
- to restore the default colour callback (based on the item’s animation state
- and ``color`` child elements in the XML layout file).
-
- Note that the function must not access the item’s ``color`` property, as
- this will result in infinite recursion.
-item:set_scroll_size_x_callback(cb)
- Set a function to call to obtain the size of the horizontal scroll window as
- a proportion of the associated element’s width. The function must accept no
- arguments and return a floating-point value. Call with ``nil`` to restore
- the default horizontal scroll window size callback (based on the ``xscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_size_x``
- property, as this will result in infinite recursion.
-item:set_scroll_size_y_callback(cb)
- Set a function to call to obtain the size of the vertical scroll window as a
- proportion of the associated element’s height. The function must accept no
- arguments and return a floating-point value. Call with ``nil`` to restore
- the default vertical scroll window size callback (based on the ``yscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_size_y``
- property, as this will result in infinite recursion.
-item:set_scroll_pos_x_callback(cb)
- Set a function to call to obtain the horizontal scroll position. A value of
- zero places the horizontal scroll window at the left edge of the associated
- element. If the item does not wrap horizontally, a value of 1.0 places the
- horizontal scroll window at the right edge of the associated element; if the
- item wraps horizontally, a value of 1.0 corresponds to wrapping back to the
- left edge of the associated element. The function must accept no arguments
- and return a floating-point value. Call with ``nil`` to restore the default
- horizontal scroll position callback (based on bindings in the ``xscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_pos_x`` property,
- as this will result in infinite recursion.
-item:set_scroll_pos_y_callback(cb)
- Set a function to call to obtain the vertical scroll position. A value of
- zero places the vertical scroll window at the top edge of the associated
- element. If the item does not wrap vertically, a value of 1.0 places the
- vertical scroll window at the bottom edge of the associated element; if the
- item wraps vertically, a value of 1.0 corresponds to wrapping back to the
- left edge of the associated element. The function must accept no arguments
- and return a floating-point value. Call with ``nil`` to restore the default
- vertical scroll position callback (based on bindings in the ``yscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_pos_y`` property,
- as this will result in infinite recursion.
-
-Properties
-^^^^^^^^^^
-
-item.id (read-only)
- Get the optional item identifier. This is the value of the ``id`` attribute
- in the XML layout file if present, or ``nil``.
-item.bounds_animated (read-only)
- A Boolean indicating whether the item’s bounds depend on its animation
- state.
-item.color_animated (read-only)
- A Boolean indicating whether the item’s colour depends on its animation
- state.
-item.bounds (read-only)
- The item’s bounds for the current state. This is a
- :ref:`render bounds <luareference-render-bounds>` object in render target
- coordinates.
-item.color (read-only)
- The item’s colour for the current state. The colour of the screen or
- element texture is multiplied by this colour. This is a
- :ref:`render colour <luareference-render-color>` object.
-item.scroll_wrap_x (read-only)
- A Boolean indicating whether the item wraps horizontally.
-item.scroll_wrap_y (read-only)
- A Boolean indicating whether the item wraps vertically.
-item.scroll_size_x (read/write)
- Get the item’s horizontal scroll window size for the current state, or set
- the horizontal scroll window size to use in the absence of bindings. This
- is a floating-point value representing a proportion of the associated
- element’s width.
-item.scroll_size_y (read/write)
- Get the item’s vertical scroll window size for the current state, or set the
- vertical scroll window size to use in the absence of bindings. This is a
- floating-point value representing a proportion of the associated element’s
- height.
-item.scroll_pos_x (read/write)
- Get the item’s horizontal scroll position for the current state, or set the
- horizontal scroll position size to use in the absence of bindings. This is
- a floating-point value.
-item.scroll_pos_y (read/write)
- Get the item’s vertical scroll position for the current state, or set the
- vertical position size to use in the absence of bindings. This is a
- floating-point value.
-item.blend_mode (read-only)
- Get the item’s blend mode. This is an integer value, where 0 means no
- blending, 1 means alpha blending, 2 means RGB multiplication, 3 means
- additive blending, and -1 allows the items within a container to specify
- their own blending modes.
-item.orientation (read-only)
- Get the item orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-item.element_state (read-only)
- Get the current element state. This will call the element state callback
- function to handle bindings.
-item.animation_state (read-only)
- Get the current animation state. This will call the animation state
- callback function to handle bindings.
-
-
-.. _luareference-debug:
-
-Debugger
---------
-
-Some of MAME’s core debugging features can be controlled from Lua script. The
-debugger must be enabled to use the debugging features (usually by passing
-``-debug`` on the command line).
-
-.. _luareference-debug-manager:
-
-Debugger manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``debugger_manager`` class, providing the main interface to control
-the debugger.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.debugger
- Returns the global debugger manager instance, or ``nil`` if the debugger is
- not enabled.
-
-Methods
-^^^^^^^
-
-debugger:command(str)
- Execute a debugger console command. The argument is the command string.
- The output is sent to both the debugger console and the Lua console.
-
-Properties
-^^^^^^^^^^
-
-debugger.consolelog[] (read-only)
- The lines in the console log (output from debugger commands). This
- container only supports index and length operations.
-debugger.errorlog[] (read-only)
- The lines in the error log (``logerror`` output). This container only
- supports index and length operations.
-debugger.visible_cpu (read/write)
- The CPU device with debugger focus. Changes become visible in the debugger
- console after the next step. Setting to a device that is not a CPU has no
- effect.
-debugger.execution_state (read/write)
- Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is
- stopped in the debugger.
-
-.. _luareference-debug-devdebug:
-
-Device debugger interface
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_debug`` class, providing the debugger interface to an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug()
- Returns the debugger interface for an emulated CPU device, or ``nil`` if the
- device is not a CPU.
-
-Methods
-^^^^^^^
-
-debug:step([cnt])
- Step by the specified number of instructions. If the instruction count is
- not provided, it defaults to a single instruction.
-debug:go()
- Run the emulated CPU.
-debug:bpset(addr, [cond], [act])
- Set a breakpoint at the specified address, with an optional condition and
- action. If the action is not specified, it defaults to just breaking into
- the debugger. Returns the breakpoint number for the new breakpoint.
-
- If specified, the condition must be a debugger expression that will be
- evaluated each time the breakpoint is hit. Execution will only be stopped
- if the expression evaluates to a non-zero value. If the condition is not
- specified, it defaults to always active.
-debug:bpenable([bp])
- Enable the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bpdisable([bp])
- Disable the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bpclear([bp])
- Clear the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bplist()
- Returns a table of breakpoints for the device. The keys are the breakpoint
- numbers, and the values are
- :ref:`breakpoint objects <luareference-debug-breakpoint>`.
-debug:wpset(space, type, addr, len, [cond], [act])
- Set a watchpoint over the specified address range, with an optional
- condition and action. The type must be ``"r"``, ``"w"`` or ``"rw"`` for a
- read, write or read/write breakpoint. If the action is not specified, it
- defaults to just breaking into the debugger. Returns the watchpoint number
- for the new watchpoint.
-
- If specified, the condition must be a debugger expression that will be
- evaluated each time the breakpoint is hit. Execution will only be stopped
- if the expression evaluates to a non-zero value. The variable 'wpaddr' is
- set to the address that actually triggered the watchpoint, the variable
- 'wpdata' is set to the data that is being read or written, and the variable
- 'wpsize' is set to the size of the data in bytes. If the condition is not
- specified, it defaults to always active.
-debug:wpenable([wp])
- Enable the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wpdisable([wp])
- Disable the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wpclear([wp])
- Clear the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wplist(space)
- Returns a table of watchpoints for the specified address space of the
- device. The keys are the watchpoint numbers, and the values are
- :ref:`watchpoint objects <luareference-debug-watchpoint>`.
-
-.. _luareference-debug-breakpoint:
-
-Breakpoint
-~~~~~~~~~~
-
-Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug():bplist()[bp]
- Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
- breakpoint corresponds to the specified index.
-
-Properties
-^^^^^^^^^^
-
-breakpoint.index (read-only)
- The breakpoint’s index. The can be used to enable, disable or clear the
- breakpoint via the
- :ref:`CPU debugger interface <luareference-debug-devdebug>`.
-breakpoint.enabled (read-only)
- A Boolean indicating whether the breakpoint is currently enabled.
-breakpoint.address (read-only)
- The breakpoint’s address.
-breakpoint.condition (read-only)
- A debugger expression evaluated each time the breakpoint is hit. The action
- will only be triggered if this expression evaluates to a non-zero value. An
- empty string if no condition was specified.
-breakpoint.action (read-only)
- An action the debugger will run when the breakpoint is hit and the condition
- evaluates to a non-zero value. An empty string if no action was specified.
-
-.. _luareference-debug-watchpoint:
-
-Watchpoint
-~~~~~~~~~~
-
-Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug():wplist(space)[wp]
- Gets the specified watchpoint for an address space of an emulated CPU
- device, or ``nil`` if no watchpoint in the address space corresponds to the
- specified index.
-
-Properties
-^^^^^^^^^^
-
-watchpoint.index (read-only)
- The watchpoint’s index. The can be used to enable, disable or clear the
- watchpoint via the
- :ref:`CPU debugger interface <luareference-debug-devdebug>`.
-watchpoint.enabled (read-only)
- A Boolean indicating whether the watchpoint is currently enabled.
-watchpoint.type (read-only)
- Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
- watchpoint.
-watchpoint.address (read-only)
- The starting address of the watchpoint’s address range.
-watchpoint.length (read-only)
- The length of the watchpoint’s address range.
-watchpoint.condition (read-only)
- A debugger expression evaluated each time the watchpoint is hit. The action
- will only be triggered if this expression evaluates to a non-zero value. An
- empty string if no condition was specified.
-watchpoint.action (read-only)
- An action the debugger will run when the watchpoint is hit and the condition
- evaluates to a non-zero value. An empty string if no action was specified.
diff --git a/docs/source/techspecs/m6502.rst b/docs/source/techspecs/m6502.rst
index c4cb45f5cea..7d67423abb8 100644
--- a/docs/source/techspecs/m6502.rst
+++ b/docs/source/techspecs/m6502.rst
@@ -18,7 +18,7 @@ Point 1 has been ensured through bisimulation with the gate-level simulation per
The 6502 family
---------------
-The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this:
+The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshoots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this:
::
@@ -26,7 +26,7 @@ The MOS 6502 family has been large and productive. A large number of variants ex
|
+------+--------+--+--+-------+-------+
| | | | | |
- 6510 deco16 6504 6509 n2a03 65c02
+ 6510 deco16 6504 6509 rp2a03 65c02
| |
+-----+-----+ r65c02
| | | |
@@ -38,7 +38,7 @@ The MOS 6502 family has been large and productive. A large number of variants ex
-The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc) and clock support.
+The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc.) and clock support.
The deco16 is a Deco variant with a small number of not really understood additional instructions and some I/O.
@@ -46,7 +46,7 @@ The 6504 is a pin and address-bus reduced version.
The 6509 adds internal support for paging.
-The n2a03 is the NES variant with the D flag disabled and sound functionality integrated.
+The rp2a03 is the NES variant with the D flag disabled and sound functionality integrated.
The 65c02 is the very first cmos variant with some additional instructions, some fixes, and most of the undocumented instructions turned into nops. The R (Rockwell, but eventually produced by WDC too among others) variant adds a number of bitwise instructions and also stp and wai. The SC variant, used by the Lynx portable console, looks identical to the R variant. The 'S' probably indicates a static-ram-cell process allowing full DC-to-max clock control.
@@ -374,6 +374,6 @@ Current TO-DO:
- Integrate the I/O subsystems in the 4510
-- Possibly integrate the sound subsytem in the n2a03
+- Possibly integrate the sound subsytem in the rp2a03
- Add decent hookups for the Apple 3 madness
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 5d18c4e1202..ebdca9646d1 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -126,7 +126,8 @@ A memory share can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved. That class behaves like a pointer but also has the
``target()``, ``length()``, ``bytes()``, ``endianness()``,
-``bitwidth()`` and ``bytewidth()`` methods for share information.
+``bitwidth()`` and ``bytewidth()`` methods for share information. The
+desired size is specified in bytes.
.. code-block:: C++
@@ -154,12 +155,17 @@ A memory bank is a named memory zone indirection that can be mapped in
address spaces. It points to ``nullptr`` when created.
``configure_entry`` associates an entry number and a base pointer.
``configure_entries`` does the same for multiple consecutive entries
-spanning a memory zone. Alternatively ``set_base`` sets the base for
-entry 0 and selects it.
+spanning a memory zone.
-``set_entry`` allows to dynamically and efficiently select the current
-active entry, ``entry()`` gets that selection back, and ``base()`` gets
-the associated base pointer.
+``set_base`` sets the base address for the active entry. If there are
+no entries, entry 0 (zero) is automatically created and selected. Use
+of ``set_base`` should be avoided in favour of pre-configured entries
+unless there are an impractically large number of possible base
+addresses.
+
+``set_entry`` dynamically and efficiently selects the active entry,
+``entry()`` returns the active entry number, and ``base()`` gets the
+associated base pointer.
.. code-block:: C++
@@ -180,7 +186,7 @@ retrieved by building one of these four finders.
[device constructor] m_bank(*this, "name"),
-A memory share can be created if it doesn’t exist in a memory map
+A memory bank can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved.
@@ -197,7 +203,7 @@ that the lookup can be expensive, prefer finders instead.
.. code-block:: C++
- class memory_bank {
+ class memory_region {
u8 *base();
u8 *end();
u32 bytes() const;
@@ -355,7 +361,7 @@ Sets a method of the current device or driver to read, write or both
for the current entry. The prototype of the method can take multiple
forms making some elements optional. ``uNN`` represents ``u8``,
``u16``, ``u32`` or ``u64`` depending on the data width of the handler.
-The handler can be narrower than the bus itself (for instance a 8-bit
+The handler can be narrower than the bus itself (for instance an 8-bit
device on a 32-bit bus).
The offset passed in is built from the access address. It starts at
@@ -597,7 +603,7 @@ parameter is that trigger width (would be 16 in the 68000 case).
This parameter allows to set user-defined flags on the handler which
can then be retrieved by an accessing device to change their
-behaviour. An example of use the the i960 which marks burstable zones
+behaviour. An example of use the i960 which marks burstable zones
that way (they have a specific hardware-level support).
@@ -647,7 +653,7 @@ changed on-the-fly. They’re powerful but have some issues:
* changing the mappings repeatedly can be slow
* the address space state is not saved in the saved states, so it has to
be rebuilt after state load
-* they can be hidden anywhere rather that be grouped in an address map,
+* they can be hidden anywhere rather than be grouped in an address map,
which can be less readable
The methods, rather than decomposing the information in handler, handler
diff --git a/docs/source/techspecs/naming.rst b/docs/source/techspecs/naming.rst
index 94d3a889649..4846876c0cd 100644
--- a/docs/source/techspecs/naming.rst
+++ b/docs/source/techspecs/naming.rst
@@ -1,3 +1,5 @@
+.. _naming:
+
MAME Naming Conventions
=======================
@@ -13,25 +15,6 @@ To promote consistency and readability in MAME source code, we have some
naming conventions for various elements.
-.. _naming-definitions:
-
-Definitions
------------
-
-Snake case
- All lowercase letters with words separated by underscores:
- ``this_is_snake_case``
-Screaming snake case
- All uppercase letters with words separated by underscores:
- ``SCREAMING_SNAKE_CASE``
-Camel case:
- Lowercase initial letter, first letter of each subsequent word
- capitalised, with no separators between words: ``exampleCamelCase``
-Llama case:
- Uppercase initial letter, first letter of each subsequent word
- capitalised, with no separators between words: ``LlamaCaseSample``
-
-
.. _naming-transliteration:
Transliteration
@@ -90,7 +73,7 @@ For software list entries where a transliteration is used for the
``name="alt_title"`` attribute.
For software items that have multiple titles (for example different
-regional titles with the same installation media), use the most most
+regional titles with the same installation media), use the most
widespread English Latin title for the ``description`` element, and put
the other titles in ``info`` elements with ``name="alt_title"``
attributes.
@@ -108,39 +91,5 @@ use lowercase for anything else besides proper nouns and initialisms.
C++ naming conventions
----------------------
-Preprocessor macros
- Macro names should use screaming snake case. Macros are always
- global and name conflicts can cause confusing errors – think
- carefully about what macros really need to be in headers and name
- them carefully.
-Include guards
- Include guard macros should begin with ``MAME_``, and end with a
- capitalised version of the file name, withe separators replaced by
- underscores.
-Constants
- Constants should use screaming snake case, whether they are constant
- globals, constant data members, enumerators or preprocessor
- constants.
-Functions
- Free functions names should use snake case. (There are some utility
- function that were previously implemented as preprocessor macros
- that still use screaming snake case.)
-Classes
- Class names should use snake case. Abstract class names should end
- in ``_base``. Public member functions (including static member
- functions) should use snake case.
-Device classes
- Concrete driver ``driver_device`` implementation names
- conventionally end in ``_state``, while other concrete device class
- names end in ``_device``. Concrete ``device_interface`` names
- conventionally begin with ``device_`` and end with ``_interface``.
-Device types
- Device types should use screaming snake case. Remember that device
- types are names in the global namespace, so choose explicit,
- unambiguous names.
-Enumerations
- The enumeration name should use snake case. The enumerators should
- use screaming snake case.
-Template parameters
- Template parameters should use llama case (both type and value
- parameters).
+For C++ naming conventions, see the relevant section in the C++
+Coding Guidelines: :ref:`contributing-cxx-naming`
diff --git a/docs/source/techspecs/object_finders.rst b/docs/source/techspecs/object_finders.rst
index 2256d74b677..27fe42fdd50 100644
--- a/docs/source/techspecs/object_finders.rst
+++ b/docs/source/techspecs/object_finders.rst
@@ -239,7 +239,7 @@ the object finders in the device class (with all distractions removed):
}
sbus_device(machine_config const &mconfig, char const *tag, device_t *owner, u32 clock) :
- device_t(mconfig, type, tag, owner, clock),
+ device_t(mconfig, SBUS, tag, owner, clock),
device_memory_interface(mconfig, *this),
m_maincpu(*this, finder_base::DUMMY_TAG),
m_type1space(*this, finder_base::DUMMY_TAG, -1)
@@ -478,7 +478,7 @@ for all elements of the array):
};
This finds or creates memory shares with tags ``vram_0`` and ``vram_1``, each of
-of which is 8 KiB organised as 4,096 big-Endian 16-bit words.
+which is 8 KiB organised as 4,096 big-Endian 16-bit words.
Optional object finders
diff --git a/docs/source/techspecs/poly_manager.rst b/docs/source/techspecs/poly_manager.rst
index e86cf481428..d30a57c39c3 100644
--- a/docs/source/techspecs/poly_manager.rst
+++ b/docs/source/techspecs/poly_manager.rst
@@ -951,7 +951,7 @@ poly_array
poly_array();
-The **poly_array** contructor requires no parameters and simply pre-allocates one
+The **poly_array** constructor requires no parameters and simply pre-allocates one
chunk of objects in preparation for future allocations.
count