From 4d7ef2749083e5e3aaf41e5b2c6b03a93c237c47 Mon Sep 17 00:00:00 2001 From: Vas Crabb Date: Sun, 13 Dec 2020 09:54:03 +1100 Subject: -luaengine.cpp: Clean up render classes and expose screen image adjustments. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Started moving Lua class reference to docs. Expecting people to find the class reference material in the source isn’t going to help make it approachable. The docs allow longer explanations, better formatting, and cross reference links. * Added another layout scripting example to the docs. -goldnpkr.cpp: Minor clean-up. * Improved the short names for Witch Card and Witch Game clone sets. * Made Witch Up & Down artwork clickable. * Added working Video Klein sets where the parent is a working Video Klein set to the tiny subtarget. * Removed history from the header comment - we have version control for a readon. --- docs/source/techspecs/layout_script.rst | 405 +++++++++++++++++++++++++++++++- 1 file changed, 404 insertions(+), 1 deletion(-) (limited to 'docs/source/techspecs/layout_script.rst') diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst index 968a8fe81fb..2291a3c4eb4 100644 --- a/docs/source/techspecs/layout_script.rst +++ b/docs/source/techspecs/layout_script.rst @@ -33,7 +33,13 @@ Practical examples ------------------ Before diving into the technical details of how it works, we’ll start with some -example layout files using Lua script for enhancement. +example layout files using Lua script for enhancement. It’s assumed that you’re +familiar with MAME’s artwork system and have a basic understanding of Lua +scripting. For details on MAME’s layout file, see :ref:`layfile`; for an +introduction to Lua scripting in MAME, see :ref:`luaengine`; for detailed +descriptions of MAME’s Lua classes, see :ref:`luareference`. + +.. _layscript-examples-espial: Espial: joystick split across ports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -201,3 +207,400 @@ This function does the following tasks: The function called before view items are added to the render target reads the player inputs, and shuffles the bits into the order needed by the joystick element. + +.. _layscript-examples-starwars: + +Star Wars: animation on two axes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We’ll make a layout that shows the position of the flight yoke for Atari Star +Wars. The input ports are straightforward – each analog axis produces a value +in the range from 0x00 (0) to 0xff (255), inclusive: + +.. code-block:: C++ + + PORT_START("STICKY") + PORT_BIT( 0xff, 0x80, IPT_AD_STICK_Y ) PORT_SENSITIVITY(70) PORT_KEYDELTA(30) + + PORT_START("STICKX") + PORT_BIT( 0xff, 0x80, IPT_AD_STICK_X ) PORT_SENSITIVITY(50) PORT_KEYDELTA(30) + +Here’s our layout file: + +.. code-block:: XML + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +The layout has a ``script`` element containing the Lua script, to be called as a +function by the layout plugin when the layout file is loaded. This happens +after the layout views have been build, but before the emulated system has +finished starting. The layout file object is supplied to the script in the +``file`` variable. + +We supply a function to be called after tags in the layout file have been +resolved. This function does the following: + +* Looks up the analog axis inputs. +* Looks up the view item that draws the outline of area where the yoke position + is displayed. +* Declares some variables to hold calculated values across function calls. +* Supplies a function to be called when the view’s dimensions have been + recomputed. +* Supplies a function to be called before adding view items to the render + container. +* Supplies functions that will supply the bounds for the animated items. +* Hides the warning that reminds the user to enable the layout plugin by setting + the element state for the item to 0 (the text component is only drawn when + the element state is 1). + +The view is looked up by name (value of its ``name`` attribute), and items +within the view are looked up by ID (values of their ``id`` attributes). + +Layout view dimensions are recomputed in response to several events, including +the window being resized, entering/leaving full screen mode, toggling visibility +of item collections, and changing the zoom to screen area setting. When this +happens, we need to update our size and animation scale factors. We get the +bounds of the square where the yoke position is displayed, calculate the size +for the animated items, and calculate the ratios of axis units to render target +coordinates in each direction. It’s more efficient to do these calculations +only when the results may change. + +Before view items are added to the render target, we read the analog axis inputs +and convert the values to coordinates positions for the animated items. The Y +axis input uses larger values to aim higher, so we need to reverse the value by +subtracting it from 0xff (255). We add in the coordinates of the top left +corner of the square where we’re displaying the yoke position. We do this once +each time the layout is drawn for efficiency, since we can use the values for +all three animated items. + +Finally, we supply bounds for the animated items when required. These functions +need to return ``render_bounds`` objects giving the position and size of the +items in render target coordinates. + +(Since the vertical and horizontal line elements each only move on a single +axis, it would be possible to animate them using the layout file format’s item +animation features. Only the box at the intersection of the line actually +requires scripting. It’s done entirely using scripting here for illustrative +purposes.) + + +.. _layscript-environment: + +The layout script environment +----------------------------- + +The Lua environment is provided by the layout plugin. It’s fairly minimal, only +providing what’s needed: + +* ``file`` giving the script’s layout file object. Has a ``device`` property + for obtaining the device that caused the layout file to be loaded, and a + ``views`` property for obtaining the layout’s views (indexed by name). +* ``machine`` giving MAME’s current running machine. +* ``emu.render_bounds`` and ``emu.render_color`` functions for creating bounds + and colour objects. +* ``emu.print_error``, ``emu.print_info`` and ``emu.print_debug`` functions for + diagnostic output. +* Standard Lua ``pairs``, ``ipairs``, ``table.insert`` and ``table.remove`` + functions for manipulating tables and other containers. +* Standard Lua ``print`` function for text output to the console. +* Standard Lua ``string.format`` function for string formatting. + + +.. _layscript-events: + +Layout events +------------- + +MAME layout scripting uses an event-based model. Scripts can supply functions +to be called after events occur, or when data is needed. There are three levels +of events: layout file events, layout view events, and layout view item events. + +.. _layscript-events-file: + +Layout file events +~~~~~~~~~~~~~~~~~~ + +Layout file events apply to the file as a whole, and not to an individual view. + +Resolve tags + ``file:set_resolve_tags_callback(cb)`` + + Called after the emulated system has finished starting, input and output + tags in the layout have been resolved, and default item callbacks have been + set up. This is a good time to look up inputs and set up view item event + handlers. + + The callback function has no return value and takes no parameters. Call + with ``nil`` as the argument to remove the event handler. + +.. _layscript-events-view: + +Layout view events +~~~~~~~~~~~~~~~~~~ + +Layout view events apply to an individual view. + +Prepare items + ``view:set_prepare_items_callback(cb)`` + + Called before the view’s items are added to the render target in preparation + for drawing a video frame. + + The callback function has no return value and takes no parameters. Call + with ``nil`` as the argument to remove the event handler. +Preload + ``view:set_preload_callback(cb)`` + + Called after pre-loading visible view elements. This can happen when the + view is selected for the first time in a session, or when the user toggles + visibility of an element collection on. Be aware that this can be called + multiple times in a session and avoid repeating expensive tasks. + + The callback function has no return value and takes no parameters. Call + with ``nil`` as the argument to remove the event handler. +Dimensions recomputed + ``view:set_recomputed_callback(cb)`` + + Called after view dimensions are recomputed. This happens in several + situations, including the window being resized, entering or leaving full + screen mode, toggling visibility of item collections, and changes to the + rotation and zoom to screen area settings. If you’re animating the position + of view items, this is a good time to calculate positions and scale factors. + + The callback function has no return value and takes no parameters. Call + with ``nil`` as the argument to remove the event handler. + +.. _layscript-events-item: + +Layout view item events +~~~~~~~~~~~~~~~~~~~~~~~ + +Layout view item callbacks apply to individual items within a view. They are +used to override items’ default element state, animation state, bounds and +colour behaviour. + +Get element state + ``item:set_element_state_callback(cb)`` + + Set callback for getting the item’s element state. This controls how the + item’s element is drawn, for components that change appearance depending on + state, conditionally-drawn components, and component bounds/colour + animation. Do not attempt to access the item’s ``element_state`` property + from the callback, as it will result in infinite recursion. + + The callback function must return an integer, and takes no parameters. Call + with ``nil`` as the argument to restore the default element state + handler (based on the item’s XML attributes). +Get animation state + ``item:set_animation_state_callback(cb)`` + + Set callback for getting the item’s animation state. This is used for item + bounds/colour animation. Do not attempt to access the item’s + ``animation_state`` property from the callback, as it will result in + infinite recursion. + + The callback function must return an integer, and takes no parameters. Call + with ``nil`` as the argument to restore the default animation state handler + (based on the item’s XML attributes and ``animate`` child element). +Get item bounds + ``item:set_bounds_callback(cb)`` + + Set callback for getting the item’s bounds (position and size). Do not + attempt to access the item’s ``bounds`` property from the callback, as it + will result in infinite recursion. + + The callback function must return a render bounds object representing the + item’s bounds in render target coordinates (usually created by calling + ``emu.render_bounds``), and takes no parameters. Call with ``nil`` as the + argument to restore the default bounds handler (based on the item’s + animation state and ``bounds`` child elements). +Get item colour + ``item::set_color_callback(cb)`` + + Set callback for getting the item’s colour (the element texture’s colours + multiplied by this colour). Do not attempt to access the item’s ``color`` + property from the callback, as it will result in infinite recursion. + + The callback function must return a render colour object representing the + ARGB colour (usually created by calling ``emu.render_color``), and takes no + parameters. Call with ``nil`` as the argument to restore the default colour + handler (based on the item’s animation state and ``color`` child elements). -- cgit v1.2.3-70-g09d2