summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2023-10-30 03:11:15 +1100
committer Vas Crabb <vas@vastheman.com>2023-10-30 03:11:15 +1100
commite4ceeee56741ebf1e72c2d2a33f94dfa1d251c11 (patch)
treed520a5fe0f93db9016bedae33a46dab2e3a893a6 /docs/source
parent08a9011cfba71c153a2c958328545408f9c1b00e (diff)
Added some additional layout functionality and script bindings.
Also corrected some copy/paste errors in documentation, and bumped documentation version as it now describes features that will appear in an upcoming release.
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/conf.py4
-rw-r--r--docs/source/luascript/ref-render.rst69
2 files changed, 63 insertions, 10 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5a8c585f694..d0227f52c06 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -63,9 +63,9 @@ copyright = u'1997-2023, MAMEdev and contributors'
# built documents.
#
# The short X.Y version.
-version = '0.260'
+version = '0.261'
# The full version, including alpha/beta/rc tags.
-release = '0.260'
+release = '0.261'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/source/luascript/ref-render.rst b/docs/source/luascript/ref-render.rst
index f10f8710e26..265e52b5016 100644
--- a/docs/source/luascript/ref-render.rst
+++ b/docs/source/luascript/ref-render.rst
@@ -480,10 +480,9 @@ emu.bitmap_yuy16(source, [x0, y0, x1, y1])
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.
+ Creates an RGB format 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,
@@ -496,10 +495,10 @@ emu.bitmap_rgb32(source, [x0, y0, x1, y1])
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.
+ Creates an ARGB format 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,
@@ -619,6 +618,12 @@ 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.
+bitmap:resample(dest, [color])
+ Copies the bitmap into the destination bitmap, scaling to fill the
+ destination bitmap and using a re-sampling filter. Only ARGB format source
+ and destination bitmaps are supported. The source pixel values will be
+ multiplied by the colour if it is supplied. It must be a
+ :ref:`render colour <luascript-ref-rendercolor>`.
Properties
~~~~~~~~~~
@@ -987,6 +992,11 @@ Properties
layout.device (read-only)
The device that caused the layout file to be loaded. Usually the root
machine device for external layouts.
+layout.elements[] (read-only)
+ The :ref:`elements <luascript-ref-renderlayelem>` created from the layout
+ file. Elements are indexed by name (i.e. the value of the ``name``
+ attribute). The index get method has O(1) complexity, and the ``at`` and
+ ``index_of`` methods have O(n) complexity.
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``
@@ -1194,6 +1204,9 @@ 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.element (read-only)
+ The :ref:`element <luascript-ref-renderlayelem>` used to draw the item, or
+ ``nil`` for screen items.
item.bounds_animated (read-only)
A Boolean indicating whether the item’s bounds depend on its animation
state.
@@ -1246,3 +1259,43 @@ item.element_state (read-only)
item.animation_state (read-only)
Get the current animation state. This will call the animation state
callback function to handle bindings.
+
+
+.. _luascript-ref-renderlayelem:
+
+Layout element
+--------------
+
+Wraps MAME’s ``layout_element`` class, representing a visual element that can be
+drawn in a :ref:`layout view <luascript-ref-renderlayview>`. Elements are
+created from XML layout files, which may be loaded from external artwork or
+internal to MAME. Note that layout element callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+layout.elements[name]
+ Gets a layout element by name.
+layout.views[name].items[id].element
+ Gets the layout element used to draw a
+ :ref:`view item <luascript-ref-renderlayitem>`.
+
+Methods
+~~~~~~~
+
+element:invalidate()
+ Invalidate all cached textures for the element, ensuring it will be redrawn
+ when the next video frame is drawn.
+element.set_draw_callback(cb)
+ Set a function to call the perform additional drawing after the element’s
+ components have been drawn. The function is passed two arguments: the
+ element state (an integer) and the 32-bit ARGB
+ :ref:`bitmap <luascript-ref-bitmap>` at the required size. The function
+ must not attempt to resize the bitmap. Call with ``nil`` to remove the
+ callback.
+
+Properties
+~~~~~~~~~~
+
+element.default_state (read-only)
+ The integer default state for the element if set or ``nil``.