summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2021-11-18 10:34:38 +1100
committer Vas Crabb <vas@vastheman.com>2021-11-18 10:34:38 +1100
commit5afce6cfab6320ee062da5f7b7438294672f9af1 (patch)
tree5902ddf0b74f27e3d43bc0556dcfd29198e86efd /docs/source/techspecs
parentded9ecfc1cf7864f206b92480eaebf32092ef8f2 (diff)
emu/render.cpp, emu/rendlay.cpp: Added scroll support for all elements.
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r--docs/source/techspecs/layout_files.rst57
-rw-r--r--docs/source/techspecs/layout_script.rst64
-rw-r--r--docs/source/techspecs/luareference.rst76
3 files changed, 178 insertions, 19 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index be4965a9e95..c43a7df8e1b 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -406,8 +406,8 @@ usually comes from an I/O port field or an emulated output (see
:ref:`layfile-interact-elemstate` for information on connecting an element to an
emulated I/O port or output). Any component of an element may be restricted to
only drawing when the element’s state is a particular value. Some components
-(e.g. multi-segment displays and reels) use the state directly to determine
-their appearance.
+(e.g. multi-segment displays) use the state directly to determine their
+appearance.
Each element has its own internal coordinate system. The bounds of the
element’s coordinate system are computed as the union of the bounds of the
@@ -591,10 +591,6 @@ simplecounter
to set text alignment. If present, the ``align`` attribute must be an
integer, where 0 (zero) means centred, 1 (one) means left-aligned, and 2
(two) means right-aligned; if absent, the text will be centred.
-reel
- Used for drawing slot machine reels. Supported attributes include
- ``symbollist``, ``stateoffset``, ``numsymbolsvisible``, ``reelreversed``,
- and ``beltreel``.
An example element that draws a static left-aligned text string:
@@ -839,6 +835,48 @@ have their colour and position/size animated by supplying multiple ``color``
and/or ``bounds`` child elements with ``state`` attributes. See
:ref:`layfile-interact-itemanim` for details.
+Layout elements (``element`` elements) may be configured to show only part of
+the element’s width or height using ``xscroll`` and/or ``yscroll`` child
+elements. This can be used for devices like slot machine reels. The
+``xscroll`` and ``yscroll`` elements support the same attributes:
+
+size
+ The size of the horizontal or vertical scroll window, as a proportion of the
+ element’s width or height, respectively. Must be in the range 0.01 to 1.0,
+ inclusive, if present (1% of the width/height to the full width/height). By
+ default, the entire width and height of the element is shown.
+wrap
+ Whether the element should wrap horizontally or vertically. Must be either
+ ``yes`` or ``no`` if present. By default, items do not wrap horizontally or
+ vertically.
+inputtag
+ If present, the horizontal or vertical scroll position will be taken from
+ the value of the corresponding I/O port. Specifies the tag path of an I/O
+ port relative to the device that caused the layout file to be loaded. The
+ raw value from the input port is used, active-low switch values are not
+ normalised.
+name
+ If present, the horizontal or vertical scroll position will be taken from
+ the correspondingly named output.
+mask
+ If present, the horizontal or vertical scroll position will be masked with
+ the value and shifted to the right to remove trailing zeroes (for example a
+ mask of 0x05 will result in no shift, while a mask of 0x68 will result in
+ the value being shifted three bits to the right). Note that this applies to
+ output values (specified with the ``name`` attribute) as well as input port
+ values (specified with the ``inputtag`` attribute). Must be an integer
+ value if present. If not present, it is equivalent to all 32 bits being
+ set.
+min
+ Minimum horizontal or vertical scroll position value. When the horizontal
+ or vertical scroll position has this value, the left or top edge or the
+ scroll window will be aligned with the left or top edge of the element.
+ Must be an integer value if present. Defaults to zero.
+max
+ Maximum horizontal or vertical scroll position value. Must be an integer
+ value if present. Defaults to the ``mask`` value shifted to the right to
+ remove trailing zeroes.
+
.. _layfile-parts-collections:
@@ -1149,9 +1187,8 @@ Clickable items
item will activate the emulated switch.
State-dependent components
Some components will be drawn differently depending on the containing
- element’s state. These include the dot matrix, multi-segment LED display,
- simple counter and reel elements. See :ref:`layfile-parts-elements` for
- details.
+ element’s state. These include the dot matrix, multi-segment LED display
+ and simple counter elements. See :ref:`layfile-parts-elements` for details.
Conditionally-drawn components
Components may be conditionally drawn or hidden depending on the containing
element’s state by supplying ``state`` and/or ``statemask`` attributes. See
@@ -1298,7 +1335,7 @@ If the ``animate`` child element has a ``mask`` attribute, the item’s animatio
state will be masked with the ``mask`` value and shifted to the right to remove
trailing zeroes (for example a mask of 0x05 will result in no shift, while a
mask of 0xb0 will result in the value being shifted four bits to the right).
-Note that the ``mask`` attribute applies to output value (specified with the
+Note that the ``mask`` attribute applies to output values (specified with the
``name`` attribute) as well as input port values (specified with the
``inputtag`` attribute). If the ``mask`` attribute is present, it must be an
integer value. If the ``mask`` attribute is not present, it is equivalent to
diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst
index 7602de6f7f4..f2b8ef1cbc3 100644
--- a/docs/source/techspecs/layout_script.rst
+++ b/docs/source/techspecs/layout_script.rst
@@ -259,7 +259,7 @@ Here’s our layout file:
<bounds x="0" y="0" width="0.1" height="0.1" />
<color alpha="0" />
</rect>
- <!-- draw the outlined of a square -->
+ <!-- draw the outline 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>
@@ -289,7 +289,7 @@ Here’s our layout file:
<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 -->
+ <!-- centre it in the square horizontally, using the full height -->
<bounds x="4.55" y="1.9" width="0.1" height="1" />
</element>
@@ -301,7 +301,7 @@ Here’s our layout file:
<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 -->
+ <!-- draw a small box at the intersection of the vertical and horizontal lines -->
<element id="box" ref="box">
<bounds x="4.55" y="2.35" width="0.1" height="0.1" />
</element>
@@ -595,7 +595,7 @@ Get item bounds
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)``
+ ``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``
@@ -605,3 +605,59 @@ Get item colour
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).
+Get item horizontal scroll window size
+ ``item:set_scroll_size_x_callback(cb)``
+
+ Set callback for getting the item’s horizontal scroll window size. This
+ allows the script to control how much of the element is displayed by the
+ item. Do not attempt to access the item’s ``scroll_size_x`` property from
+ the callback, as it will result in infinite recursion.
+
+ The callback function must return a floating-point number representing the
+ horizontal window size as a proportion of the associated element’s width,
+ and takes no parameters. A value of 1.0 will display the entire width of
+ the element; smaller values will display proportionally smaller parts of the
+ element. Call with ``nil`` as the argument to to restore the default
+ horizontal scroll window size handler (based on the ``xscroll`` child
+ element).
+Get item vertical scroll window size
+ ``item:set_scroll_size_y_callback(cb)``
+
+ Set callback for getting the item’s vertical scroll window size. This
+ allows the script to control how much of the element is displayed by the
+ item. Do not attempt to access the item’s ``scroll_size_y`` property from
+ the callback, as it will result in infinite recursion.
+
+ The callback function must return a floating-point number representing the
+ vertical window size as a proportion of the associated element’s height, and
+ takes no parameters. A value of 1.0 will display the entire height of the
+ element; smaller values will display proportionally smaller parts of the
+ element. Call with ``nil`` as the argument to to restore the default
+ vertical scroll window size handler (based on the ``xscroll`` child
+ element).
+Get item horizontal scroll position
+ ``item:set_scroll_pos_x_callback(cb)``
+
+ Set callback for getting the item’s horizontal scroll position. This allows
+ the script to control which part of the element is displayed by the item.
+ Do not attempt to access the item’s ``scroll_pos_x`` property from the
+ callback, as this will result in infinite recursion.
+
+ The callback must return a floating-point number, and takes no parameters.
+ A value of 0.0 aligns the left edge of the element with the left edge of the
+ item; larger values pan right. Call with ``nil`` as the argument to restore
+ the default horizontal scroll position handler (based on bindings in the
+ ``xscroll`` child element).
+Get item vertical scroll position
+ ``item:set_scroll_pos_y_callback(cb)``
+
+ Set callback for getting the item’s vertical scroll position. This allows
+ the script to control which part of the element is displayed by the item.
+ Do not attempt to access the item’s ``scroll_pos_y`` property from the
+ callback, as this will result in infinite recursion.
+
+ The callback must return a floating-point number, and takes no parameters.
+ A value of 0.0 aligns the top edge of the element with the top edge of the
+ item; larger values pan down. Call with ``nil`` as the argument to restore
+ the default vertical scroll position handler (based on bindings in the
+ ``yscroll`` child element).
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index 3cea683f547..85c7ea8cb8a 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -2815,7 +2815,7 @@ view.has_art
Layout view item
~~~~~~~~~~~~~~~~
-Wraps MAME’s ``layout_view::item`` class, representing an item in a view. An
+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.
@@ -2832,7 +2832,7 @@ 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)
+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
@@ -2844,7 +2844,7 @@ item.set_element_state_callback(cb)
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)
+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
@@ -2852,7 +2852,7 @@ item.set_animation_state_callback(cb)
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)
+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
@@ -2862,7 +2862,7 @@ item.set_bounds_callback(cb)
Note that the function must not access the item’s ``bounds`` property, as
this will result in infinite recursion.
-item.set_color_callback(cb)
+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``
@@ -2871,6 +2871,50 @@ item.set_color_callback(cb)
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
^^^^^^^^^^
@@ -2892,6 +2936,28 @@ 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.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