diff options
author | 2023-04-07 06:20:40 +1000 | |
---|---|---|
committer | 2023-04-07 06:20:40 +1000 | |
commit | b67b969bf0911d71396c77e42d85ddfe80de6f20 (patch) | |
tree | 8d964eac6e0c4c849dc2b9b0b3742154c6c943d4 /docs/source/techspecs | |
parent | c4282fecede9032be78028e8fde737d44bf2b7c6 (diff) |
-Improved some Lua APIs:
* Moved several machine lifecycle callbacks to the notifier/subscriber
model. The old callback registration model is still available for
them for now, but prints a deprecation warning.
* Added pre-save/post-load notifications.
* Use a single allocated timer rather than one anonymous timer per
waiter. Waiters no longer prevent saved states from being loaded.
* Clean up outstanding waiters on stop or state load rather than just
leaking them.
* Started documenting parts of the emulator interface object that should
be relatively stable.
-imagedev/avivideo.cpp: Fixed an object leak on unload. Also changed
some other media image devices to use smart pointers.
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r-- | docs/source/techspecs/luaengine.rst | 12 | ||||
-rw-r--r-- | docs/source/techspecs/luareference.rst | 88 |
2 files changed, 90 insertions, 10 deletions
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst index 5e97d4e3885..7f2ba99545a 100644 --- a/docs/source/techspecs/luaengine.rst +++ b/docs/source/techspecs/luaengine.rst @@ -53,9 +53,9 @@ Many of the classes are documented on the Usage ----- -MAME supports external scripting via Lua (>= 5.3) scripts, either entered at the +MAME supports external scripting via Lua scripts, either entered at the interactive console or loaded as a file. To reach the console, enable the -console plugin (e.g. run MAME with ``-plugin console``) and you will be greeted +console plugin (e.g. run MAME with ``-console``) and you will be greeted with a ``[MAME]>`` prompt where you can enter Lua script interactively. To load a whole script at once, store it in a plain text file and pass it using @@ -78,7 +78,7 @@ Let’s first run MAME in a terminal to reach the Lua console: :: - $ mame -console YOUR_ROM + $ mame -console YOUR_SYSTEM /| /| /| /| /| _______ / | / | / | / | / | / / / |/ | / | / |/ | / ____/ @@ -90,10 +90,10 @@ Let’s first run MAME in a terminal to reach the Lua console: / / / _/ - mame 0.227 + mame 0.254 Copyright (C) Nicola Salmoria and the MAME team - Lua 5.3 + Lua 5.4 Copyright (C) Lua.org, PUC-Rio [MAME]> @@ -113,7 +113,7 @@ You can check at runtime which version of MAME you are running, with: :: [MAME]> print(emu.app_name() .. " " .. emu.app_version()) - mame 0.227 + mame 0.254 We now start exploring screen related methods. First, let's enumerate available screens: diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst index ec7727916db..967fc889729 100644 --- a/docs/source/techspecs/luareference.rst +++ b/docs/source/techspecs/luareference.rst @@ -55,6 +55,82 @@ c:index_of(v) value. +.. _luareference-globals: + +Global objects +-------------- + +.. _luareference-globals-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 <luareference-core-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 <luareference-core-notifiersub>`. +emu.add_machine_stop_notifier(callback) + Add a callback to receive notifications when the emulated system is stopped. + Returns a :ref:`notifier subscription <luareference-core-notifiersub>`. +emu.add_machine_pause_notifier(callback) + Add a callback to receive notifications when the emulated system is paused. + Returns a :ref:`notifier subscription <luareference-core-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 <luareference-core-notifiersub>`. +emu.add_machine_frame_notifier(callback) + Add a callback to receive notifications when an emulated frame completes. + Returns a :ref:`notifier subscription <luareference-core-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 <luareference-core-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 <luareference-core-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. + + .. _luareference-core: Core classes @@ -1598,7 +1674,8 @@ Pass-through handler Tracks a pass-through handler installed in an :ref:`address space <luareference-mem-space>`. 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. +modify the data that is read or written if desired. Note that pass-through handler +callbacks are not run as coroutines. Instantiation ^^^^^^^^^^^^^ @@ -3572,7 +3649,8 @@ Layout file ~~~~~~~~~~~ Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout -file for use by a render target. +file for use by a render target. Note that layout file callbacks are not run as +coroutines. Instantiation ^^^^^^^^^^^^^ @@ -3616,7 +3694,8 @@ 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. +screens in the emulated system. Note that layout view callbacks are not run as +coroutines. Instantiation ^^^^^^^^^^^^^ @@ -3695,7 +3774,8 @@ Layout view item Wraps MAME’s ``layout_view_item`` class, representing an item in a view. An item is drawn as a rectangular textured surface. The texture is supplied by an -emulated screen or a layout element. +emulated screen or a layout element. Note that layout view item callbacks are +not run as coroutines. Instantiation ^^^^^^^^^^^^^ |