diff options
author | 2023-07-06 09:52:10 +1000 | |
---|---|---|
committer | 2023-07-06 09:52:10 +1000 | |
commit | 12623c3fd35984f75e31144126689986af657a30 (patch) | |
tree | 8b8b01669ab168705148152e3f4a3622945dd04c /docs/source/luascript | |
parent | 737af4b6655d1de338895272bfeeec8bb7b7b17f (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.rst | 235 | ||||
-rw-r--r-- | docs/source/luascript/ref-common.rst | 118 | ||||
-rw-r--r-- | docs/source/luascript/ref-core.rst | 635 | ||||
-rw-r--r-- | docs/source/luascript/ref-debugger.rst | 451 | ||||
-rw-r--r-- | docs/source/luascript/ref-devices.rst | 764 | ||||
-rw-r--r-- | docs/source/luascript/ref-input.rst | 776 | ||||
-rw-r--r-- | docs/source/luascript/ref-mem.rst | 449 | ||||
-rw-r--r-- | docs/source/luascript/ref-render.rst | 1248 |
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. |