summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
committer Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
commit12623c3fd35984f75e31144126689986af657a30 (patch)
tree8b8b01669ab168705148152e3f4a3622945dd04c /docs/source/luascript
parent737af4b6655d1de338895272bfeeec8bb7b7b17f (diff)
docs: Moved Lua API reference to its own section - the page was far too long.
Diffstat (limited to 'docs/source/luascript')
-rw-r--r--docs/source/luascript/index.rst235
-rw-r--r--docs/source/luascript/ref-common.rst118
-rw-r--r--docs/source/luascript/ref-core.rst635
-rw-r--r--docs/source/luascript/ref-debugger.rst451
-rw-r--r--docs/source/luascript/ref-devices.rst764
-rw-r--r--docs/source/luascript/ref-input.rst776
-rw-r--r--docs/source/luascript/ref-mem.rst449
-rw-r--r--docs/source/luascript/ref-render.rst1248
8 files changed, 4676 insertions, 0 deletions
diff --git a/docs/source/luascript/index.rst b/docs/source/luascript/index.rst
new file mode 100644
index 00000000000..7ba5a0a8caf
--- /dev/null
+++ b/docs/source/luascript/index.rst
@@ -0,0 +1,235 @@
+.. _luascript:
+
+Lua Scripting Interface
+=======================
+
+.. contents:: :local:
+
+
+.. _luascript-intro:
+
+Introduction
+------------
+
+MAME provides Lua script bindings for a useful set of core functionality. This
+feature first appeared in version 0.148, when a minimal Lua interface was
+implemented. Today, the Lua interface is rich enough to let you inspect and
+manipulate device state, access CPU registers, read and write memory, and draw
+custom graphical overlays.
+
+There are three ways to use MAME’s Lua scripting capabilities:
+
+* Using the :ref:`interactive Lua console <luascript-console>`, enabled by the
+ :ref:`console option <mame-commandline-console>`.
+* By providing a script file to run using the :ref:`-autoboot_script option
+ <mame-commandline-autobootscript>`. The :ref:`-autoboot_delay option
+ <mame-commandline-autobootdelay>` controls how long MAME waits after starting
+ the emulated system before running the script.
+* By writing :ref:`Lua plugins <plugins>`. Several plugins are included with
+ MAME.
+
+Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
+to implement Lua bindings.
+
+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 objects support some level of runtime
+introspection.
+
+
+.. _luascript-features:
+
+Features
+--------
+
+The API is not yet complete, but this is a partial list of capabilities exposed
+to Lua scripts:
+
+* Session information (application version, current emulated system)
+* 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)
+
+
+.. _luascript-api:
+
+API reference
+-------------
+
+.. toctree::
+ :maxdepth: 2
+
+ ref-common
+ ref-core
+ ref-devices
+ ref-mem
+ ref-input
+ ref-render
+ ref-debugger
+
+
+.. _luascript-console:
+
+Interactive Lua console tutorial
+--------------------------------
+
+First run an arcade game in MAME at the command prompt with the ``-console``
+and ``-window`` options to enable the Lua console:
+
+::
+
+ $ mame -console -window YOUR_SYSTEM
+ /| /| /| /| /| _______
+ / | / | / | / | / | / /
+ / |/ | / | / |/ | / ____/
+ / | / | / | / /_
+ / |/ | / |/ __/
+ / /| /| /| |/ /| /| /____
+ / / | / | / | / | / | /
+ / _/ |/ / / |___/ |/ /_______/
+ / /
+ / _/
+
+ mame 0.255
+ Copyright (C) Nicola Salmoria and the MAME team
+
+ Lua 5.4
+ Copyright (C) Lua.org, PUC-Rio
+
+ [MAME]>
+
+At this point, your game is probably running in attract 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 error messages.
+
+You can check the version of MAME you are running with:
+
+::
+
+ [MAME]> print(emu.app_name() .. " " .. emu.app_version())
+ mame 0.255
+
+Let’s examine the emulated screens. First, enumerate the :ref:`screen devices
+<luascript-ref-screendev>` in the system:
+
+::
+
+ [MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
+ :screen
+
+``manager.machine`` is the :ref:`running machine <luascript-ref-machine>` object
+for the current emulation session. We will be using this frequently.
+``screens`` is a :ref:`device enumerator <luascript-ref-devenum>` that yields
+all emulated screens in the system. Most arcade games only have one main
+screen. In our case, the main and only screen has the absolute tag ``:screen``.
+We can examine it further:
+
+::
+
+ [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
+
+Several methods are available for drawing an overlay on the screen using lines,
+rectangles and text:
+
+::
+
+ [MAME]> -- define a function for drawing an overlay and call it
+ [MAME]> function draw_overlay()
+ [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_overlay()
+
+This will draw some useless lines and text over the screen. However, when the
+emulated system is resumed, your overlay needs to be refreshed or it will just
+disappear. In order to do this, you have to register your function to be called
+on every video update:
+
+::
+
+ [MAME]> emu.register_frame_done(draw_overlay, 'frame')
+
+All colors are specified in ARGB format (eight bits per channel). The
+coordinate origin (0,0) normally corresponds to the top-left corner of the
+screen.
+
+As with screens, you can examine all the emulated devices in the running system:
+
+::
+
+ [MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
+ :audiocpu
+ :maincpu
+ :saveram
+ :screen
+ :palette
+ [...]
+
+For some of them, you can also inspect and manipulate memory and state:
+
+::
+
+ [MAME]> cpu = manager.machine.devices[':maincpu']
+ [MAME]> -- enumerate, read and write register state
+ [MAME]> for k, v in pairs(cpu.state) do print(k) end
+ CURPC
+ rPC
+ IR
+ CURFLAGS
+ SSR
+ D0
+ [...]
+ [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
+ cpu_space
+ [MAME]> mem = cpu.spaces['program']
+ [MAME]> print(mem:read_i8(0xc000))
+ 41
+
+Note that many objects support symbol completion if you type part of a method or
+property name and press the Tab key:
+
+::
+
+ [MAME]>print(mem:read_<TAB>
+ read_direct_i8
+ read_u16
+ read_range
+ read_direct_u16
+ read_direct_i64
+ read_i64
+ read_i32
+ read_direct_u64
+ read_i8
+ read_u32
+ read_u8
+ read_u64
+ read_direct_u32
+ read_direct_i16
+ read_direct_i32
+ read_direct_u8
+ read_i16
+ [MAME]>print(mem:read_direct_i8
diff --git a/docs/source/luascript/ref-common.rst b/docs/source/luascript/ref-common.rst
new file mode 100644
index 00000000000..a68a832b88f
--- /dev/null
+++ b/docs/source/luascript/ref-common.rst
@@ -0,0 +1,118 @@
+.. _luascript-ref-common:
+
+Lua Common Types and Globals
+============================
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-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 over 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 over 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.
+
+
+.. _luascript-ref-emu:
+
+Emulator interface
+------------------
+
+The emulator interface ``emu`` provides access to core functionality. Many
+classes are also available as properties of the emulator interface.
+
+Methods
+~~~~~~~
+
+emu.wait(duration, …)
+ Yields for the specified duration in terms of emulated time. The duration
+ may be specified as an :ref:`attotime <luascript-ref-attotime>` or a number
+ in seconds. Any additional arguments are returned to the caller. Returns a
+ Boolean indicating whether the duration expired normally.
+
+ All outstanding calls to ``emu.wait`` will return ``false`` immediately if a
+ saved state is loaded or the emulation session ends. Calling this function
+ from callbacks that are not run as coroutines will raise an error.
+emu.wait_next_update(…)
+ Yields until the next video/UI update. Any arguments are returned to the
+ caller. Calling this function from callbacks that are not run as coroutines
+ will raise an error.
+emu.wait_next_frame(…)
+ Yields until the next emulated frame completes. Any arguments are returned
+ to the caller. Calling this function from callbacks that are not run as
+ coroutines will raise an error.
+emu.add_machine_reset_notifier(callback)
+ Add a callback to receive notifications when the emulated system is reset.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_stop_notifier(callback)
+ Add a callback to receive notifications when the emulated system is stopped.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_pause_notifier(callback)
+ Add a callback to receive notifications when the emulated system is paused.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_resume_notifier(callback)
+ Add a callback to receive notifications when the emulated system is resumed
+ after being paused. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_frame_notifier(callback)
+ Add a callback to receive notifications when an emulated frame completes.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_pre_save_notifier(callback)
+ Add a callback to receive notification before the emulated system state is
+ saved. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_post_load_notifier(callback)
+ Add a callback to receive notification after the emulated system is restored
+ to a previously saved state. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.print_error(message)
+ Print an error message.
+emu.print_warning(message)
+ Print a warning message.
+emu.print_info(message)
+ Print an informational message.
+emu.print_verbose(message)
+ Print a verbose diagnostic message (disabled by default).
+emu.print_debug(message)
+ Print a debug message (only enabled for debug builds by default).
+emu.lang_translate([context], message)
+ Look up a message with optional context in the current localised message
+ catalog. Returns the message unchanged if no corresponding localised
+ message is found.
+emu.subst_env(string)
+ Substitute environment variables in a string. The syntax is dependent on
+ the host operating system.
diff --git a/docs/source/luascript/ref-core.rst b/docs/source/luascript/ref-core.rst
new file mode 100644
index 00000000000..f761b20f5de
--- /dev/null
+++ b/docs/source/luascript/ref-core.rst
@@ -0,0 +1,635 @@
+.. _luascript-ref-core:
+
+Lua Core Classes
+================
+
+Many of MAME’s core classes used to implement an emulation session are available
+to Lua scripts.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-notifiersub:
+
+Notifier subscription
+---------------------
+
+Wraps MAME’s ``util::notifier_subscription`` class, which manages a subscription
+to a broadcast notification.
+
+Methods
+~~~~~~~
+
+subscription:unsubscribe()
+ Unsubscribes from notifications. The subscription will become inactive and
+ no future notifications will be received.
+
+Properties
+~~~~~~~~~~
+
+subscription.is_active (read-only)
+ A Boolean indicating whether the subscription is active. A subscription
+ becomes inactive after explicitly unsubscribing or if the underlying
+ notifier is destroyed.
+
+
+.. _luascript-ref-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.
+
+
+.. _luascript-ref-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 <luascript-ref-machine>` for the current emulation
+ session.
+manager.ui (read-only)
+ The :ref:`UI manager <luascript-ref-uiman>` for the current session.
+manager.options (read-only)
+ The :ref:`emulation options <luascript-ref-emuopts>` for the current
+ session.
+manager.plugins[] (read-only)
+ Gets information about the :ref:`Lua plugins <luascript-ref-plugin>` that
+ are present, indexed by name. The index get, ``at`` and ``index_of``
+ methods have O(n) complexity.
+
+
+.. _luascript-ref-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 <luascript-ref-attotime>`.
+machine.system (read-only)
+ The :ref:`driver metadata <luascript-ref-driver>` for the current
+ system.
+machine.parameters (read-only)
+ The :ref:`parameters manager <luascript-ref-paramman>` for the current
+ emulation session.
+machine.video (read-only)
+ The :ref:`video manager <luascript-ref-videoman>` for the current emulation
+ session.
+machine.sound (read-only)
+ The :ref:`sound manager <luascript-ref-soundman>` for the current emulation
+ session.
+machine.output (read-only)
+ The :ref:`output manager <luascript-ref-outputman>` for the current
+ emulation session.
+machine.memory (read-only)
+ The :ref:`emulated memory manager <luascript-ref-memman>` for the current
+ session.
+machine.ioport (read-only)
+ The :ref:`I/O port manager <luascript-ref-ioportman>` for the current
+ emulation session.
+machine.input (read-only)
+ The :ref:`input manager <luascript-ref-inputman>` for the current emulation
+ session.
+machine.natkeyboard (read-only)
+ Gets the :ref:`natural keyboard manager <luascript-ref-natkbdman>`, used for
+ controlling keyboard and keypad input to the emulated system.
+machine.uiinput (read-only)
+ The :ref:`UI input manager <luascript-ref-uiinputman>` for the current
+ emulation session.
+machine.render (read-only)
+ The :ref:`render manager <luascript-ref-renderman>` for the current
+ emulation session.
+machine.debugger (read-only)
+ The :ref:`debugger manager <luascript-ref-debugman>` for the current
+ emulation session, or ``nil`` if the debugger is not enabled.
+machine.options (read-only)
+ The user-specified :ref:`options <luascript-ref-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 <luascript-ref-devenum>` that yields all
+ :ref:`devices <luascript-ref-device>` in the emulated system.
+machine.palettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`palette devices <luascript-ref-dipalette>` in the emulated system.
+machine.screens (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`screen devices <luascript-ref-screendev>` in the emulated system.
+machine.cassettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the emulated
+ system.
+machine.images (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`media image devices <luascript-ref-diimage>` in the emulated system.
+machine.slots (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`slot devices <luascript-ref-dislot>` in the emulated system.
+
+
+.. _luascript-ref-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 <luascript-ref-rendertarget>` used to produce
+ snapshots and video recordings.
+
+
+.. _luascript-ref-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.
+
+
+.. _luascript-ref-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.
+
+
+.. _luascript-ref-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.
+
+
+.. _luascript-ref-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 <luascript-ref-inputseq>` 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 <luascript-ref-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.ui_active (read/write)
+ A Boolean indicating whether UI control inputs are currently enabled.
+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.
+
+
+.. _luascript-ref-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.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.
+
+
+.. _luascript-ref-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.
diff --git a/docs/source/luascript/ref-debugger.rst b/docs/source/luascript/ref-debugger.rst
new file mode 100644
index 00000000000..e347b7303ff
--- /dev/null
+++ b/docs/source/luascript/ref-debugger.rst
@@ -0,0 +1,451 @@
+.. _luascript-ref-debugger:
+
+Lua Debugger Classes
+====================
+
+Some of MAME’s core debugging features can be controlled from Lua script. The
+debugger must be enabled to use the debugger features (usually by passing
+``-debug`` on the command line).
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-debugsymtable:
+
+Symbol table
+------------
+
+Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
+in expressions. Note that symbol tables can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.symbol_table(machine)
+ Creates a new symbol table in the context of the specified machine,
+emu.symbol_table(parent, [device])
+ Creates a new symbol table with the specified parent symbol table. If a
+ device is specified and it implements ``device_memory_interface``, it will
+ be used as the base for looking up address spaces and memory regions. Note
+ that if a device that does not implement ``device_memory_interface`` is
+ supplied, it will not be used (address spaces and memory regions will be
+ looked up relative to the root device).
+emu.symbol_table(device)
+ Creates a new symbol table in the context of the specified device. If the
+ device implements ``device_memory_interface``, it will be used as the base
+ for looking up address spaces and memory regions. Note that if a device
+ that does not implement ``device_memory_interface`` is supplied, it will
+ only be used to determine the machine context (address spaces and memory
+ regions will be looked up relative to the root device).
+
+Methods
+~~~~~~~
+
+symbols:set_memory_modified_func(cb)
+ Set a function to call when memory is modified via the symbol table. No
+ arguments are passed to the function and any return values are ignored.
+ Call with ``nil`` to remove the callback.
+symbols:add(name, [value])
+ Adds a named integer symbol. The name must be a string. If a value is
+ supplied, it must be an integer. If a value is supplied, a read-only symbol
+ is added with the supplied value. If no value is supplied, a read/write
+ symbol is created with and initial value of zero. If a symbol entry with
+ the specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, getter, [setter], [format])
+ Adds a named integer symbol using getter and optional setter callbacks. The
+ name must be a string. The getter must be a function returning an integer
+ for the symbol value. If supplied, the setter must be a function that
+ accepts a single integer argument for the new value of the symbol. A format
+ string for displaying the symbol value may optionally be supplied. If a
+ symbol entry with the specified name already exists in the symbol table, it
+ will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, minparams, maxparams, execute)
+ Adds a named function symbol. The name must be a string. The minimum and
+ maximum numbers of parameters must be integers. If a symbol entry with the
+ specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:find(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table.
+symbols:find_deep(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table or any of its parent symbol tables.
+symbols:value(name)
+ Returns the integer value of the symbol with the specified name, or zero if
+ there is no symbol with the specified name in the symbol table or any of its
+ parent symbol tables. Raises an error if the symbol with specified name is
+ a function symbol.
+symbols:set_value(name, value)
+ Sets the value of the symbol with the specified name. Raises an error if
+ the symbol with the specified name is a read-only integer symbol or if it is
+ a function symbol. Has no effect if there is no symbol with the specified
+ name in the symbol table or any of its parent symbol tables.
+symbols:memory_value(name, space, offset, size, disable_se)
+ Read a value from memory. Supply the name or tag of the address space or
+ memory region to read from, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:set_memory_value(name, space, offset, value, size, disable_se)
+ Write a value to memory. Supply the name or tag of the address space or
+ memory region to write to, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:read_memory(space, address, size, apply_translation)
+ Read a value from an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug read intention. Returns a value
+ of the requested size with all bits set if address translation fails.
+symbols:write_memory(space, address, data, size, apply_translation)
+ Write a value to an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug write intention. The symbol
+ table’s memory modified function will be called after the value is written.
+ The value will not be written and the symbol table’s memory modified
+ function will not be called if address translation fails.
+
+Properties
+~~~~~~~~~~
+
+symbols.entries[]
+ The :ref:`symbol entries <luascript-ref-debugsymentry>` in the symbol table,
+ indexed by name. The ``at`` and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+symbols.parent (read-only)
+ The parent symbol table, or ``nil`` if the symbol table has no parent.
+
+
+.. _luascript-ref-debugexpression:
+
+Parsed expression
+-----------------
+
+Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
+expression. Note that parsed expressions can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.parsed_expression(symbols)
+ Creates an empty expression that will use the supplied
+ :ref:`symbol table <luascript-ref-debugsymtable>` to look up symbols.
+emu.parsed_expression(symbols, string, [default_base])
+ Creates an expression by parsing the supplied string, looking up symbols in
+ the supplied :ref:`symbol table <luascript-ref-debugsymtable>`. If the
+ default base for interpreting integer literals is not supplied, 16 is used
+ (hexadecimal). Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols.
+
+Methods
+~~~~~~~
+
+expression:set_default_base(base)
+ Set the default base for interpreting numeric literals. The base must be a
+ positive integer.
+expression:parse(string)
+ Parse a debugger expression string. Replaces the current contents of the
+ expression if it is not empty. Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols. The previous content of the expression is not
+ preserved when attempting to parse an invalid expression string.
+expression:execute()
+ Evaluates the expression, returning an unsigned integer result. Raises an
+ :ref:`expression error <luascript-ref-debugexpressionerror>` if the
+ expression cannot be evaluated (e.g. attempting to call a function with an
+ invalid number of arguments).
+
+Properties
+~~~~~~~~~~
+
+expression.is_empty (read-only)
+ A Boolean indicating whether the expression contains no tokens.
+expression.original_string (read-only)
+ The original string that was parsed to create the expression.
+expression.symbols (read/write)
+ The :ref:`symbol table <luascript-ref-debugsymtable>` used for to look up
+ symbols in the expression.
+
+
+.. _luascript-ref-debugsymentry:
+
+Symbol entry
+------------
+
+Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
+:ref:`symbol table <luascript-ref-debugsymtable>`. Note that symbol entries
+must not be used after the symbol table they belong to is destroyed.
+
+Instantiation
+~~~~~~~~~~~~~
+
+symbols:add(name, [value])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, getter, [setter], [format])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, minparams, maxparams, execute)
+ Adds function symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+
+Properties
+~~~~~~~~~~
+
+entry.name (read-only)
+ The name of the symbol entry.
+entry.format (read-only)
+ The format string used to convert the symbol entry to text for display.
+entry.is_function (read-only)
+ A Boolean indicating whether the symbol entry is a callable function.
+entry.is_lval (read-only)
+ A Boolean indicating whether the symbol entry is an integer symbol that can
+ be set (i.e. whether it can be used on the left-hand side of assignment
+ expressions).
+entry.value (read/write)
+ The integer value of the symbol entry. Attempting to set the value raises
+ an error if the symbol entry is read-only. Attempting to get or set the
+ value of a function symbol raises an error.
+
+
+.. _luascript-ref-debugman:
+
+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.
+
+
+.. _luascript-ref-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 <luascript-ref-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 <luascript-ref-watchpoint>`.
+
+
+.. _luascript-ref-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 <luascript-ref-devdebug>`.
+breakpoint.enabled (read/write)
+ 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.
+
+
+.. _luascript-ref-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 <luascript-ref-devdebug>`.
+watchpoint.enabled (read/write)
+ 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.
+
+
+.. _luascript-ref-debugexpressionerror:
+
+Expression error
+----------------
+
+Wraps MAME’s ``expression_error`` class, describing an error occurring while
+parsing or executing a debugger expression. Raised on errors when using
+:ref:`parsed expressions <luascript-ref-debugexpression>`. Can be converted to
+a string to provide a description of the error.
+
+Properties
+~~~~~~~~~~
+
+err.code (read-only)
+ An implementation-dependent number representing the category of error.
+ Should not be displayed to the user.
+err.offset (read-only)
+ The offset within the expression string where the error was encountered.
diff --git a/docs/source/luascript/ref-devices.rst b/docs/source/luascript/ref-devices.rst
new file mode 100644
index 00000000000..17b34ef1914
--- /dev/null
+++ b/docs/source/luascript/ref-devices.rst
@@ -0,0 +1,764 @@
+.. _luascript-ref-dev:
+
+Lua Device Classes
+==================
+
+Several device classes and device mix-ins classes are exposed to Lua. Devices
+can be looked up by tag or enumerated.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-devenum:
+
+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 <luascript-ref-device>` in the system.
+manager.machine.palettes
+ Returns a device enumerator that will iterate over
+ :ref:`palette devices <luascript-ref-dipalette>` in the system.
+manager.machine.screens
+ Returns a device enumerator that will iterate over
+ :ref:`screen devices <luascript-ref-screendev>` in the system.
+manager.machine.cassettes
+ Returns a device enumerator that will iterate over
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the system.
+manager.machine.images
+ Returns a device enumerator that will iterate over
+ :ref:`media image devices <luascript-ref-diimage>` in the system.
+manager.machine.slots
+ Returns a device enumerator that will iterate over
+ :ref:`slot devices <luascript-ref-dislot>` in the system.
+emu.device_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`devices <luascript-ref-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.palette_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`palette devices <luascript-ref-dipalette>` in the sub-tree starting at
+ the specified device. The specified device will be included if it is a
+ palette 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.screen_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`screen devices <luascript-ref-screendev>` 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 <luascript-ref-cassdev>` 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 <luascript-ref-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 <luascript-ref-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).
+
+
+.. _luascript-ref-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 <luascript-ref-memshare>` by tag relative to the
+ device, or ``nil`` if no such memory share exists.
+device:membank(tag)
+ Gets a :ref:`memory bank <luascript-ref-membank>` by tag relative to the
+ device, or ``nil`` if no such memory bank exists.
+device:memregion(tag)
+ Gets a :ref:`memory region <luascript-ref-memregion>` by tag relative to the
+ device, or ``nil`` if no such memory region exists.
+device:ioport(tag)
+ Gets an :ref:`I/O port <luascript-ref-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 <luascript-ref-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.state[] (read-only)
+ The :ref:`state entries <luascript-ref-distateentry>` for devices that
+ expose the register state interface, indexed by symbol, or ``nil`` for other
+ devices. The index operator and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+device.spaces[] (read-only)
+ A table of the device’s :ref:`address spaces <luascript-ref-addrspace>`,
+ 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.
+
+
+.. _luascript-ref-dipalette:
+
+Palette device
+--------------
+
+Wraps MAME’s ``device_palette_interface`` class, which represents a device that
+translates pen values to colours.
+
+Colours are represented in alpha/red/green/blue (ARGB) format. Channel values
+range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
+Colour channel values are not pre-multiplied by the alpha value. Channel values
+are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
+green, blue from most-significant to least-significant byte.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.palettes[tag]
+ Gets a palette device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a palette device.
+
+Methods
+~~~~~~~
+
+palette:pen(index)
+ Gets the remapped pen number for the specified palette index.
+palette:pen_color(pen)
+ Gets the colour for the specified pen number.
+palette:pen_contrast(pen)
+ Gets the contrast value for the specified pen number. The contrast is a
+ floating-point number.
+palette:pen_indirect(index)
+ Gets the indirect pen index for the specified palette index.
+palette:indirect_color(index)
+ Gets the indirect pen colour for the specified palette index.
+palette:set_pen_color(pen, color)
+ Sets the colour for the specified pen number. The colour may be specified
+ as a single packed 32-bit value; or as individual red, green and blue
+ channel values, in that order.
+palette:set_pen_red_level(pen, level)
+ Sets the red channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_green_level(pen, level)
+ Sets the green channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_blue_level(pen, level)
+ Sets the blue channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_contrast(pen, factor)
+ Sets the contrast value for the specified pen number. The value must be a
+ floating-point number.
+palette:set_pen_indirect(pen, index)
+ Sets the indirect pen index for the specified pen number.
+palette:set_indirect_color(index, color)
+ Sets the indirect pen colour for the specified palette index. The colour
+ may be specified as a single packed 32-bit value; or as individual red,
+ green and blue channel values, in that order.
+palette:set_shadow_factor(factor)
+ Sets the contrast value for the current shadow group. The value must be a
+ floating-point number.
+palette:set_highlight_factor(factor)
+ Sets the contrast value for the current highlight group. The value must be
+ a floating-point number.
+palette:set_shadow_mode(mode)
+ Sets the shadow mode. The value is the index of the desired shadow table.
+
+Properties
+~~~~~~~~~~
+
+palette.palette (read-only)
+ The underlying :ref:`palette <luascript-ref-palette>` managed by the
+ device.
+palette.entries (read-only)
+ The number of colour entries in the palette.
+palette.indirect_entries (read-only)
+ The number of indirect pen entries in the palette.
+palette.black_pen (read-only)
+ The index of the fixed black pen entry.
+palette.white_pen (read-only)
+ The index of the fixed white pen.
+palette.shadows_enabled (read-only)
+ A Boolean indicating whether shadow colours are enabled.
+palette.highlights_enabled (read-only)
+ A Boolean indicating whether highlight colours are enabled.
+palette.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+
+
+.. _luascript-ref-screendev:
+
+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:`luascript-ref-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, the visible area width and visible area height.
+
+ Pixels are returned 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(x0, y0, x1, y1, [color])
+ Draws a line from (x0, y0) to (x1, y1).
+
+ 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 <luascript-ref-rendercontainer>` used to draw the
+ screen.
+screen.palette (read-only)
+ The :ref:`palette device <luascript-ref-dipalette>` used to translate pixel
+ values to colours, or ``nil`` if the screen uses a direct colour pixel
+ format.
+
+
+.. _luascript-ref-cassdev:
+
+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:`luascript-ref-device`
+* :ref:`luascript-ref-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.
+
+
+.. _luascript-ref-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 ``nil`` if no error
+ or a string describing an error if an error occurred.
+image:load_software(name)
+ Loads a media image described in a software list. Returns ``nil`` if no
+ error or a string describing an error if an error occurred.
+image:unload()
+ Unloads the mounted image.
+image:create(filename)
+ Creates and mounts a media image file with the specified name. Returns
+ ``nil`` if no error or a string describing an error if an error
+ occurred.
+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 <luascript-ref-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 <luascript-ref-device>`.
+
+
+.. _luascript-ref-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 <luascript-ref-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 <luascript-ref-device>`.
+
+
+.. _luascript-ref-distateentry:
+
+Device state entry
+------------------
+
+Wraps MAME’s ``device_state_entry`` class, which allows access to named
+registers exposed by a :ref:`device <luascript-ref-device>`. Supports
+conversion to string for display.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].state[symbol]
+ Gets a state entry for a given device by symbol.
+
+Properties
+~~~~~~~~~~
+
+entry.value (read/write)
+ The numeric value of the state entry, as either an integer or floating-point
+ number. Attempting to set the value of a read-only state entry raises an
+ error.
+entry.symbol (read-only)
+ The state entry’s symbolic name.
+entry.visible (read-only)
+ A Boolean indicating whether the state entry should be displayed in the
+ debugger register view.
+entry.writeable (read-only)
+ A Boolean indicating whether it is possible to modify the state entry’s
+ value.
+entry.is_float (read-only)
+ A Boolean indicating whether the state entry’s value is a floating-point
+ number.
+entry.datamask (read-only)
+ A bit mask of the valid bits of the value for integer state entries.
+entry.datasize (read-only)
+ The size of the underlying value in bytes for integer state entries.
+entry.max_length (read-only)
+ The maximum display string length for the state entry.
+
+
+.. _luascript-ref-imagefmt:
+
+Media image format
+------------------
+
+Wraps MAME’s ``image_device_format`` class, which describes a media file format
+supported by a :ref:`media image device <luascript-ref-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.
+
+
+.. _luascript-ref-slotopt:
+
+Slot option
+-----------
+
+Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
+child device that a :ref:`slot device <luascript-ref-dislot>` can be
+configured to instantiate.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.slots[tag].options[name]
+ Gets a slot option for a given :ref:`slot device <luascript-ref-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.
diff --git a/docs/source/luascript/ref-input.rst b/docs/source/luascript/ref-input.rst
new file mode 100644
index 00000000000..7227ea02999
--- /dev/null
+++ b/docs/source/luascript/ref-input.rst
@@ -0,0 +1,776 @@
+.. _luascript-ref-input:
+
+Lua Input System Classes
+========================
+
+Allows scripts to get input from the user, and access I/O ports in the emulated
+system.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-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 type may be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number may be supplied as a zero-based index;
+ if the player number is not supplied, it is assumed to be zero. If the
+ input type is an input type entry, the player number may not be supplied
+ separately.
+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 <luascript-ref-inputseq>` for the
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number may be supplied as a zero-based index;
+ if the player number is not supplied, it is assumed to be zero. If the
+ input type is an input type entry, the player number may not be supplied
+ separately. 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 assignments.
+ioport:set_type_seq(type, [player], seqtype, seq)
+ Set the configured :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number must be supplied as a zero-based index.
+ If the input type is an input type entry, the player number may not be
+ supplied separately. The sequence type must be ``"standard"``,
+ ``"increment"`` or ``"decrement"``.
+
+ This allows general input assignments to be set.
+ioport:token_to_input_type(string)
+ Returns the input type and player number for the specified input type token
+ string.
+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.types[] (read-only)
+ Gets the supported :ref:`input types <luascript-ref-inputtype>`. Keys are
+ arbitrary indices. All supported operations have O(1) complexity.
+ioport.ports[]
+ Gets the emulated :ref:`I/O ports <luascript-ref-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.
+
+
+.. _luascript-ref-natkbdman:
+
+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 <luascript-ref-natkbddev>` in
+ the emulated system, indexed by absolute device tag. Index get has O(n)
+ complexity; all other supported operations have O(1) complexity.
+
+
+.. _luascript-ref-natkbddev:
+
+Keyboard input device
+---------------------
+
+Represents a keyboard or keypad input device managed by the
+:ref:`natural keyboard manager <luascript-ref-natkbdman>`. Note that this is
+not a :ref:`device <luascript-ref-device>` class.
+
+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 :ref:`device <luascript-ref-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.
+
+
+.. _luascript-ref-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 <luascript-ref-ioportfield>`
+ 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 <luascript-ref-ioportfield>` indexed by name.
+
+
+.. _luascript-ref-ioportfield:
+
+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:clear_value()
+ Clear programmatically overridden value and restore the field’s regular
+ behaviour.
+field:set_input_seq(seqtype, seq)
+ Set the :ref:`input sequence <luascript-ref-inputseq>` 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 <luascript-ref-inputseq>` 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 <luascript-ref-inputseq>` 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 <luascript-ref-inputseq>` for the
+ specified sequence type. If the default assignment is not overridden, this
+ returns the general input assignment for the field’s input type. 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 <luascript-ref-ioport>` that the field belongs to.
+field.live (read-only)
+ The :ref:`live state <luascript-ref-ioportfieldlive>` 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.minvalue (read-only)
+ The minimum allowed value for analog fields, or ``nil`` for digital fields.
+field.maxvalue (read-only)
+ The maximum allowed value for analog fields, or ``nil`` for digital fields.
+field.sensitivity (read-only)
+ The sensitivity or gain for analog fields, or ``nil`` for digital 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.
+
+
+.. _luascript-ref-ioportfieldlive:
+
+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.
+
+
+.. _luascript-ref-inputtype:
+
+Input type
+----------
+
+Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
+emulator UI input type. Input types are uniquely identified by the combination
+of their enumerated type value and player index.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport.types[index]
+ Gets a supported input type.
+
+Properties
+~~~~~~~~~~
+
+type.type (read-only)
+ An enumerated value representing the type of input.
+type.group (read-only)
+ An integer giving the grouping for the input type. Should be used to
+ provide canonical grouping in an input configuration UI.
+type.player (read-only)
+ The zero-based player number, or zero for non-player controls.
+type.token (read-only)
+ The token string for the input type, used in configuration files.
+type.name (read-only)
+ The display name for the input type.
+type.is_analog (read-only)
+ A Boolean indicating whether the input type is analog or digital. Inputs
+ that only have on and off states are considered digital, while all other
+ inputs are considered analog, even if they can only represent discrete
+ values or positions.
+
+
+.. _luascript-ref-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 <luascript-ref-inputseq>` is currently pressed.
+input:seq_clean(seq)
+ Remove invalid elements from the supplied
+ :ref:`input sequence <luascript-ref-inputseq>`. Returns the new, cleaned
+ input sequence.
+input:seq_name(seq)
+ Get display text for an :ref:`input sequence <luascript-ref-inputseq>`.
+input:seq_to_tokens(seq)
+ Convert an :ref:`input sequence <luascript-ref-inputseq>` 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 <luascript-ref-inputseq>`. This should be used when
+ loading configuration.
+input:axis_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining an analog host input code.
+input:switch_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining a host switch input code.
+input:keyboard_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining a host switch input code that only considers keyboard input
+ devices.
+input:axis_sequence_poller()
+ Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
+ obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
+ an analog input assignment.
+input:axis_sequence_poller()
+ Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
+ obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
+ a digital input assignment.
+
+Properties
+~~~~~~~~~~
+
+input.device_classes[] (read-only)
+ Gets a table of host
+ :ref:`input device classes <luascript-ref-inputdevclass>` indexed by name.
+
+
+.. _luascript-ref-inputcodepoll:
+
+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.
+
+
+.. _luascript-ref-inputseqpoll:
+
+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 <luascript-ref-inputseq>`. 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.
+
+
+.. _luascript-ref-inputseq:
+
+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 <luascript-ref-inputman>` methods. Use an
+:ref:`input sequence poller <luascript-ref-inputseqpoll>` 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.
+
+
+.. _luascript-ref-inputdevclass:
+
+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 <luascript-ref-inputdev>` in the
+ class. Keys are one-based indices.
+
+
+.. _luascript-ref-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 <luascript-ref-inputdevitem>`, indexed
+ by item ID. The item ID is an enumerated value.
+
+
+.. _luascript-ref-inputdevitem:
+
+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 <luascript-ref-inputman>` with the item’s code.
+item.code (read-only)
+ The input item’s identification code. This is used by several
+ :ref:`input manager <luascript-ref-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 <luascript-ref-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.
+
+
+.. _luascript-ref-uiinputman:
+
+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:reset()
+ Clears pending events and UI input states. Should be called when leaving a
+ modal state where input is handled directly (e.g. configuring an input
+ combination).
+uiinput:find_mouse()
+ Returns host system mouse pointer X position, Y position, button state, and
+ the :ref:`render target <luascript-ref-rendertarget>` 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.
diff --git a/docs/source/luascript/ref-mem.rst b/docs/source/luascript/ref-mem.rst
new file mode 100644
index 00000000000..d96ff8ba3ca
--- /dev/null
+++ b/docs/source/luascript/ref-mem.rst
@@ -0,0 +1,449 @@
+.. _luascript-ref-mem:
+
+Lua Memory System Classes
+=========================
+
+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.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-memman:
+
+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 <luascript-ref-memshare>` 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 <luascript-ref-membank>` 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 <luascript-ref-memregion>` 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.
+
+
+.. _luascript-ref-addrspace:
+
+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.
+space:add_change_notifier(callback)
+ Add a callback to receive notifications for handler changes in address
+ space. The callback function is passed a single string as an argument,
+ either ``r`` if read handlers have potentially changed, ``w`` if write
+ handlers have potentially changed, or ``rw`` if both read and write handlers
+ have potentially changed.
+
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+space:install_read_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on reads from the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data read,
+ and the memory access mask. The offset is the absolute offset into the
+ address space. To modify the data being read, return the modified value
+ from the callback function as an integer. If the callback does not return
+ an integer, the data will not be modified.
+space:install_write_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on write to the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data
+ written, and the memory access mask. The offset is the absolute offset into
+ the address space. To modify the data being written, return the modified
+ value from the callback function as an integer. If the callback does not
+ return an integer, the data will not be modified.
+
+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 <luascript-ref-addrmap>` for the space or
+ ``nil``.
+
+
+.. _luascript-ref-addrspacetap:
+
+Pass-through handler
+--------------------
+
+Tracks a pass-through handler installed in an
+:ref:`address space <luascript-ref-addrspace>`. A memory pass-through handler
+receives notifications on accesses to a specified range of addresses, and can
+modify the data that is read or written if desired. Note that pass-through handler
+callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on reads
+ from the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on writes to
+ the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+
+Methods
+~~~~~~~
+
+passthrough:reinstall()
+ Reinstalls the pass-through handler in the address space. May be necessary
+ if the handler is removed due to other changes to handlers in the address
+ space.
+passthrough:remove()
+ Removes the pass-through handler from the address space. The associated
+ callback will not be called in response to future memory accesses.
+
+Properties
+~~~~~~~~~~
+
+passthrough.addrstart (read-only)
+ The inclusive start address of the address range monitored by the
+ pass-through handler (i.e. the lowest address that the handler will be
+ notified for).
+passthrough.addrend (read-only)
+ The inclusive end address of the address range monitored by the pass-through
+ handler (i.e. the highest address that the handler will be notified for).
+passthrough.name (read-only)
+ The display name for the pass-through handler.
+
+
+.. _luascript-ref-addrmap:
+
+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 <luascript-ref-addrmapentry>` in the address
+ map. Uses 1-based integer indices. The index operator and the ``at``
+ method have O(n) complexity.
+
+
+.. _luascript-ref-addrmapentry:
+
+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 <luascript-ref-memhandlerdata>` for the read handler.
+entry.write (read-only)
+ :ref:`Additional data <luascript-ref-memhandlerdata>` 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.
+
+
+.. _luascript-ref-memhandlerdata:
+
+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``.
+
+
+.. _luascript-ref-memshare:
+
+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.
+
+
+.. _luascript-ref-membank:
+
+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.
+
+
+.. _luascript-ref-memregion:
+
+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.
diff --git a/docs/source/luascript/ref-render.rst b/docs/source/luascript/ref-render.rst
new file mode 100644
index 00000000000..8a2dc7f5692
--- /dev/null
+++ b/docs/source/luascript/ref-render.rst
@@ -0,0 +1,1248 @@
+.. _luascript-ref-render:
+
+Lua Render System Classes
+=========================
+
+The render system is responsible for drawing what you see in MAME’s windows,
+including emulated screens, artwork, and UI elements.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-renderbounds:
+
+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.
+
+
+.. _luascript-ref-rendercolor:
+
+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).
+
+
+.. _luascript-ref-palette:
+
+Palette
+-------
+
+Wraps MAME’s ``palette_t`` class, which represents a table of colours that can
+be looked up by zero-based index. Palettes always contain additional special
+entries for black and white.
+
+Each colour has an associated contrast adjustment value. Each adjustment group
+has associated brightness and contrast adjustment values. The palette also has
+overall brightness, contrast and gamma adjustment values.
+
+Colours are represented in alpha/red/green/blue (ARGB) format. Channel values
+range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
+Colour channel values are not pre-multiplied by the alpha value. Channel values
+are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
+green, blue from most-significant to least-significant byte.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.palette(colors, [groups])
+ Creates a palette with the specified number of colours and
+ brightness/contrast adjustment groups. The number of colour groups defaults
+ to one if not specified. Colours are initialised to black, brightness
+ adjustment is initialised to 0.0, contrast adjustment initialised to 1.0,
+ and gamma adjustment is initialised to 1.0.
+
+Methods
+~~~~~~~
+
+palette:entry_color(index)
+ Gets the colour at the specified zero-based index.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Returns black if the index is greater than or equal to the number of
+ colours in the palette.
+palette:entry_contrast(index)
+ Gets the contrast adjustment for the colour at the specified zero-based
+ index. This is a floating-point number.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Returns 1.0 if the index is greater than or equal to the number of
+ colours in the palette.
+palette:entry_adjusted_color(index, [group])
+ Gets a colour with brightness, contrast and gamma adjustments applied.
+
+ If the group is specified, colour index values range from zero to the number
+ of colours in the palette minus one, and group values range from zero to the
+ number of adjustment groups in the palette minus one.
+
+ If the group is not specified, index values range from zero to the number of
+ colours multiplied by the number of adjustment groups plus one. Index
+ values may be calculated by multiplying the zero-based group index by the
+ number of colours in the palette, and adding the zero-based colour index.
+ The last two index values correspond to the special entries for black and
+ white, respectively.
+
+ Returns black if the specified combination of index and adjustment group is
+ invalid.
+palette:entry_set_color(index, color)
+ Sets the colour at the specified zero-based index. The colour may be
+ specified as a single packed 32-bit value; or as individual red, green and
+ blue channel values, in that order.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_red_level(index, level)
+ Sets the red channel value of the colour at the specified zero-based index.
+ Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_green_level(index, level)
+ Sets the green channel value of the colour at the specified zero-based
+ index. Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_blue_level(index, level)
+ Sets the blue channel value of the colour at the specified zero-based index.
+ Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_contrast(index, level)
+ Sets the contrast adjustment value for the colour at the specified
+ zero-based index. This must be a floating-point number.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:group_set_brightness(group, brightness)
+ Sets the brightness adjustment value for the adjustment group at the
+ specified zero-based index. This must be a floating-point number.
+
+ Group values range from zero to the number of adjustment groups in the
+ palette minus one. Raises an error if the index value is invalid.
+palette:group_set_contrast(group, contrast)
+ Sets the contrast adjustment value for the adjustment group at the specified
+ zero-based index. This must be a floating-point number.
+
+ Group values range from zero to the number of adjustment groups in the
+ palette minus one. Raises an error if the index value is invalid.
+
+Properties
+~~~~~~~~~~
+
+palette.colors (read-only)
+ The number of colour entries in each group of colours in the palette.
+palette.groups (read-only)
+ The number of groups of colours in the palette.
+palette.max_index (read-only)
+ The number of valid colour indices in the palette.
+palette.black_entry (read-only)
+ The index of the special entry for the colour black.
+palette.white_entry (read-only)
+ The index of the special entry for the colour white.
+palette.brightness (write-only)
+ The overall brightness adjustment for the palette. This is a floating-point
+ number.
+palette.contrast (write-only)
+ The overall contrast adjustment for the palette. This is a floating-point
+ number.
+palette.gamma (write-only)
+ The overall gamma adjustment for the palette. This is a floating-point
+ number.
+
+
+.. _luascript-ref-bitmap:
+
+Bitmap
+------
+
+Wraps implementations of MAME’s ``bitmap_t`` and ``bitmap_specific`` classes,
+which represent two-dimensional bitmaps stored in row-major order. Pixel
+coordinates are zero-based, increasing to the right and down. Several pixel
+formats are supported.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.bitmap_ind8(palette, [width, height], [xslop, yslop])
+ Creates an 8-bit indexed bitmap. Each pixel is a zero-based, unsigned 8-bit
+ index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind16(palette, [width, height], [xslop, yslop])
+ Creates a 16-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 16-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind32(palette, [width, height], [xslop, yslop])
+ Creates a 32-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 32-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind64(palette, [width, height], [xslop, yslop])
+ Creates a 64-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 64-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_yuy16([width, height], [xslop], yslop])
+ Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling (horizontal
+ pairs of pixels have individual luma values but share chroma values). Each
+ pixel is a 16-bit integer value. The most significant byte of the pixel
+ value is the unsigned 8-bit Y' (luma) component of the pixel colour. For
+ each horizontal pair of pixels, the least significant byte of the first
+ pixel (even zero-based X coordinate) value is the signed 8-bit Cb value for
+ the pair of pixels, and the least significant byte of the second pixel (odd
+ zero-based X coordinate) value is the signed 8-bit Cr value for the pair of
+ pixels.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_rgb32([width, height], [xslop, yslop])
+ Creates an RGB format bitmap with no alpha (transparency) channel. Each
+ pixel is represented by a 32-bit integer value. The most significant byte
+ of the pixel value is ignored. The remaining three bytes, from most
+ significant to least significant, are the unsigned 8-bit unsigned red, green
+ and blue channel values (larger values correspond to higher intensities).
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_argb32([width, height], [xslop, yslop])
+ Creates an ARGB format bitmap. Each pixel is represented by a 32-bit
+ integer value. The most significant byte of the pixel is the 8-bit unsigned
+ alpha (transparency) channel value (smaller values are more transparent).
+ The remaining three bytes, from most significant to least significant, are
+ the unsigned 8-bit unsigned red, green and blue channel values (larger
+ values correspond to higher intensities). Colour channel values are not
+ pre-multiplied by the alpha channel value.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind8(source, [x0, y0, x1, y1])
+ Creates an 8-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 8-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind16(source, [x0, y0, x1, y1])
+ Creates a 16-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 16-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind32(source, [x0, y0, x1, y1])
+ Creates a 32-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 32-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind64(source, [x0, y0, x1, y1])
+ Creates a 64-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 64-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_yuy16(source, [x0, y0, x1, y1])
+ Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling representing a
+ view of a portion of an existing bitmap. The initial clipping rectangle is
+ set to the bounds of the view. The source bitmap will be locked, preventing
+ resizing and reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the Y'CbCr
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_rgb32(source, [x0, y0, x1, y1])
+ Creates an RGB format bitmap with 4:2:2 chroma subsampling representing a
+ view of a portion of an existing bitmap. The initial clipping rectangle is
+ set to the bounds of the view. The source bitmap will be locked, preventing
+ resizing and reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the RGB
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_argb32(source, [x0, y0, x1, y1])
+ Creates an ARGB format bitmap with 4:2:2 chroma subsampling representing a
+ view of a portion of an existing bitmap. The initial clipping rectangle is
+ set to the bounds of the view. The source bitmap will be locked, preventing
+ resizing and reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the ARGB
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_argb32.load(data)
+ Creates an ARGB format bitmap from data in PNG, JPEG (JFIF/EXIF) or
+ Microsoft DIB (BMP) format. Raises an error if the data invalid or not a
+ supported format.
+
+Methods
+~~~~~~~
+
+bitmap:cliprect()
+ Returns the left, top, right and bottom coordinates of the bitmap’s clipping
+ rectangle. Coordinates are in units of pixels; the bottom and right
+ coordinates are inclusive.
+bitmap:reset()
+ Sets the width and height to zero, and frees the pixel storage if the bitmap
+ owns its own storage, or releases the source bitmap if the it represents a
+ view of another bitmap.
+
+ The bitmap must be owned by the Lua script. Raises an error if the bitmap’s
+ storage is referenced by another bitmap or a :ref:`texture
+ <luascript-ref-rendertexture>`.
+bitmap:allocate(width, height, [xslop, yslop])
+ Reallocates storage for the bitmap, sets its width and height, and sets the
+ clipping rectangle to the entirety of the bitmap. If the bitmap already
+ owns allocated storage, it will always be freed and reallocated; if the
+ bitmap represents a view of another bitmap, the source bitmap will be
+ released. The storage will be filled with pixel value zero.
+
+ The X and Y slop values set the amount of extra storage in pixels to reserve
+ at the left/right of each row and top/bottom of each column, respectively.
+ If an X slop value is specified, a Y slop value must be specified as well.
+ If no X and Y slop values are specified, they are assumed to be zero (the
+ storage will be sized to fit the bitmap content). If the width and/or
+ height is less than or equal to zero, no storage will be allocated,
+ irrespective of the X and Y slop values, and the width and height of the
+ bitmap will both be set to zero.
+
+ The bitmap must be owned by the Lua script. Raises an error if the bitmap’s
+ storage is referenced by another bitmap or a :ref:`texture
+ <luascript-ref-rendertexture>`.
+bitmap:resize(width, height, [xslop, yslop])
+ Changes the width and height, and sets the clipping rectangle to the
+ entirety of the bitmap.
+
+ The X and Y slop values set the amount of extra storage in pixels to reserve
+ at the left/right of each row and top/bottom of each column, respectively.
+ If an X slop value is specified, a Y slop value must be specified as well.
+ If no X and Y slop values are specified, they are assumed to be zero (rows
+ will be stored contiguously, and the top row will be placed at the beginning
+ of the bitmap’s storage).
+
+ If the bitmap already owns allocated storage and it is large enough for the
+ updated size, it will be used without being freed; if it is too small for
+ the updated size, it will always be freed and reallocated. If the bitmap
+ represents a view of another bitmap, the source bitmap will be released. If
+ storage is allocated, it will be filled with pixel value zero (if existing
+ storage is used, its contents will not be changed).
+
+ Raises an error if the bitmap’s storage is referenced by another bitmap or a
+ :ref:`texture <luascript-ref-rendertexture>`.
+bitmap:wrap(source, [x0, y0, x1, y1])
+ Makes the bitmap represent a view of a portion of another bitmap and sets
+ the clipping rectangle to the bounds of the view.
+
+ If no coordinates are specified, the target bitmap will represent a view of
+ the source bitmap’s current clipping rectangle. If coordinates are
+ specified, the target bitmap will represent a view of the rectangle with top
+ left corner at (x0, y0) and bottom right corner at (x1, y1) in the source
+ bitmap. Coordinates are in units of pixels. The bottom right coordinates
+ are inclusive.
+
+ The source bitmap will be locked, preventing resizing and reallocation. If
+ the target bitmap owns allocated storage, it will be freed; if it represents
+ a view of another bitmap, the current source bitmap will be released.
+
+ The source and target bitmaps must both be owned by the Lua script and must
+ use the same pixel format. Raises an error if coordinates are specified
+ representing a rectangle not fully contained within the source bitmap’s
+ clipping rectangle; if the bitmap’s storage is referenced by another bitmap
+ or a :ref:`texture <luascript-ref-rendertexture>`; or if the source and
+ target are the same bitmap.
+bitmap:pix(x, y)
+ Returns the colour value of the pixel at the specified location.
+ Coordinates are zero-based in units of pixels.
+bitmap:pixels([x0, y0, x1, y1])
+ Returns the pixels, width and height of the portion of the bitmap with top
+ left corner at (x0, y0) and bottom right corner at (x1, y1). Coordinates
+ are in units of pixels. The bottom right coordinates are inclusive. If
+ coordinates are not specified, the bitmap’s clipping rectangle is used.
+
+ Pixels are returned packed into a binary string in host Endian order.
+ Pixels are organised in row-major order, from left to right then top to
+ bottom. The size and format of the pixel values depends on the format of
+ the bitmap. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the bitmap’s clipping rectangle.
+bitmap:fill(color, [x0, y0, x1, y1])
+ Fills a portion of the bitmap with the specified colour value. If
+ coordinates are not specified, the clipping rectangle is filled; if
+ coordinates are specified, the intersection of the clipping rectangle and
+ the rectangle with top left corner at (x0, y0) and bottom right corner at
+ (x1, y1) is filled. Coordinates are in units of pixels. The bottom right
+ coordinates are inclusive.
+bitmap:plot(x, y, color)
+ Sets the colour value of the pixel at the specified location if it is within
+ the clipping rectangle. Coordinates are zero-based in units of pixels.
+bitmap:plot_box(x, y, width, height, color)
+ Fills the intersection of the clipping rectangle and the rectangle with top
+ left (x, y) and the specified height and width with the specified colour
+ value. Coordinates and dimensions are in units of pixels.
+
+Properties
+~~~~~~~~~~
+
+bitmap.palette (read/write)
+ The :ref:`palette <luascript-ref-palette>` used to translate pixel
+ values to colours. Only applicable for bitmaps that use indexed pixel
+ formats.
+bitmap.width (read-only)
+ Width of the bitmap in pixels.
+bitmap.height (read-only)
+ Height of the bitmap in pixels.
+bitmap.rowpixels (read-only)
+ Row stride of the bitmap’s storage in pixels. That is, the difference in
+ pixel offsets of the pixels at the same horizontal location in consecutive
+ rows. May be greater than the width.
+bitmap.rowbytes (read-only)
+ Row stride of the bitmap’s storage in bytes. That is, the difference in
+ byte addresses of the pixels at the same horizontal location in consecutive
+ rows.
+bitmap.bpp (read-only)
+ Size of the type used to represent pixels in the bitmap in bits (may be
+ larger than the number of significant bits).
+bitmap.valid (read-only)
+ A Boolean indicating whether the bitmap has storage available (may be false
+ for empty bitmaps).
+bitmap.locked (read-only)
+ A Boolean indicating whether the bitmap’s storage is referenced by another
+ bitmap or a :ref:`texture <luascript-ref-rendertexture>`.
+
+
+.. _luascript-ref-rendertexture:
+
+Render texture
+--------------
+
+Wraps MAME’s ``render_texture`` class, representing a texture that cam be drawn
+in a :ref:`render container <luascript-ref-rendercontainer>`. Render textures
+must be freed before the emulation session ends.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render:texture_alloc(bitmap)
+ Creates a render texture based on a :ref:`bitmap
+ <luascript-ref-bitmap>`. The bitmap must be owned by the Lua script, and
+ must use the Y'CbCr, RGB or ARGB format. The bitmap’s storage will be
+ locked, preventing resizing and reallocation.
+
+Methods
+~~~~~~~
+
+texture:free()
+ Frees the texture. The storage of the underlying bitmap will be released.
+
+Properties
+~~~~~~~~~~
+
+texture.valid (read-only)
+ A Boolean indicating whether the texture is valid (false if the texture has
+ been freed).
+
+
+.. _luascript-ref-renderman:
+
+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.
+
+Methods
+~~~~~~~
+
+render:texture_alloc(bitmap)
+ Creates a :ref:`render texture <luascript-ref-rendertexture>` based on a
+ :ref:`bitmap <luascript-ref-bitmap>`. The bitmap must be owned by the Lua
+ script, and must use the Y'CbCr, RGB or ARGB pixel format. The bitmap’s
+ storage will be locked, preventing resizing and reallocation. Render
+ textures must be freed before the emulation session ends.
+
+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 <luascript-ref-rendertarget>` 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 <luascript-ref-rendercontainer>` 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.
+
+
+.. _luascript-ref-rendertarget:
+
+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 <luascript-ref-renderlayview>` 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.
+
+
+.. _luascript-ref-rendercontainer:
+
+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
+ the screen that shows 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(x0, y0, x1, y1, [color])
+ Draws a line from (x0, y0) to (x1, y1).
+
+ 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
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or 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_quad(texture, x0, y0, x1, y1, [color])
+ Draws a textured rectangle with top left corner at (x0, y0) and bottom right
+ corner at (x1, y1). If a colour is specified, the ARGB channel values of
+ the texture’s pixels are multiplied by the corresponding values of the
+ specified colour.
+
+ 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
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. If the rectangle extends beyond the container’s bounds,
+ it will be cropped.
+
+ The 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.
+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
+ the screen that shows 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 <luascript-ref-rendercntnrsettings>`.
+ 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.
+
+
+.. _luascript-ref-rendercntnrsettings:
+
+Container user settings
+-----------------------
+
+Wraps MAME’s ``render_container::user_settings`` class, representing image
+adjustments applied to a
+:ref:`render container <luascript-ref-rendercontainer>`.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.screens[tag].container
+ Gets the current render container user settings for a given emulated 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.
+
+
+.. _luascript-ref-renderlayfile:
+
+Layout file
+-----------
+
+Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
+file for use by a render target. Note that layout file callbacks are not run as
+coroutines.
+
+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 <luascript-ref-renderlayview>` 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 some views in the XML file may not 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 emulated system.
+
+
+.. _luascript-ref-renderlayview:
+
+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. Note that layout view callbacks are not run as
+coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render.targets[index].current_view
+ Gets the currently selected view for a given render target.
+file.views[name]
+ Gets the view with the specified name from a
+ :ref:`layout file <luascript-ref-renderlayfile>`. This is how layout
+ scripts generally obtain views.
+
+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 <luascript-ref-renderlayitem>` 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 <luascript-ref-renderbounds>` 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.
+
+
+.. _luascript-ref-renderlayitem:
+
+Layout view item
+----------------
+
+Wraps MAME’s ``layout_view_item`` class, representing an item in a :ref:`layout
+view <luascript-ref-renderlayview>`. An item is drawn as a rectangular textured
+surface. The texture is supplied by an emulated screen or a layout element.
+Note that layout view item callbacks are not run as coroutines.
+
+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 <luascript-ref-renderbounds>` 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 <luascript-ref-rendercolor>` 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 <luascript-ref-renderbounds>` 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 <luascript-ref-rendercolor>` 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.