summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2020-12-13 09:54:03 +1100
committer Vas Crabb <vas@vastheman.com>2020-12-13 09:54:03 +1100
commit4d7ef2749083e5e3aaf41e5b2c6b03a93c237c47 (patch)
tree47076411b64212db0145e73f953325affa9d49dc /docs
parentbc951bcfa9c9b4a54e40dc3ab5559531f820fafc (diff)
-luaengine.cpp: Clean up render classes and expose screen image adjustments.
* 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.
Diffstat (limited to 'docs')
-rw-r--r--docs/source/techspecs/index.rst1
-rw-r--r--docs/source/techspecs/layout_script.rst405
-rw-r--r--docs/source/techspecs/luaengine.rst20
-rw-r--r--docs/source/techspecs/luareference.rst582
4 files changed, 1005 insertions, 3 deletions
diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst
index 0435dd486e8..37d37c73479 100644
--- a/docs/source/techspecs/index.rst
+++ b/docs/source/techspecs/index.rst
@@ -18,4 +18,5 @@ MAME’s source or working on scripts that run within the MAME framework.
floppy
nscsi
luaengine
+ luareference
m6502
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
+
+ <?xml version="1.0"?>
+ <mamelayout version="2">
+
+ <!-- a square with a white outline 1% of its width -->
+ <element name="outline">
+ <rect><bounds x="0.00" y="0.00" width="1.00" height="0.01" /></rect>
+ <rect><bounds x="0.00" y="0.99" width="1.00" height="0.01" /></rect>
+ <rect><bounds x="0.00" y="0.00" width="0.01" height="1.00" /></rect>
+ <rect><bounds x="0.99" y="0.00" width="0.01" height="1.00" /></rect>
+ </element>
+
+ <!-- a rectangle with a vertical line 10% of its width down the middle -->
+ <element name="line">
+ <!-- use a transparent rectangle to force element dimensions -->
+ <rect>
+ <bounds x="0" y="0" width="0.1" height="1" />
+ <color alpha="0" />
+ </rect>
+ <!-- this is the visible white line -->
+ <rect><bounds x="0.045" y="0" width="0.01" height="1" /></rect>
+ </element>
+
+ <!-- an outlined square inset by 20% with lines 10% of the element width/height -->
+ <element name="box">
+ <!-- use a transparent rectangle to force element dimensions -->
+ <rect>
+ <bounds x="0" y="0" width="0.1" height="0.1" />
+ <color alpha="0" />
+ </rect>
+ <!-- draw the outlined of a square -->
+ <rect><bounds x="0.02" y="0.02" width="0.06" height="0.01" /></rect>
+ <rect><bounds x="0.02" y="0.07" width="0.06" height="0.01" /></rect>
+ <rect><bounds x="0.02" y="0.02" width="0.01" height="0.06" /></rect>
+ <rect><bounds x="0.07" y="0.02" width="0.01" height="0.06" /></rect>
+ </element>
+
+ <!-- we'll warn the user if the layout plugin isn't enabled -->
+ <!-- draw only when state is 1, and set the default state to 1 so warning is visible initially -->
+ <element name="warning" defstate="1">
+ <text state="1" string="This view requires the layout plugin." />
+ </element>
+
+ <!-- view showing the screen and flight yoke position -->
+ <view name="Analog Control Display">
+ <!-- draw the screen with correct aspect ratio -->
+ <screen index="0">
+ <bounds x="0" y="0" width="4" height="3" />
+ </screen>
+
+ <!-- draw the white outlined square to the right of the screen near the bottom -->
+ <!-- the script uses the size of this item to determine movement ranges -->
+ <element id="outline" ref="outline">
+ <bounds x="4.1" y="1.9" width="1.0" height="1.0" />
+ </element>
+
+ <!-- vertical line for displaying X axis input -->
+ <element id="vertical" ref="line">
+ <!-- element draws a vertical line, no need to rotate it -->
+ <orientation rotate="0" />
+ <!-- centre it in the square horizotnally, using the full height -->
+ <bounds x="4.55" y="1.9" width="0.1" height="1" />
+ </element>
+
+ <!-- horizontal line for displaying Y axis input -->
+ <element id="horizontal" ref="line">
+ <!-- rotate the element by 90 degrees to get a horizontal line -->
+ <orientation rotate="90" />
+ <!-- centre it in the square vertically, using the full width -->
+ <bounds x="4.1" y="2.35" width="1" height="0.1" />
+ </element>
+
+ <!-- draw a small box at the intersection of the vertical and horiztonal lines -->
+ <element id="box" ref="box">
+ <bounds x="4.55" y="2.35" width="0.1" height="0.1" />
+ </element>
+
+ <!-- draw the warning text over the screen near the bottom -->
+ <element id="warning" ref="warning">
+ <bounds x="0.2" y="2.6" width="3.6" height="0.2" />
+ </element>
+ </view>
+
+ <!-- the content of the script element will be called as a function by the layout plugin -->
+ <!-- use CDATA block to avoid the need to escape angle brackets and ampersands -->
+ <script><![CDATA[
+ -- file is the layout file object
+ -- set a function to call after resolving tags
+ file:set_resolve_tags_callback(
+ function ()
+ -- file.device is the device that caused the layout to be loaded
+ -- in this case, it's the root machine driver for starwars
+ -- find the analog axis inputs
+ local x_input = file.device:ioport("STICKX")
+ local y_input = file.device:ioport("STICKY")
+
+ -- find the outline item
+ local outline_item = file.views["Analog Control Display"].items["outline"]
+
+ -- variables for keeping state across callbacks
+ local outline_bounds -- bounds of the outlined square
+ local width, height -- width and height for animated items
+ local x_scale, y_scale -- ratios of axis units to render coordinates
+ local x_pos, y_pos -- display positions for the animated items
+
+ -- set a function to call when view dimensions have been recalculated
+ -- this can happen when when the window is resized or scaling options are changed
+ file.views["Analog Control Display"]:set_recomputed_callback(
+ function ()
+ -- get the bounds of the outlined square
+ outline_bounds = outline_item.bounds
+ -- animated items use 10% of the width/height of the square
+ width = outline_bounds.width * 0.1
+ height = outline_bounds.height * 0.1
+ -- calculate ratios of axis units to render coordinates
+ -- animated items leave 90% of the width/height for the movement range
+ -- the end of the range of each axis is at 0xff
+ x_scale = outline_bounds.width * 0.9 / 0xff
+ y_scale = outline_bounds.height * 0.9 / 0xff
+ end)
+
+ -- set a function to call before adding the view items to the render target
+ file.views["Analog Control Display"]:set_prepare_items_callback(
+ function ()
+ -- read analog axes, reverse Y axis as zero is at the bottom
+ local x = x_input:read() & 0xff
+ local y = 0xff - (y_input:read() & 0xff)
+ -- convert the input values to layout coordinates
+ -- use the top left corner of the outlined square as the origin
+ x_pos = outline_bounds.x0 + (x * x_scale)
+ y_pos = outline_bounds.y0 + (y * y_scale)
+ end)
+
+ -- set a function to supply the bounds for the vertical line
+ file.views["Analog Control Display"].items["vertical"]:set_bounds_callback(
+ function ()
+ -- create a new render bounds object (starts as a unit square)
+ local result = emu.render_bounds()
+ -- set left, top, width and height
+ result:set_wh(
+ x_pos, -- calculated X position for animated items
+ outline_bounds.y0, -- top of outlined square
+ width, -- 10% of width of outlined square
+ outline_bounds.height) -- full height of outlined square
+ return result
+ end)
+
+ -- set a function to supply the bounds for the horizontal line
+ file.views["Analog Control Display"].items["horizontal"]:set_bounds_callback(
+ function ()
+ -- create a new render bounds object (starts as a unit square)
+ local result = emu.render_bounds()
+ -- set left, top, width and height
+ result:set_wh(
+ outline_bounds.x0, -- left of outlined square
+ y_pos, -- calculated Y position for animated items
+ outline_bounds.width, -- full width of outlined square
+ height) -- 10% of height of outlined square
+ return result
+ end)
+
+ -- set a function to supply the bounds for the box at the intersection of the lines
+ file.views["Analog Control Display"].items["box"]:set_bounds_callback(
+ function ()
+ -- create a new render bounds object (starts as a unit square)
+ local result = emu.render_bounds()
+ -- set left, top, width and height
+ result:set_wh(
+ x_pos, -- calculated X position for animated items
+ y_pos, -- calculated Y position for animated items
+ width, -- 10% of width of outlined square
+ height) -- 10% of height of outlined square
+ return result
+ end)
+
+ -- hide the warning, since if we got here the script is running
+ file.views["Analog Control Display"].items["warning"]:set_state(0)
+ end)
+ ]]></script>
+
+ </mamelayout>
+
+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).
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst
index 4b9c3f0e555..22981fe79e6 100644
--- a/docs/source/techspecs/luaengine.rst
+++ b/docs/source/techspecs/luaengine.rst
@@ -1,6 +1,13 @@
-Scripting MAME via LUA
+.. _luaengine:
+
+Scripting MAME via Lua
======================
+.. contents:: :local:
+
+
+.. _luaengine-intro:
+
Introduction
------------
@@ -19,6 +26,9 @@ change without prior notice. However, we expose methods to let you know at
runtime which API version you are running against, and most of the objects
support runtime you can introspection.
+
+.. _luaengine-features:
+
Features
--------
@@ -34,6 +44,9 @@ currently available to Lua scripts:
- memory read/write (8/16/32/64 bits, signed and unsigned)
- register and state control (state enumeration, get and set)
+
+.. _luaengine-usage:
+
Usage
-----
@@ -52,10 +65,13 @@ approach. The former is not encouraged as it is resource-intensive and makes
control flow unnecessarily complex. Instead, we suggest to register custom
hooks to be invoked on specific events (e.g. at each frame rendering).
+
+.. _luaengine-walkthrough:
+
Walkthrough
-----------
-Let's first run MAME in a terminal to reach the LUA console:
+Let's first run MAME in a terminal to reach the Lua console:
::
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
new file mode 100644
index 00000000000..ac606f02293
--- /dev/null
+++ b/docs/source/techspecs/luareference.rst
@@ -0,0 +1,582 @@
+.. _luareference:
+
+MAME Lua Class Reference
+========================
+
+.. contents::
+ :local:
+ :depth: 2
+
+
+.. _luareference-intro:
+
+Introduction
+------------
+
+Various aspects of MAME can be controlled using Lua scripting. Many key classes
+are exposed as Lua objects.
+
+.. _luareference-intro-containers:
+
+Containers
+~~~~~~~~~~
+
+Many properties yield container wrappers. Container wrappers are cheap to
+create, and provide an interface that is similar to a read-only table. The
+complexity of operations may vary. Container wrappers usually provide most of
+these operations:
+
+#c
+ Get the number of items in the container.
+c[k]
+ Returns the item corresponding to the key ``k``, or ``nil`` if the key is
+ not present.
+pairs(c)
+ Iterate container by key and value. The key is what you would pass to the
+ index operator or the ``get`` method to get the value.
+ipairs(c)
+ Iterate container by index and value. The index is what you would pass to
+ the ``at`` method to get the value (this may be the same as the key for some
+ containers).
+c:empty()
+ Returns a Boolean indicating whether there are no items in the container.
+c:get(k)
+ Returns the item corresponding to the key ``k``, or ``nil`` if the key is
+ not present. Usually equivalent to the index operator.
+c:at(i)
+ Returns the value at the 1-based index ``i``, or ``nil`` if it is out of
+ range.
+c:find(v)
+ Returns the key for item ``v``, or ``nil`` if it is not in the collection.
+ The key is what you would pass to the index operator to get the value.
+c:find(v)
+ Returns the key for item ``v``, or ``nil`` if it is not in the container.
+ The key is what you would pass to the index operator to get the value.
+c:index_of(v)
+ Returns the 1-based index for item ``v``, or ``nil`` if it is not in the
+ container. The index is what you would pass to the ``at`` method to get the
+ value.
+
+
+.. _luareference-render:
+
+Render system
+-------------
+
+The render system is responsible for drawing what you see in MAME’s windows,
+including emulated screens, artwork, and UI elements.
+
+.. _luareference-render-bounds:
+
+Render bounds
+~~~~~~~~~~~~~
+
+Wraps MAME’s ``render_bounds`` class, which represents a rectangle using
+floating-point coordinates.
+
+Instantiation
+^^^^^^^^^^^^^
+
+emu.render_bounds()
+ Creates a render bounds object representing a unit square, with top left
+ corner at (0, 0) and bottom right corner at (1, 1). Note that render
+ target coordinates don’t necessarily have equal X and Y scales, so this may
+ not represent a square in the final output.
+emu.render_bounds(left, top, right, bottom)
+ Creates a render bounds object representing a rectangle with top left
+ corner at (x0, y0) and bottom right corner at (x1, y1).
+
+ The arguments must all be floating-point numbers.
+
+Methods
+^^^^^^^
+
+bounds:includes(x, y)
+ Returns a Boolean indicating whether the specified point falls within the
+ rectangle. The rectangle must be normalised for this to work (right greater
+ than left and bottom greater than top).
+
+ The arguments must both be floating-point numbers.
+bounds:set_xy(left, top, right, bottom)
+ Set the rectangle’s position and size in terms of the positions of the
+ edges.
+
+ The arguments must all be floating-point numbers.
+bounds:set_wh(left, top, width, height)
+ Set the rectangle’s position and size in terms of the top top left corner
+ position, and the width and height.
+
+ The arguments must all be floating-point numbers.
+
+Properties
+^^^^^^^^^^
+
+bounds.x0 (read/write)
+ The leftmost coordinate in the rectangle (i.e. the X coordinate of the left
+ edge or the top left corner).
+bounds.x1 (read/write)
+ The rightmost coordinate in the rectangle (i.e. the X coordinate of the
+ right edge or the bottom right corner).
+bounds.y0 (read/write)
+ The topmost coordinate in the rectangle (i.e. the Y coordinate of the top
+ edge or the top left corner).
+bounds.y1 (read/write)
+ The bottommost coordinate in the rectangle (i.e. the Y coordinate of the
+ bottom edge or the bottom right corner).
+bounds.width (read/write)
+ The width of the rectangle. Setting this property changes the position of
+ the rightmost edge.
+bounds.height (read/write)
+ The height of the rectangle. Setting this property changes the position of
+ the bottommost edge.
+bounds.aspect (read-only)
+ The width-to-height aspect ratio of the rectangle. Note that this is often
+ in render target coordinates which don’t necessarily have equal X and Y
+ scales. A rectangle representing a square in the final output doesn’t
+ necessarily have an aspect ratio of 1.
+
+.. _luareference-render-color:
+
+Render colour
+~~~~~~~~~~~~~
+
+Wraps MAME’s ``render_color`` class, which represents an ARGB (alpha, red,
+green, blue) format colour. Channels are floating-point values ranging from
+zero (0, transparent alpha or colour off) to one (1, opaque or full colour
+intensity). Colour channel values are not pre-multiplied by the alpha channel
+value.
+
+Instantiation
+^^^^^^^^^^^^^
+
+emu.render_color()
+ Creates a render colour object representing opaque white (all channels set
+ to 1). This is the identity value – ARGB multiplication by this value will
+ not change a colour.
+emu.render_color(a, r, g, b)
+ Creates a render colour object with the specified alpha, red, green and
+ blue channel values.
+
+ The arguments must all be floating-point numbers in the range from zero (0)
+ to one (1), inclusive.
+
+Methods
+^^^^^^^
+
+color:set(a, r, g, b)
+ Sets the colour object’s alpha, red, green and blue channel values.
+
+ The arguments must all be floating-point numbers in the range from zero (0)
+ to one (1), inclusive.
+
+Properties
+^^^^^^^^^^
+
+color.a (read/write)
+ Alpha value, in the range of zero (0, transparent) to one (1, opaque).
+color.r (read/write)
+ Red channel value, in the range of zero (0, off) to one (1, full intensity).
+color.g (read/write)
+ Green channel value, in the range of zero (0, off) to one (1, full
+ intensity).
+color.b (read/write)
+ Blue channel value, in the range of zero (0, off) to one (1, full
+ intensity).
+
+.. _luareference-render-manager:
+
+Render manager
+~~~~~~~~~~~~~~
+
+Wraps MAME’s ``render_manager`` class, responsible for managing render targets
+and textures.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager:machine():render()
+ Gets the global render manager instance for the emulation session.
+
+Properties
+^^^^^^^^^^
+
+render.max_update_rate (read-only)
+ The maximum update rate in Hertz. This is a floating-point number.
+render.ui_target (read-only)
+ The :ref:`render target <luareference-render-target>` used to draw the user
+ interface (including menus, sliders and pop-up messages). This is usually
+ the first host window or screen.
+render.ui_container (read-only)
+ The :ref:`render container <luareference-render-container>` used for drawing
+ the user interface.
+render.targets[] (read-only)
+ The list of render targets, including output windows and screens, as well as
+ hidden render targets used for things like rendering screenshots. Uses
+ 1-based integer indices. The index operator and the ``at`` method have O(n)
+ complexity.
+
+.. _luareference-render-target:
+
+Render target
+~~~~~~~~~~~~~
+
+Wrap’s MAME’s ``render_target`` class, which represents a video output channel.
+This could be a host window or screen, or a hidden target used for rendering
+screenshots.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager:machine():render().targets[index]
+ Get a render target by index.
+manager:machine():render():ui_target()
+ Get 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.
+
+Properties
+^^^^^^^^^^
+
+target.index (read-only)
+ The 1-based index of the render target. This has O(n) complexity.
+target.width (read-only)
+ The width of the render target in output pixels. This is an integer.
+target.height (read-only)
+ The height of the render target in output pixels. This is an integer.
+target.pixel_aspect (read-only)
+ The width-to-height aspect ratio of the render target’s pixels. This is a
+ floating-point number.
+target.hidden (read-only)
+ A Boolean indicating whether this is an internal render target that is not
+ displayed to the user directly (e.g. the render target used to draw
+ screenshots).
+target.is_ui_target (read-only)
+ A Boolean indicating whether this is the render target used to display the
+ user interface.
+target.max_update_rate (read/write)
+ The maximum update rate for the render target in Hertz.
+target.orientation (read/write)
+ The target orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+target.view_names[]
+ The names of the available views for this render target. Uses 1-based
+ integer indices. The ``find`` and ``index_of`` methods have O(n)
+ complexity; all other supported operations have O(1) complexity.
+target.current_view (read-only)
+ The currently selected view for the render target. This is a
+ :ref:`layout view <luareference-render-layview>` object.
+target.view_index (read/write)
+ The 1-based index of the selected view for this render target.
+target.visibility_mask (read-only)
+ An integer bit mask indicating which item collections are currently visible
+ for the current view.
+target.screen_overlay (read/write)
+ A Boolean indicating whether screen overlays are enabled.
+target.zoom_to_screen (read/write)
+ A Boolean indicating whether the render target is configured to scale so
+ that the emulated screen(s) fill as much of the output window/screen as
+ possible.
+
+.. _luareference-render-container:
+
+Render container
+~~~~~~~~~~~~~~~~
+
+Wraps MAME’s ``render_container`` class.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager:machine():render().ui_container
+ Gets the render container used to draw the user interface, including menus,
+ sliders and pop-up messages.
+manager:machine().screens[tag].container
+ Gets the render container used to draw a given screen.
+
+Properties
+^^^^^^^^^^
+
+container.user_settings (read/write)
+ The container’s :ref:`user settings <luareference-render-contsettings>`.
+ This can be used to control a number of image adjustments.
+container.orientation (read/write)
+ The container orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+container.xscale (read/write)
+ The container’s X scale factor. This is a floating-point number.
+container.yscale (read/write)
+ The container’s Y scale factor. This is a floating-point number.
+container.xoffset (read/write)
+ The container’s X offset. This is a floating-point number where one (1)
+ represents the X size of the container.
+container.yoffset (read/write)
+ The container’s Y offset. This is a floating-point number where one (1)
+ represents the Y size of the container.
+container.is_empty (read-only)
+ A Boolean indicating whether the container has no items.
+
+.. _luareference-render-contsettings:
+
+Container user settings
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Wraps MAME’s ``render_container::user_settings`` class, representing image
+adjustments applied to a
+:ref:`render container <luareference-render-container>`.
+
+Instantiation
+^^^^^^^^^^^^^
+
+manager:machine().screens[tag].container
+ Gets the current container user settings for a given screen.
+
+Properties
+^^^^^^^^^^
+
+settings.orientation (read/write)
+ The container orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+settings.brightness (read/write)
+ The brightness adjustment applied to the container. This is a
+ floating-point number.
+settings.contrast (read/write)
+ The contrast adjustment applied to the container. This is a floating-point
+ number.
+settings.gamma (read/write)
+ The gamma adjustment applied to the container. This is a floating-point
+ number.
+settings.xscale (read/write)
+ The container’s X scale factor. This is a floating-point number.
+settings.yscale (read/write)
+ The container’s Y scale factor. This is a floating-point number.
+settings.xoffset (read/write)
+ The container’s X offset. This is a floating-point number where one (1)
+ represents the X size of the container.
+settings.yoffset (read/write)
+ The container’s Y offset. This is a floating-point number where one (1)
+ represents the Y size of the container.
+
+.. _luareference-render-layfile:
+
+Layout file
+~~~~~~~~~~~
+
+Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
+file for use by a render target.
+
+Instantiation
+^^^^^^^^^^^^^
+
+A layout file object is supplied to its layout script in the ``file`` variable.
+Layout file objects are not instantiated directly from Lua scripts.
+
+Methods
+^^^^^^^
+
+layout:set_resolve_tags_callback(cb)
+ Set a function to perform additional tasks after the emulated machine has
+ finished starting, tags in the layout views have been resolved, and the
+ default view item handlers have been set up. The function must accept no
+ arguments.
+
+ Call with ``nil`` to remove the callback.
+
+Properties
+^^^^^^^^^^
+
+layout.device (read-only)
+ The device that caused the layout file to be loaded. Usually the root
+ machine device for external layouts.
+layout.views[] (read-only)
+ The :ref:`views <luareference-render-layview>` created from the layout file.
+ Views are indexed by unqualified name (i.e. the value of the ``name``
+ attribute). Views are ordered how they appear in the layout file when
+ iterating or using the ``at`` method. The index get, ``at`` and
+ ``index_of`` methods have O(n) complexity.
+
+ Note that not all views in the XML file may be created. For example views
+ that reference screens provided by slot card devices will not be created if
+ said slot card devices are not present in the system.
+
+.. _luareference-render-layview:
+
+Layout view
+~~~~~~~~~~~
+
+Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
+a render target. Views are created from XML layout files, which may be loaded
+from external artwork, internal to MAME, or automatically generated based on the
+screens in the emulated system.
+
+Instantiation
+^^^^^^^^^^^^^
+
+Layout scripts generally
+
+manager:machine():render().targets[index].current_view
+ Gets the currently selected view for a given render target.
+
+Methods
+^^^^^^^
+
+view:has_screen(screen)
+ Returns a Boolean indicating whether the screen is present in the view.
+ This is true for screens that are present but not visible because the user
+ has hidden the item collection they belong to.
+view:set_prepare_items_callback(cb)
+ Set a function to perform additional tasks before the view items are added
+ to the render target in preparation for drawing a video frame. The function
+ must accept no arguments. Call with ``nil`` to remove the callback.
+view:set_preload_callback(cb)
+ Set a function to perform additional tasks after preloading visible view
+ items. The function must accept no arguments. Call with ``nil`` to remove
+ the callback.
+
+ This function may be called when the user selects a view or makes an item
+ collection visible. It may be called multiple times for a view, so avoid
+ repeating expensive tasks.
+view:set_recomputed_callback(cb)
+ Set a function to perform additional tasks after the view’s dimensions are
+ recomputed. The function must accept no arguments. Call with ``nil`` to
+ remove the callback.
+
+ View coordinates are recomputed in various events, including the window
+ being resized, entering or leaving full-screen mode, and changing the zoom
+ to screen area setting.
+
+Properties
+^^^^^^^^^^
+
+view.items[] (read-only)
+ The screen and layout element :ref:`items <luareference-render-layitem>` in
+ the view. This container does not support iteration by key using ``pairs``;
+ only iteration by index using ``ipairs`` is supported. The key is the value
+ of the ``id`` attribute if present. Only items with ``id`` attributes can
+ be looked up by key. The index get method has O(1) complexity, and the
+ ``at`` and ``index_of`` methods have O(n) complexity.
+view.name (read-only)
+ The display name for the view. This may be qualified to indicate the device
+ that caused the layout file to be loaded when it isn’t the root machine
+ device.
+view.unqualified_name (read-only)
+ The unqualified name of the view, exactly as it appears in the ``name``
+ attribute in the XML layout file.
+view.visible_screen_count (read-only)
+ The number of screens items currently enabled in the view.
+view.effective_aspect (read-only)
+ The effective width-to-height aspect ratio of the view in its current
+ configuration.
+view.bounds (read-only)
+ A :ref:`render bounds <luareference-render-bounds>` object representing the
+ effective bounds of the view in its current configuration. The coordinates
+ are in view units, which are arbitrary but assumed to have square aspect
+ ratio.
+view.has_art
+ A Boolean indicating whether the view has any non-screen items, including
+ items that are not visible because the user has hidden the item collection
+ that they belong to.
+
+.. _luareference-render-layitem:
+
+Layout view item
+~~~~~~~~~~~~~~~~
+
+Wraps MAME’s ``layout_view::item`` class, representing an item in a view. An
+item is drawn as a rectangular textured surface. The texture is supplied by an
+emulated screen or a layout element.
+
+Instantiation
+^^^^^^^^^^^^^
+
+layout.views[name].items[id]
+ Get a view item by ID. The item must have an ``id`` attribute in the XML
+ layout file to be looked up by ID.
+
+Methods
+^^^^^^^
+
+item:set_state(state)
+ Set the value used as the element state and animation state in the absence
+ of bindings. The argument must be an integer.
+item.set_element_state_callback(cb)
+ Set a function to call to obtain the element state for the item. The
+ function must accept no arguments and return an integer. Call with ``nil``
+ to restore the default element state callback (based on bindings in the XML
+ layout file).
+
+ Note that the function must not access the item’s ``element_state``
+ property, as this will result in infinite recursion.
+
+ This callback will not be used to obtain the animation state for the item,
+ even if the item lacks explicit animation state bindings in the XML layout
+ file.
+item.set_animation_state_callback(cb)
+ Set a function to call to obtain the animation state for the item. The
+ function must accept no arguments and return an integer. Call with ``nil``
+ to restore the default animation state callback (based on bindings in the
+ XML layout file).
+
+ Note that the function must not access the item’s ``animation_state``
+ property, as this will result in infinite recursion.
+item.set_bounds_callback(cb)
+ Set a function to call to obtain the bounds for the item. The function must
+ accept no arguments and return a
+ :ref:`render bounds <luareference-render-bounds>` object in render target
+ coordinates. Call with ``nil`` to restore the default bounds callback
+ (based on the item’s animation state and ``bounds`` child elements in the
+ XML layout file).
+
+ Note that the function must not access the item’s ``bounds`` property, as
+ this will result in infinite recursion.
+item.set_color_callback(cb)
+ Set a function to call to obtain the multiplier colour for the item. The
+ function must accept no arguments and return a
+ :ref:`render colour <luareference-render-color>` object. Call with ``nil``
+ to restore the default colour callback (based on the item’s animation state
+ and ``color`` child elements in the XML layout file).
+
+ Note that the function must not access the item’s ``color`` property, as
+ this will result in infinite recursion.
+
+Properties
+^^^^^^^^^^
+
+item.id (read-only)
+ Get the optional item identifier. This is the value of the ``id`` attribute
+ in the XML layout file if present, or ``nil``.
+item.bounds_animated (read-only)
+ A Boolean indicating whether the item’s bounds depend on its animation
+ state.
+item.color_animated (read-only)
+ A Boolean indicating whether the item’s colour depends on its animation
+ state.
+item.bounds (read-only)
+ The item’s bounds for the current state. This is a
+ :ref:`render bounds <luareference-render-bounds>` object in render target
+ coordinates.
+item.color (read-only)
+ The item’s colour for the current state. The colour of the screen or
+ element texture is multiplied by this colour. This is a
+ :ref:`render colour <luareference-render-color>` object.
+item.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.